Contacts

The Contacts API allows you to manage contacts and contact books for your email campaigns.

Base URL

https://api.unsent.dev/v1/contactBooks

Features

Contact management

Create, read, update, and delete contacts

Contact books

Organize contacts into logical groups

Custom properties

Store additional data for personalization

Subscription management

Handle opt-in/opt-out preferences

Bulk operations

Manage multiple contacts efficiently

Upsert operations

Create or update contacts in one call

Quick Start

Create a new contact

curl -X POST https://api.unsent.dev/v1/contactBooks/{contactBookId}/contacts \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "subscribed": true,
    "properties": {
      "company": "Acme Corp",
      "phone": "+1-555-0123",
      "source": "newsletter_signup"
    }
  }'

List contacts from a contact book

curl -X GET "https://api.unsent.dev/v1/contactBooks/{contactBookId}/contacts?page=1&limit=50" \
  -H "Authorization: Bearer your-api-key"

Update a contact

curl -X PATCH https://api.unsent.dev/v1/contactBooks/{contactBookId}/contacts/{contactId} \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Johnathan",
    "properties": {
      "last_purchase": "2024-01-15",
      "tier": "premium"
    }
  }'

Upsert a contact (create or update)

curl -X PUT https://api.unsent.dev/v1/contactBooks/{contactBookId}/contacts \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "subscribed": true,
    "properties": {
      "source": "website_signup",
      "interests": ["technology", "marketing"]
    }
  }'

API Endpoints

Data Model

Contact Fields

email (required) - The contact's email address
firstName - Contact's first name
lastName - Contact's last name
subscribed - Subscription status (default: true)
properties - Custom key-value pairs for additional data

Custom Properties

Store any additional information as custom properties:

{
  "properties": {
    "company": "Acme Corp",
    "phone": "+1-555-0123",
    "country": "United States",
    "signup_date": "2024-01-01",
    "interests": ["marketing", "technology"],
    "customer_tier": "premium"
  }
}

Subscription Management

Opt-in Management

subscribed: true - Contact can receive emails
subscribed: false - Contact will not receive emails

Best Practices

Always collect explicit consent before adding contacts
Provide clear unsubscribe options in your emails
Respect subscription preferences at all times
Keep contact data up to date with regular updates
Use custom properties for personalization

Common Use Cases

{
  "email": "subscriber@example.com",
  "firstName": "Jane",
  "subscribed": true,
  "properties": {
    "source": "website_form",
    "interests": ["technology", "business"],
    "signup_date": "2024-01-15"
  }
}

Customer Management

{
  "email": "customer@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "properties": {
    "customer_id": "CUST_12345",
    "tier": "premium",
    "last_purchase": "2024-01-10",
    "total_orders": 15
  }
}

Event Attendees

{
  "email": "attendee@example.com",
  "firstName": "Sarah",
  "properties": {
    "event_id": "EVENT_2024",
    "ticket_type": "VIP",
    "dietary_restrictions": "vegetarian"
  }
}

Rate Limits

Contact operations: 500 requests per minute
Bulk contact retrieval: 100 requests per minute
Contact book operations: 100 requests per minute