Skip to main content

​
Key Concepts

Audiences

Lists of contacts grouped by purpose. E.g., Newsletter subscribers, Product updates, etc.

Contacts

Individual subscribers with email addresses and custom properties.

Properties

Custom fields on contacts for personalization and segmentation.

​
Creating an Audience

Create an audience to group your contacts:
cURL
curl -X POST https://www.unosend.co/api/v1/audiences \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Subscribers",
    "description": "Users who signed up for our weekly newsletter"
  }'

​
Response

response.json
{
  "id": "aud_xxxxxxxxxxxxxxxx",
  "name": "Newsletter Subscribers",
  "description": "Users who signed up for our weekly newsletter",
  "contact_count": 0,
  "created_at": "2024-01-15T10:30:00Z"
}

​
Adding Contacts

​
Single Contact

cURL
curl -X POST https://www.unosend.co/api/v1/contacts \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_id": "aud_xxxxxxxxxxxxxxxx",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "properties": {
      "company": "Acme Inc",
      "role": "Developer",
      "signup_date": "2024-01-15",
      "plan": "pro"
    }
  }'

​
Response

response.json
{
  "id": "ctc_xxxxxxxxxxxxxxxx",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "properties": {
    "company": "Acme Inc",
    "role": "Developer",
    "signup_date": "2024-01-15",
    "plan": "pro"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

​
Adding Multiple Contacts

To add multiple contacts, make individual POST requests to /api/v1/contacts or use the dashboard’s CSV import feature for bulk imports.

​
Bulk Operations

Perform bulk operations on existing contacts:

​
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": ["ctc_xxx1", "ctc_xxx2", "ctc_xxx3"],
    "operation": "delete"
  }'

​
Bulk Subscribe/Unsubscribe

cURL
# Unsubscribe multiple contacts
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": ["ctc_xxx1", "ctc_xxx2"],
    "operation": "unsubscribe"
  }'

# Re-subscribe contacts
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": ["ctc_xxx1", "ctc_xxx2"],
    "operation": "subscribe"
  }'

​
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": ["ctc_xxx1", "ctc_xxx2", "ctc_xxx3"],
    "operation": "move",
    "audience_id": "aud_new_audience_id"
  }'

​
Bulk Operation Response

response.json
{
  "operation": "delete",
  "affected": 3,
  "skipped": 0,
  "message": "Successfully deleted 3 contact(s)"
}

​
Contact Properties

Store custom data on contacts for personalization:
properties-example.json
{
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Smith",
  "properties": {
    "company": "Tech Corp",
    "job_title": "Product Manager",
    "signup_date": "2024-01-15",
    "last_purchase": "2024-03-20",
    "lifetime_value": 1500,
    "order_count": 12,
    "is_premium": true,
    "newsletter_opted_in": true,
    "interests": ["technology", "design", "marketing"]
  }
}

​
Update Properties

cURL
curl -X PATCH https://www.unosend.co/api/v1/contacts/ctc_xxxxxxxx \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "plan": "enterprise",
      "lifetime_value": 5000,
      "last_purchase": "2024-03-25"
    }
  }'
Properties are merged, not replaced. Existing properties not included are preserved.

​
Listing & Searching Contacts

​
List Contacts in Audience

cURL
curl "https://www.unosend.co/api/v1/contacts?audience_id=aud_xxxxxxxx&limit=100&offset=0" \
  -H "Authorization: Bearer un_your_api_key"

​
Response

response.json
{
  "contacts": [
    {
      "id": "ctc_xxxxxxxx",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "properties": { "plan": "pro" }
    }
  ],
  "total": 150,
  "has_more": true
}

​
Get a Specific Contact

cURL
curl https://www.unosend.co/api/v1/contacts/ctc_xxxxxxxx \
  -H "Authorization: Bearer un_your_api_key"

​
Managing Unsubscribes

Contacts can unsubscribe from audiences. We automatically handle unsubscribe links in your emails:
cURL
# Manually unsubscribe a contact
curl -X PATCH https://www.unosend.co/api/v1/contacts/ctc_xxxxxxxx \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "unsubscribed": true
  }'

# Re-subscribe (only if they have opted in again)
curl -X PATCH https://www.unosend.co/api/v1/contacts/ctc_xxxxxxxx \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "unsubscribed": false
  }'
Automatic Unsubscribe Links: We automatically add unsubscribe links to your emails if you use the {{unsubscribe_url}} variable in your templates.

​
Best Practices

  • ✓ Organize with audiences - Create separate audiences for different purposes
  • ✓ Use properties - Store relevant data for personalization
  • ✓ Handle unsubscribes - Never re-add unsubscribed contacts without explicit consent
  • ✓ Clean your lists - Remove bounced emails and inactive contacts regularly
  • ✓ Double opt-in - Confirm subscriptions to maintain a quality list