Contacts

Contacts represent individual email subscribers. They can belong to one or more audiences and can be individually suppressed or unsubscribed.

---

Create contact

POST /v1/contacts

Requires full_access scope.

Request body

{
  "email": "alice@example.com",
  "first_name": "Alice",
  "last_name": "Smith",
  "metadata": {"plan": "pro", "source": "signup"}
}

Field	Type	Required	Description
email	string	Yes	Contact's email address.
first_name	string	No	First name.
last_name	string	No	Last name.
metadata	Record<string, any>	No	Arbitrary key/value data.

Response

{
  "id": "con_abc123",
  "email": "alice@example.com",
  "first_name": "Alice",
  "last_name": "Smith",
  "metadata": {"plan": "pro"},
  "subscribed": true,
  "created_at": "2025-03-12T09:00:00Z"
}

---

Get contact

GET /v1/contacts/:id

Requires read_only scope.

---

List contacts

GET /v1/contacts

Requires read_only scope.

Query parameters

Parameter	Type	Default	Description
limit	number	50	Results per page (1–100).
cursor	string		Pagination cursor.

---

Update contact

PATCH /v1/contacts/:id

Requires full_access scope.

---

Delete contact

DELETE /v1/contacts/:id

Requires full_access scope. Permanently removes the contact.

---

Bulk import contacts

POST /v1/contacts/import

Requires full_access scope. Import up to 1,000 contacts in a single request. The import checks your plan's contact limit before inserting — if the batch would exceed your limit, the entire import is rejected.

Request body

{
  "contacts": [
    {"email": "alice@example.com", "first_name": "Alice"},
    {"email": "bob@example.com", "first_name": "Bob"}
  ]
}

Response

{
  "imported": 2,
  "skipped": 0,
  "errors": []
}

---

Plan limits

Plan	Contacts
Free	500
Pro	10,000
Business	100,000
Enterprise	Unlimited

---

Suppression and unsubscribes

Contacts who unsubscribe or hard-bounce are automatically added to the suppression list. Attempting to send to a suppressed address returns an error.

See the suppression endpoints for manual management:

• GET /v1/suppression — list suppressed addresses
• POST /v1/suppression — add a suppression
• DELETE /v1/suppression/:email — remove a suppression

Unsubscribe management:

• GET /v1/unsubscribes — list all unsubscribes
• POST /v1/unsubscribes — add an unsubscribe
• DELETE /v1/unsubscribes/:id — remove an unsubscribe