Skip to main content

​
Create a Contact

POST/v1/contacts
Add a new contact to your organization, optionally assigning them to an audience.

​
Request Body

​
email
string
required
Email address
​
first_name
string
First name
​
last_name
string
Last name
​
audience_id
string
UUID of the audience to add the contact to
​
subscribed
boolean
Subscription status (default: true)
​
metadata
object
Custom 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"
}

​
List Contacts

GET/v1/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"
    }
  ]
}

​
Update a Contact

PATCH/v1/contacts/:id
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 a Contact

DELETE/v1/contacts/:id
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"

​
Bulk Operations

POST/v1/contacts/bulk
Perform bulk operations on multiple contacts at once.

​
Request Body

​
contact_ids
string[]
required
Array of contact UUIDs
​
operation
string
required
One of: delete, subscribe, unsubscribe, move
​
audience_id
string
Target 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)"
}