List

Manage contact lists. A list is a collection of contacts (email subscribers) with its own sender identity, language, and subscription settings. Lists support double opt-in, custom redirect URLs after subscription events, and webhook notifications. Also includes deprecated subscription form endpoints for legacy integrations — use the Form endpoints instead.

Show all lists

GET

https://api.cakemail.dev

/lists

List all contact lists in the account. Results can be filtered by name and status, and sorted by name or creation date.

Required scope(s): lists:read

Show all lists › 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

filter

string

Valid Terms:

status
name

Valid Operators:

==

Query separator:

Valid Terms:

status
name

Valid Operators:

==

Query separator:

sort

string

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

Valid terms:

name
created_on

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

Valid terms:

name
created_on

Show all lists › Responses

Successful Response

ListsResponse

Pagination · required

ListSummaryResponse[] · required

Create a List

POST

https://api.cakemail.dev

/lists

Create a new contact list. A default sender must be specified — this is the sender identity used for campaigns sent to this list. Lists are created with double opt-in enabled by default.

Required scope(s): lists:write

Create a List › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Create a List › Request Body

List

name

string · minLength: 1 · required

List Name

object · required

language

string · enum

Supported Locales

Enum values:

da_DK

de_DE

el_GR

en_US

Default: en_US

object

Default: {}

object

Default: {}

Create a List › Responses

Successful Response

CreateListResponse

id

integer · required

ListFullResponse · required

created

boolean

Default: true

POST/lists

curl https://api.cakemail.dev/lists \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "name",
  "default_sender": {
    "id": "id"
  },
  "language": "en_US",
  "redirections": {},
  "webhook": {}
}'

Example Request Body

{
  "name": "name",
  "default_sender": {
    "id": "id"
  },
  "language": "en_US",
  "redirections": {},
  "webhook": {}
}

json

Example Responses

{
  "id": 0,
  "created": true,
  "data": {
    "id": 0,
    "name": "name",
    "status": "status",
    "policy_accepted": false,
    "language": "language",
    "created_on": 0,
    "default_sender": {
      "name": "name",
      "email": "email"
    },
    "redirections": {
      "after_opt_in": "after_opt_in",
      "after_double_opt_in": "after_double_opt_in",
      "after_opt_out": "after_opt_out"
    },
    "pages": {
      "opt_in": "opt_in",
      "opt_out": "opt_out",
      "subscribe": "subscribe",
      "unsubscribe": "unsubscribe"
    },
    "webhook": {
      "url": "url",
      "actions": [
        "all"
      ]
    }
  }
}

json

application/json

Show a list parameters

GET

https://api.cakemail.dev

/lists/{list_id}

Retrieve the full details of a list, including its name, language, default sender, redirect URLs, webhook configuration, and pages.

Required scope(s): lists:read

Show a list parameters › path Parameters

list_id

integer · min: 1 · required

Show a list parameters › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Show a list parameters › Responses

Successful Response

ListResponse

ListFullResponse · required

GET/lists/{list_id}

curl https://api.cakemail.dev/lists/:list_id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": 0,
    "name": "name",
    "status": "status",
    "policy_accepted": false,
    "language": "language",
    "created_on": 0,
    "default_sender": {
      "name": "name",
      "email": "email"
    },
    "redirections": {
      "after_opt_in": "after_opt_in",
      "after_double_opt_in": "after_double_opt_in",
      "after_opt_out": "after_opt_out"
    },
    "pages": {
      "opt_in": "opt_in",
      "opt_out": "opt_out",
      "subscribe": "subscribe",
      "unsubscribe": "unsubscribe"
    },
    "webhook": {
      "url": "url",
      "actions": [
        "all"
      ]
    }
  }
}

json

application/json

Update a list parameters

PATCH

https://api.cakemail.dev

/lists/{list_id}

Update a list's settings. All fields are optional — only provided fields are updated. Can change the name, default sender, language, redirect URLs, and webhook configuration.

Required scope(s): lists:write

Update a list parameters › path Parameters

list_id

integer · min: 1 · required

Update a list parameters › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Update a list parameters › Request Body

UpdateList

name

string · minLength: 1

object

language

string · enum

Supported Locales

Enum values:

da_DK

de_DE

el_GR

en_US

object

Default: {}

object

Default: {}

Update a list parameters › Responses

Successful Response

PatchListResponse

id

integer · required

ListFullResponse · required

updated

boolean

Default: true

PATCH/lists/{list_id}

curl https://api.cakemail.dev/lists/:list_id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "name",
  "default_sender": {
    "id": "id"
  },
  "language": "da",
  "redirections": {},
  "webhook": {}
}'

Example Request Body

{
  "name": "name",
  "default_sender": {
    "id": "id"
  },
  "language": "da",
  "redirections": {},
  "webhook": {}
}

json

Example Responses

{
  "id": 0,
  "updated": true,
  "data": {
    "id": 0,
    "name": "name",
    "status": "status",
    "policy_accepted": false,
    "language": "language",
    "created_on": 0,
    "default_sender": {
      "name": "name",
      "email": "email"
    },
    "redirections": {
      "after_opt_in": "after_opt_in",
      "after_double_opt_in": "after_double_opt_in",
      "after_opt_out": "after_opt_out"
    },
    "pages": {
      "opt_in": "opt_in",
      "opt_out": "opt_out",
      "subscribe": "subscribe",
      "unsubscribe": "unsubscribe"
    },
    "webhook": {
      "url": "url",
      "actions": [
        "all"
      ]
    }
  }
}

json

application/json

Delete a List

DELETE

https://api.cakemail.dev

/lists/{list_id}

Permanently delete a list and all its contacts. This action cannot be undone. To preserve the data, archive the list instead.

Required scope(s): lists:delete

Delete a List › path Parameters

list_id

integer · min: 1 · required

Delete a List › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Delete a List › Responses

Successful Response

DeleteListResponse

id

integer · required

object

string

Default: list

deleted

boolean

Default: true

Accept policy for a list

POST

https://api.cakemail.dev

/lists/{list_id}/accept-policy

Accept the anti-spam policy for a list. This acknowledgement is required before the list can be used for sending campaigns.

Required scope(s): lists:write

Accept policy for a list › path Parameters

list_id

integer · min: 1 · required

Accept policy for a list › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Accept policy for a list › Responses

Successful Response

AcceptListPolicyResponse

id

integer · required

object

string

Default: list

policy_accepted

boolean

Default: true

Archive a list

POST

https://api.cakemail.dev

/lists/{list_id}/archive

Archive a list, making it inactive. Archived lists retain their contacts and data but cannot be used for sending campaigns.

Required scope(s): lists:write

Archive a list › path Parameters

list_id

integer · min: 1 · required

Archive a list › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Archive a list › Responses

Successful Response

ArchiveListResponse

id

integer · required

object

string

Default: list

archived

boolean

Default: true

deprecated

Enable a subscription form endpoint

POST

https://api.cakemail.dev

/lists/{list_id}/forms/{form_id}/enable

Required scope(s): lists:write

Enable a subscription form endpoint › path Parameters

form_id

string · minLength: 1 · pattern: ^[a-zA-Z0-9]+$ · required

list_id

integer · min: 1 · required

Enable a subscription form endpoint › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Enable a subscription form endpoint › Responses

Successful Response

EnableSubscriptionFormEndpointResponse

SubscriptionFormEndpointResponse · required

object

string

Default: subscription_form_endpoint

enabled

boolean

Default: true

deprecated

Disable a subscription form endpoint

POST

https://api.cakemail.dev

/lists/{list_id}/forms/{form_id}/disable

Required scope(s): lists:write

Disable a subscription form endpoint › path Parameters

form_id

string · minLength: 1 · pattern: ^[a-zA-Z0-9]+$ · required

list_id

integer · min: 1 · required

Disable a subscription form endpoint › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Disable a subscription form endpoint › Responses

Successful Response

DisableSubscriptionFormEndpointResponse

SubscriptionFormEndpointResponse · required

object

string

Default: subscription_form_endpoint

enabled

boolean

Default: false

deprecated

List subscription form endpoints

GET

https://api.cakemail.dev

/lists/{list_id}/forms

Required scope(s): lists:read

List subscription form endpoints › path Parameters

list_id

integer · min: 1 · required

List subscription form endpoints › 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

List subscription form endpoints › Responses

Successful Response

ListSubscriptionFormEndpointResponse

Pagination · required

SubscriptionFormEndpointResponse[] · required

deprecated

Create a subscription form endpoint

POST

https://api.cakemail.dev

/lists/{list_id}/forms

Required scope(s): lists:write

Create a subscription form endpoint › path Parameters

list_id

integer · min: 1 · required

Create a subscription form endpoint › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Create a subscription form endpoint › Request Body

CreateSubscriptionFormEndpointRequest

domain

string · pattern: ^(?:[a-zA-Z0-9](?:[a…

domain name hosting the form

name

string

Name of the form

double_opt_in

boolean

Whether to use double opt in

Default: true

secret

string

Google reCaptcha secret key

post_redirect_url

string

Instead of the usual API reply, redirect to this URL when submitting the form.

double_opt_in_redirect_url

string

Redirect to this URL after the double opt in callback.

async_processing

boolean

Whether to process the form submission asynchronously.

Default: true

Create a subscription form endpoint › Responses

Successful Response

CreateSubscriptionFormEndpointResponse

SubscriptionFormEndpointResponse · required

object

string

Default: subscription_form_endpoint

created

boolean

Default: true

POST/lists/{list_id}/forms

curl https://api.cakemail.dev/lists/:list_id/forms \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "domain": "domain",
  "name": "name",
  "double_opt_in": true,
  "secret": "secret",
  "post_redirect_url": "post_redirect_url",
  "double_opt_in_redirect_url": "double_opt_in_redirect_url",
  "async_processing": true
}'

Example Request Body

{
  "domain": "domain",
  "name": "name",
  "double_opt_in": true,
  "secret": "secret",
  "post_redirect_url": "post_redirect_url",
  "double_opt_in_redirect_url": "double_opt_in_redirect_url",
  "async_processing": true
}

json

Example Responses

{
  "object": "subscription_form_endpoint",
  "created": true,
  "data": {
    "id": "id",
    "enabled": true,
    "name": "name",
    "domain": "domain",
    "secret": "secret",
    "post_redirect_url": "post_redirect_url",
    "double_opt_in": true,
    "double_opt_in_redirect_url": "double_opt_in_redirect_url",
    "submission_url": "submission_url",
    "async_processing": true
  }
}

json

application/json

deprecated

Show a subscription form endpoint

GET

https://api.cakemail.dev

/lists/{list_id}/forms/{form_id}

Required scope(s): lists:read

Show a subscription form endpoint › path Parameters

form_id

string · minLength: 1 · pattern: ^[a-zA-Z0-9]+$ · required

list_id

integer · min: 1 · required

Show a subscription form endpoint › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Show a subscription form endpoint › Responses

Successful Response

ShowSubscriptionFormEndpointResponse

SubscriptionFormEndpointResponse · required

deprecated

Patch a subscription form endpoint

PATCH

https://api.cakemail.dev

/lists/{list_id}/forms/{form_id}

Required scope(s): lists:write

Patch a subscription form endpoint › path Parameters

form_id

string · minLength: 1 · pattern: ^[a-zA-Z0-9]+$ · required

list_id

integer · min: 1 · required

Patch a subscription form endpoint › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Patch a subscription form endpoint › Request Body

PatchSubscriptionFormEndpointRequest

domain

string · pattern: ^(?:[a-zA-Z0-9](?:[a…

domain name hosting the form

name

string

Name of the form

double_opt_in

boolean

Whether to use double opt in

secret

string

Google reCaptcha secret key

post_redirect_url

string

Instead of the usual API reply, redirect to this URL when submitting the form.

double_opt_in_redirect_url

string

Redirect to this URL after the double opt in callback.

async_processing

boolean

Whether to process the form submission asynchronously.

Patch a subscription form endpoint › Responses

Successful Response

PatchSubscriptionFormEndpointResponse

SubscriptionFormEndpointResponse · required

object

string

Default: subscription_form_endpoint

updated

boolean

Default: true

PATCH/lists/{list_id}/forms/{form_id}

curl https://api.cakemail.dev/lists/:list_id/forms/:form_id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "domain": "domain",
  "name": "name",
  "double_opt_in": true,
  "secret": "secret",
  "post_redirect_url": "post_redirect_url",
  "double_opt_in_redirect_url": "double_opt_in_redirect_url",
  "async_processing": true
}'

Example Request Body

{
  "domain": "domain",
  "name": "name",
  "double_opt_in": true,
  "secret": "secret",
  "post_redirect_url": "post_redirect_url",
  "double_opt_in_redirect_url": "double_opt_in_redirect_url",
  "async_processing": true
}

json

Example Responses

{
  "object": "subscription_form_endpoint",
  "updated": true,
  "data": {
    "id": "id",
    "enabled": true,
    "name": "name",
    "domain": "domain",
    "secret": "secret",
    "post_redirect_url": "post_redirect_url",
    "double_opt_in": true,
    "double_opt_in_redirect_url": "double_opt_in_redirect_url",
    "submission_url": "submission_url",
    "async_processing": true
  }
}

json

application/json

deprecated

Delete a subscription form endpoint

DELETE

https://api.cakemail.dev

/lists/{list_id}/forms/{form_id}

Required scope(s): lists:delete

Delete a subscription form endpoint › path Parameters

form_id

string · minLength: 1 · pattern: ^[a-zA-Z0-9]+$ · required

list_id

integer · min: 1 · required

Delete a subscription form endpoint › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Delete a subscription form endpoint › Responses

Successful Response

DeleteSubscriptionFormEndpointResponse

SubscriptionFormEndpointResponse · required

object

string

Default: subscription_form_endpoint

deleted

boolean

Default: true

User Contact