Managing Contacts

Contacts are organized into lists. Before adding contacts, you need at least one list.

Create a list

curl -X POST https://api.cakemail.dev/lists \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Newsletter Subscribers"}'

The response includes a list_id you'll use for all contact operations.

Add a contact

curl -X POST https://api.cakemail.dev/lists/{list_id}/contacts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "subscriber@example.com"}'

List contacts

curl "https://api.cakemail.dev/lists/{list_id}/contacts?page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use page and per_page for pagination. Results are sorted by creation date.

Update a contact

curl -X PATCH https://api.cakemail.dev/lists/{list_id}/contacts/{contact_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"custom_attributes": [{"name": "first_name", "value": "Jane"}]}'

Delete a contact

curl -X DELETE https://api.cakemail.dev/lists/{list_id}/contacts/{contact_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Accept anti-spam policy

You must accept the anti-spam policy for a list before you can send to it. This is a one-time step per list.

curl -X POST https://api.cakemail.dev/lists/{list_id}/accept-policy \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Import contacts in bulk

Import up to 1,000 contacts per request using the import endpoint:

curl -X POST https://api.cakemail.dev/lists/{list_id}/contacts/import \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contacts": [{"email": "alice@example.com"}, {"email": "bob@example.com"}]}'

For larger lists, split your contacts into batches of 1,000 and send multiple requests.

Unsubscribe a contact

curl -X POST https://api.cakemail.dev/lists/{list_id}/contacts/{contact_id}/unsubscribe \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Filtering and pagination

When listing contacts, use query parameters to control results:

page — page number (starts at 1)
per_page — number of results per page
sort — sort field and direction (e.g. email:asc)
filter — filter by field value (e.g. status:active)

curl "https://api.cakemail.dev/lists/{list_id}/contacts?page=1&per_page=50&sort=email:asc&filter=status:active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Using MCP

With the Execution MCP connected, your AI assistant can manage contacts directly:

contacts tool with operation list — list contacts in a list
contacts tool with operation create — add a new contact
tags tool with operation list — browse available tags

See MCP Servers for connection instructions.