Contact

Manage contacts within lists. Contacts are individual email subscribers with an email address, subscription status, custom attributes, tags, and interests. Supports creating, importing, updating, unsubscribing, and deleting contacts. Bulk operations are available for tagging and interest management. Contact data can be exported to CSV files.

Add interest(s) to contact(s)

POST

https://api.cakemail.dev

/lists/{list_id}/contacts/add-interests

Add interests to multiple contacts at once. Contacts can be specified by ID list or by a filter query. Interests are used for preference-based segmentation.

Required scope(s): contacts:write

Add interest(s) to contact(s) › path Parameters

list_id

integer · min: 1 · required

Add interest(s) to contact(s) › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Add interest(s) to contact(s) › Request Body

AddInterestsToContacts

interests

string[] · maxItems: 16 · required

contact_ids

integer[] · min: 1 · maxItems: 1024

query

string

fiql

string

json

object

Add interest(s) to contact(s) › Responses

Successful Response

AddInterestsToMultipleContactsResponse

object

string

Object type

Default: interests

added

boolean

Whether interests were added

Default: true

Show contacts of a list

GET

https://api.cakemail.dev

/lists/{list_id}/contacts

List all contacts in a list with pagination. Supports filtering by contact attributes using SQL-like queries, FIQL, or JSON query format. Results can be sorted by email, status, or subscription date.

Required scope(s): contacts:read

Show contacts of a list › path Parameters

list_id

integer · min: 1 · required

Show contacts of a list › query Parameters

query

string

SQL selection query (only use one of query, fiql and json)

json

string · json-string

JSON selection expression (only use one of query, fiql and json)

cursor

string

Cursor pagination

account_id

integer · min: 1

Optional Account ID to be used for the request

page

integer · min: 1

Default: 1

per_page

integer · min: 1

Default: 50

with_count

boolean

Include count in the response

Default: false

sort

string

Sort term and direction, using syntax [-|+]term.

Valid terms:

id
email
status
subscribed_on
last_bounce_type
bounces_count

Sort term and direction, using syntax [-|+]term.

Valid terms:

id
email
status
subscribed_on
last_bounce_type
bounces_count

filter

string

Valid Terms:

status
email
tags
interests

Valid Operators:

==

Query separator:

Valid Terms:

status
email
tags
interests

Valid Operators:

==

Query separator:

fiql

string

Show contacts of a list › Responses

Successful Response

ContactsResponse

PaginationWithCursor · required

ContactFullResponse[] · required

Add a contact

POST

https://api.cakemail.dev

/lists/{list_id}/contacts

Add a single contact to a list. Optionally trigger a double opt-in confirmation email. If the contact already exists and is unsubscribed, set resubscribe to true to re-activate them.

Required scope(s): contacts:write

Add a contact › path Parameters

list_id

integer · min: 1 · required

Add a contact › query Parameters

send_double_opt_in

string · enum

Default: 'false'

Send a double opt-in/confirmation email

new : send only if the email is new to the list
not_active : send only if the contact is not already active
true : send the email regardless of contact status
false : do not send the email

Enum values:

true

false

new

not_active

Default: false

resubscribe

boolean

Default: true

account_id

integer · min: 1

Optional Account ID to be used for the request

Add a contact › Request Body

Contact

email

string · email · required

Contact's email address

CustomAttribute[]

Custom attributes to set on the contact

Add a contact › Responses

Successful Response

CreateContactResponse

id

integer · required

object

string

Default: contact

created

boolean

Default: true

ContactFullResponse

POST/lists/{list_id}/contacts

curl https://api.cakemail.dev/lists/:list_id/contacts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "email": "test@example.com",
  "custom_attributes": [
    {
      "name": "name",
      "value": "value"
    }
  ]
}'

Example Request Body

{
  "email": "test@example.com",
  "custom_attributes": [
    {
      "name": "name",
      "value": "value"
    }
  ]
}

json

Example Responses

{
  "id": 0,
  "object": "contact",
  "created": true,
  "data": {
    "id": 0,
    "email": "email",
    "status": "status",
    "subscribed_on": 0,
    "last_bounce_type": "last_bounce_type",
    "bounces_count": 0,
    "custom_attributes": [
      {
        "name": "name",
        "value": "value"
      }
    ],
    "tags": [],
    "interests": []
  }
}

json

application/json

Show contacts of a segment

GET

https://api.cakemail.dev

/lists/{list_id}/segments/{segment_id}/contacts

List contacts matching a segment's filter criteria. The segment's query is combined with any additional filters provided in the request.

Required scope(s): contacts:read

Show contacts of a segment › path Parameters

segment_id

integer · min: 1 · required

list_id

integer · min: 1 · required

Show contacts of a segment › query Parameters

query

string

SQL selection query (only use one of query, fiql and json)

json

string · json-string

JSON selection expression (only use one of query, fiql and json)

cursor

string

Cursor pagination

account_id

integer · min: 1

Optional Account ID to be used for the request

page

integer · min: 1

Default: 1

per_page

integer · min: 1

Default: 50

with_count

boolean

Include count in the response

Default: false

sort

string

Sort term and direction, using syntax [-|+]term.

Valid terms:

id
email
status
subscribed_on
last_bounce_type
bounces_count

Sort term and direction, using syntax [-|+]term.

Valid terms:

id
email
status
subscribed_on
last_bounce_type
bounces_count

filter

string

Valid Terms:

status
email
tags
interests

Valid Operators:

==

Query separator:

Valid Terms:

status
email
tags
interests

Valid Operators:

==

Query separator:

fiql

string

Show contacts of a segment › Responses

Successful Response

ContactsResponse

PaginationWithCursor · required

ContactFullResponse[] · required

Tags multiple contacts

POST

https://api.cakemail.dev

/lists/{list_id}/contacts/tag

Add tags to multiple contacts at once. Contacts can be specified by ID list or by a filter query.

Required scope(s): contacts:write

Tags multiple contacts › path Parameters

list_id

integer · min: 1 · required

Tags multiple contacts › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Tags multiple contacts › Request Body

TagMultipleContacts

tags

string[] · minItems: 1 · maxItems: 1024 · required

contact_ids

integer[] · min: 1 · minItems: 1 · maxItems: 1024

query

string · minLength: 1

SQL-like expression

fiql

string

json

object

Tags multiple contacts › Responses

Successful Response

TagMultipleContactsResponse

tagged

boolean

Default: true

skipped_contact_ids

integer[]

contact_ids that were not a contact of the list and were not tagged

Untags multiple contacts

POST

https://api.cakemail.dev

/lists/{list_id}/contacts/untag

Remove tags from multiple contacts at once. Contacts can be specified by ID list or by a filter query.

Required scope(s): contacts:write

Untags multiple contacts › path Parameters

list_id

integer · min: 1 · required

Untags multiple contacts › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Untags multiple contacts › Request Body

UntagMultipleContacts

tags

string[] · minItems: 1 · maxItems: 1024 · required

contact_ids

integer[] · min: 1 · minItems: 1 · maxItems: 1024

query

string · minLength: 1

SQL-like expression

fiql

string

json

object

Untags multiple contacts › Responses

Successful Response

UntagMultipleContactsResponse

untagged

boolean

Default: true

Show a contact details

GET

https://api.cakemail.dev

/lists/{list_id}/contacts/{contact_id}

Retrieve the full details of a contact, including email, subscription status, custom attributes, tags, and interests.

Required scope(s): contacts:read

Show a contact details › path Parameters

list_id

integer · min: 1 · required

contact_id

integer · min: 1 · required

Show a contact details › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Show a contact details › Responses

Successful Response

ContactResponse

ContactFullResponse · required

Update a contact

PATCH

https://api.cakemail.dev

/lists/{list_id}/contacts/{contact_id}

Update a contact's email, custom attributes, tags, or interests. All fields are optional — only provided fields are updated. By default, tags and interests are replaced with the provided values; set remove_tags to false to add tags without removing existing ones.

Required scope(s): contacts:write

Update a contact › path Parameters

list_id

integer · min: 1 · required

contact_id

integer · min: 1 · required

Update a contact › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Update a contact › Request Body

PatchContact

email

string · email

Contact's email address

CustomAttribute[]

Custom attributes to set on the contact

interests

string[]

Interests to assign to the contact

tags

string[]

Tags to assign to the contact

remove_tags

boolean

Tags the contact has that are not in tags are removed. When false, tags are added without removing any existing tag.

Default: true

Update a contact › Responses

Successful Response

PatchContactResponse

id

integer · required

ContactFullResponse · required

object

string

Default: contact

updated

boolean

Default: true

PATCH/lists/{list_id}/contacts/{contact_id}

curl https://api.cakemail.dev/lists/:list_id/contacts/:contact_id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "email": "test@example.com",
  "custom_attributes": [
    {
      "name": "name",
      "value": "value"
    }
  ],
  "interests": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "remove_tags": true
}'

Example Request Body

{
  "email": "test@example.com",
  "custom_attributes": [
    {
      "name": "name",
      "value": "value"
    }
  ],
  "interests": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "remove_tags": true
}

json

Example Responses

{
  "id": 0,
  "object": "contact",
  "updated": true,
  "data": {
    "id": 0,
    "email": "email",
    "status": "status",
    "subscribed_on": 0,
    "last_bounce_type": "last_bounce_type",
    "bounces_count": 0,
    "custom_attributes": [
      {
        "name": "name",
        "value": "value"
      }
    ],
    "tags": [],
    "interests": []
  }
}

json

application/json

Delete a contact

DELETE

https://api.cakemail.dev

/lists/{list_id}/contacts/{contact_id}

Delete a contact from a list. The contact's data is permanently removed.

Required scope(s): contacts:delete

Delete a contact › path Parameters

list_id

integer · min: 1 · required

contact_id

integer · min: 1 · required

Delete a contact › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Delete a contact › Responses

Successful Response

DeleteContactResponse

id

integer · required

object

string

Default: contact

deleted

boolean

Default: true

Import contacts

POST

https://api.cakemail.dev

/lists/{list_id}/import-contacts

Synchronize your own list by importing to your active, unsubscribed or deleted contacts.

Required scope(s): contacts:import

Import contacts › path Parameters

list_id

integer · min: 1 · required

Import contacts › query Parameters

send_double_opt_in

string · enum

Default: 'false'

Send a double opt-in/confirmation email

new : send only if the email is new to the list
not_active : send only if the contact is not already active
true : send the email regardless of contact status
false : do not send the email

Enum values:

true

false

new

not_active

Default: false

account_id

integer · min: 1

Optional Account ID to be used for the request

Import contacts › Request Body

ImportContacts

ImportContactData[] · minItems: 1 · required

List of contacts to import

import_to

string · enum

Status to assign to imported contacts

Enum values:

active

unsubscribed

deleted

contact_details

boolean

Include detailed contact information in the response. When false, returns only ID and email.

Default: true

resubscribe

boolean

Resubscribe previously unsubscribed contacts

Default: false

remove_tags

boolean

Tags are removed if omitted.

Default: true

remove_interests

boolean

Interests are removed if omitted.

Default: true

Import contacts › Responses

Successful Response

ImportContactsResponse

id

integer[] · required

IDs of successfully imported contacts

import_id

string · uuid4

Unique identifier for this import batch

object

string

Object type

Default: contact

imported

boolean

Whether the import succeeded

Default: true

array

Imported contact details

Default: []

array

Errors encountered during import

POST/lists/{list_id}/import-contacts

curl https://api.cakemail.dev/lists/:list_id/import-contacts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "import_to": "active",
  "contact_details": true,
  "contacts": [
    {
      "email": "test@example.com",
      "custom_attributes": [
        {
          "name": "name",
          "value": "value"
        }
      ],
      "tags": [
        "string"
      ],
      "interests": [
        "string"
      ]
    }
  ],
  "resubscribe": false,
  "remove_tags": true,
  "remove_interests": true
}'

Example Request Body

{
  "import_to": "active",
  "contact_details": true,
  "contacts": [
    {
      "email": "test@example.com",
      "custom_attributes": [
        {
          "name": "name",
          "value": "value"
        }
      ],
      "tags": [
        "string"
      ],
      "interests": [
        "string"
      ]
    }
  ],
  "resubscribe": false,
  "remove_tags": true,
  "remove_interests": true
}

json

Example Responses

{
  "import_id": "import_id",
  "id": [
    0
  ],
  "object": "contact",
  "imported": true,
  "data": [],
  "errors": [
    {
      "loc": [
        "string"
      ],
      "msg": "Contact not found",
      "code": 8001
    }
  ]
}

json

application/json

Unsubscribe a contact from a list

POST

https://api.cakemail.dev

/lists/{list_id}/contacts/{contact_id}/unsubscribe

Unsubscribe a contact from a list. The contact remains in the list but will no longer receive campaigns.

Required scope(s): contacts:write

Unsubscribe a contact from a list › path Parameters

list_id

integer · min: 1 · required

contact_id

integer · min: 1 · required

Unsubscribe a contact from a list › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Unsubscribe a contact from a list › Responses

Successful Response

UnsubscribeContactResponse

object · required

Unsubscribed contact details

object

string

Object type

Default: contact

subscribed

boolean

Subscription status of the contact

Default: false

deprecated

Tags a contact

POST

https://api.cakemail.dev

/lists/{list_id}/contacts/{contact_id}/tag

Add tags to a single contact. Deprecated — use the bulk tag endpoint instead.

Required scope(s): contacts:write

Tags a contact › path Parameters

list_id

integer · min: 1 · required

contact_id

integer · min: 1 · required

Tags a contact › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Tags a contact › Request Body

Tags a contact › Responses

Successful Response

TagContactResponse

tagged

boolean

Default: true

deprecated

Untags a contact

POST

https://api.cakemail.dev

/lists/{list_id}/contacts/{contact_id}/untag

Remove tags from a single contact. Deprecated — use the bulk untag endpoint instead.

Required scope(s): contacts:write

Untags a contact › path Parameters

list_id

integer · min: 1 · required

contact_id

integer · min: 1 · required

Untags a contact › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Untags a contact › Request Body

Untags a contact › Responses

Successful Response

UntagContactResponse

untagged

boolean

Default: true

Remove interest(s) from contact(s)

POST

https://api.cakemail.dev

/lists/{list_id}/contacts/remove-interests

Remove interests from multiple contacts at once. Contacts can be specified by ID list or by a filter query.

Required scope(s): contacts:write

Remove interest(s) from contact(s) › path Parameters

list_id

integer · min: 1 · required

Remove interest(s) from contact(s) › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Remove interest(s) from contact(s) › Request Body

RemoveInterestsFromContacts

interests

string[] · maxItems: 16 · required

contact_ids

integer[] · min: 1 · maxItems: 1024

query

string

fiql

string

json

object

Remove interest(s) from contact(s) › Responses

Successful Response

RemoveInterestsFromMultipleContactsResponse

object

string

Object type

Default: interests

removed

boolean

Whether interests were removed

Default: true

Show all Contacts Exports

GET

https://api.cakemail.dev

/lists/{list_id}/exports

Show all Contacts Exports.

Required scope(s): contacts:export

Show all Contacts Exports › path Parameters

list_id

integer · min: 1 · required

Show all Contacts Exports › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

page

integer · min: 1

Default: 1

per_page

integer · min: 1

Default: 50

with_count

boolean

Include count in the response

Default: false

sort

string

Sort term and direction, using syntax [-|+]term.

Valid terms:

status
created_on
expires_on

Sort term and direction, using syntax [-|+]term.

Valid terms:

status
created_on
expires_on

filter

string

Valid Terms:

status
progress

Valid Operators:

==

Query separator:

Valid Terms:

status
progress

Valid Operators:

==

Query separator:

Show all Contacts Exports › Responses

Successful Response

ContactsExportsResponse

object · required

Pagination metadata

ContactsExportFullResponse[] · required

List of contact exports

Create a Contacts Export

POST

https://api.cakemail.dev

/lists/{list_id}/exports

Create a Contacts Export to a CSV file.

Required scope(s): contacts:export

Create a Contacts Export › path Parameters

list_id

integer · min: 1 · required

Create a Contacts Export › query Parameters

description

string

query

string

json

string · json-string

segment_id

integer · min: 1

account_id

integer · min: 1

Optional Account ID to be used for the request

filter

string

Valid Terms:

status
email
tags
interests

Valid Operators:

==

Query separator:

Valid Terms:

status
email
tags
interests

Valid Operators:

==

Query separator:

fiql

string

Create a Contacts Export › Responses

Successful Response

CreateContactsExportResponse

id

string · required

ID of the created export task

object · required

Created export details

object

string

Object type

Default: task

created

boolean

Whether the export was created

Default: true

Show a Contacts Export

GET

https://api.cakemail.dev

/lists/{list_id}/exports/{export_id}

Show a Contacts Export.

Required scope(s): contacts:export

Show a Contacts Export › path Parameters

export_id

string · required

list_id

integer · min: 1 · required

Show a Contacts Export › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Show a Contacts Export › Responses

Successful Response

ContactsExportResponse

object · required

Export details

Delete a Contacts Export

DELETE

https://api.cakemail.dev

/lists/{list_id}/exports/{export_id}

Delete a Contacts Export.

Required scope(s): contacts:export

Delete a Contacts Export › path Parameters

export_id

string · required

list_id

integer · min: 1 · required

Delete a Contacts Export › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Delete a Contacts Export › Responses

Successful Response

ContactsExportDeleteResponse

id

string · required

ID of the deleted export

object · required

Deleted export details

object

string

Object type

Default: contactsexport

deleted

boolean

Whether the export was deleted

Default: true

Download a Contacts Export

GET

https://api.cakemail.dev

/lists/{list_id}/exports/{export_id}/download

Download a Contacts Export.

Required scope(s): contacts:export

Download a Contacts Export › path Parameters

export_id

string · required

list_id

integer · min: 1 · required

Download a Contacts Export › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Download a Contacts Export › Responses

Successful Response

DownloadContactsExportResponse

object · required

Download details

List Segment