Command Palette

Search for a command to run...

Guide

Audiences & Contacts

Learn how to manage your subscribers, organize contacts into audiences, and send targeted emails to specific segments.

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": "john@example.com",
    "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": "john@example.com",
  "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": "user@example.com",
  "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"
    }
  }'

Note: 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": "john@example.com",
      "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"

Sending to an Audience

Send a broadcast email to all contacts in an audience:

cURL
curl -X POST https://www.unosend.co/api/v1/broadcasts \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_id": "aud_xxxxxxxxxxxxxxxx",
    "from": "hello@yourdomain.com",
    "subject": "Weekly Newsletter - March Edition",
    "template_id": "tpl_xxxxxxxxxxxxxxxx",
    "scheduled_at": "2024-03-25T09:00:00Z"
  }'

Response

response.json
{
  "id": "brd_xxxxxxxxxxxxxxxx",
  "audience_id": "aud_xxxxxxxxxxxxxxxx",
  "status": "scheduled",
  "recipient_count": 1500,
  "scheduled_at": "2024-03-25T09:00:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

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.

Segmentation

Target specific contacts based on their properties using filters:

cURL
# Send to premium users only
curl -X POST https://www.unosend.co/api/v1/broadcasts \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_id": "aud_xxxxxxxxxxxxxxxx",
    "from": "hello@yourdomain.com",
    "subject": "Exclusive Premium Feature Update",
    "template_id": "tpl_xxxxxxxxxxxxxxxx",
    "filters": {
      "properties": {
        "is_premium": true
      }
    }
  }'

Complex Filters

filters.json
{
  "filters": {
    "properties": {
      "plan": ["pro", "enterprise"],
      "order_count": { "gte": 5 },
      "is_premium": true
    }
  }
}

Best Practices

Organize with audiences - Create separate audiences for different purposes (newsletter, product updates, etc.)

Use properties - Store relevant data for personalization and segmentation

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