Command Palette

Search for a command to run...

API Reference

Contacts

Manage contacts within your audiences. Add, update, and remove contacts from your mailing lists.

POST/v1/contacts

Create a Contact

Add a new contact to your organization, optionally assigning them to an audience.

Request Body

ParameterTypeRequiredDescription
emailstringRequiredEmail address
first_namestringOptionalFirst name
last_namestringOptionalLast name
audience_idstringOptionalUUID of the audience to add the contact to
subscribedbooleanOptionalSubscription status (default: true)
metadataobjectOptionalCustom key-value data
cURL
curl -X POST https://www.unosend.co/api/v1/contacts \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "audience_id": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": {
      "plan": "pro",
      "signup_source": "website"
    }
  }'

Response

201 Created
{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "audience_id": "550e8400-e29b-41d4-a716-446655440000",
  "subscribed": true,
  "metadata": {
    "plan": "pro",
    "signup_source": "website"
  },
  "created_at": "2024-01-15T10:30:00.000Z"
}
GET/v1/contacts

List Contacts

Get a paginated list of contacts. Optionally filter by audience.

Query Parameters

ParameterTypeDescription
audience_idstringFilter contacts by audience
limitnumberMax results to return (default: 50, max: 100)
offsetnumberNumber of results to skip (default: 0)
cURL
curl "https://www.unosend.co/api/v1/contacts?audience_id=550e8400-e29b-41d4-a716-446655440000&limit=50" \
  -H "Authorization: Bearer un_your_api_key"

Response

200 OK
{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "audience_id": "550e8400-e29b-41d4-a716-446655440000",
      "subscribed": true,
      "metadata": { "plan": "pro" },
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}
PATCH/v1/contacts/:id

Update a Contact

Update contact details. Only provided fields will be updated.

cURL
curl -X PATCH https://www.unosend.co/api/v1/contacts/770e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "metadata": {
      "plan": "enterprise"
    }
  }'
DELETE/v1/contacts/:id

Delete a Contact

Permanently delete a contact. This action cannot be undone.

cURL
curl -X DELETE https://www.unosend.co/api/v1/contacts/770e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer un_your_api_key"
POST/v1/contacts/bulk

Bulk Operations

Perform bulk operations on multiple contacts at once.

Request Body

ParameterTypeRequiredDescription
contact_idsstring[]RequiredArray of contact UUIDs
operationstringRequiredOne of: delete, subscribe, unsubscribe, move
audience_idstringFor moveTarget audience UUID (required for move operation)

Bulk Delete

cURL
curl -X POST https://www.unosend.co/api/v1/contacts/bulk \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": ["id1", "id2", "id3"],
    "operation": "delete"
  }'

Bulk Subscribe/Unsubscribe

cURL
curl -X POST https://www.unosend.co/api/v1/contacts/bulk \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": ["id1", "id2"],
    "operation": "unsubscribe"
  }'

Move to Different Audience

cURL
curl -X POST https://www.unosend.co/api/v1/contacts/bulk \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": ["id1", "id2", "id3"],
    "operation": "move",
    "audience_id": "new-audience-uuid"
  }'

Response

200 OK
{
  "operation": "delete",
  "affected": 3,
  "skipped": 0,
  "message": "Successfully deleted 3 contact(s)"
}