Cakemail API

Managing your contacts

Copy page

This page will help you get started with the Contact API.

Create your first list

Before you can add a contact, you will need to create your first List. A list allows you to group your contacts in one place and define additional custom fields. You can also build segments to better target your audience.

To create a list, you will call the Create a list endpoint along with a name and a default sender.

Code
 
import requests

url = "https://api.cakemail.dev/lists"

payload = {
    "language": "en_US",
    "name": "List Name"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": f"Bearer {token}"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Code
 
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cakemail.dev/lists', [
  'body' => '{"language":"en_US","name":"List Name"}',
  'headers' => [
    'accept' => 'application/json',
    'content-type' => 'application/json',
    'authorization' => "Bearer {$token}"
  ],
]);

echo $response->getBody();

Code
 
curl --request POST \
  --url https://api.cakemail.dev/lists \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]' \
  --header 'content-type: application/json' \
  --data '{"default_sender":{"id":"[sender id]"},"language":"en_US","name":"[list name]"}'

This call will return you a list object containing an ID. But before you can use this list, you will need to accept our anti-spam policy for that list. You can call the Accept policy for a list endpoint to accept the policy for your new list.

Code
 
import requests

url = f"https://api.cakemail.dev/lists/{list_id}/accept-policy"

headers = {"accept": "application/json", "authorization": f"Bearer {token}"}

response = requests.post(url, headers=headers)

print(response.text)

Code
 
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', "https://api.cakemail.dev/lists/{$list_id}/accept-policy", [
  'headers' => [
    'accept' => 'application/json',
    'authorization' => "Bearer {$token}"
  ],
]);

echo $response->getBody();

Code
 
curl --request POST \
  --url https://api.cakemail.dev/lists/[list ID]/accept-policy \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]'

You now have a working list.

Add your first contact

Now let's add your first contact by calling the Add a contact in a list endpoint along with a contact email address.

Code
 
import requests

url = f"https://api.cakemail.dev/lists/{list_id}/contacts"

headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": f"Bearer {token}"
}

response = requests.post(url, headers=headers)

print(response.text)

Code
 
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', "https://api.cakemail.dev/lists/{$list_id}/contacts", [
  'headers' => [
    'accept' => 'application/json',
    'content-type' => 'application/json',
    'authorization' => "Bearer {$token}"
  ],
]);

echo $response->getBody();

Code
 
curl --request POST \
  --url https://api.cakemail.dev/lists/[list ID]/contacts \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]' \
  --header 'content-type: application/json' \
  --data '{"email":"[contact email address]"}'

You now have your first contact in your list!

Import your contacts

In case you already have a list of contacts, you might want to import it in Cakemail instead of adding it one by one. You can do so by calling the Import contacts endpoint along with your list of contacts.

Code
 
import requests

url = f"https://api.cakemail.dev/lists/{list_id}/import-contacts"

payload = {
    "remove_tags": False,
    "remove_interests": False,
    "contacts": [
      { "email": "contact_1@email.com" },
      { "email": "contact_2@email.com" },
    ]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": f"Bearer {token}"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Code
 
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', "https://api.cakemail.dev/lists/{$list_id}/import-contacts", [
  'body' => '{"contacts":[{"email":"contact_1@email.com"}],"resubscribe":false,"remove_tags":true,"remove_interests":true}',
  'headers' => [
    'accept' => 'application/json',
    'content-type' => 'application/json',
    'authorization' => "Bearer {$token}"
  ],
]);

echo $response->getBody();

Code
 
curl --request POST \
  --url https://api.cakemail.dev/lists/[list ID]/import-contacts \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]' \
  --header 'content-type: application/json' \
  --data '{"import_to":"active","contacts":[{"email":"[1st contact email address"},{"email":"2nd contact email address"},...]}'

You now have plenty of contacts in your list. It is important to note that you might have to call this endpoint multiple times as we have a limit to import a maximum of 1,000 contacts at a time.

Display all your contacts

At any time, you can show the contacts of your contact list by calling the Show all contacts in a list endpoint.

Code
 
import requests

url = f"https://api.cakemail.dev/lists/{list_id}/contacts"

headers = {
  "accept": "application/json",
  "authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)

print(response.text)

Code
 
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', "https://api.cakemail.dev/lists/{$list_id}/contacts", [
  'headers' => [
    'accept' => 'application/json',
    'authorization' => "Bearer {$token}"
  ],
]);

echo $response->getBody();

Code
 
curl --request GET \
  --url 'https://api.cakemail.dev/lists/[list ID]/contacts?page=1&per_page=50&with_count=false&filter=status%3D%3Dsubscribed' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]'

This call will return the first 50 contacts of your list who are subscribed. You can change how the pagination is done by using the query parameters Page and Per Page. If you want the Pagination object to also contain the total count of contacts in your list, you can specify the query parameters With Count to be true. Finally the query parameter Filter which is optional can be used to search the list.

Unsubscribe a contact

Although this can be done automatically using our tracking links, there are times where you might want to manage the subscriptions on your side. To remain compliant, you still need to sync the people who unsubscribed on your side with our API. This can be done by calling the Unsubscribe a contact from a list endpoint.

Code
 
import requests

url = f"https://api.cakemail.dev/lists/{list_id}/contacts/{contact_id}/unsubscribe"

headers = {"accept": "application/json", "authorization": f"Bearer {token}"}

response = requests.post(url, headers=headers)

print(response.text)

Code
 
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', "https://api.cakemail.dev/lists/{$list_id}/contacts/{$contact_id}/unsubscribe", [
  'headers' => [
    'accept' => 'application/json',
    'authorization' => "Bearer {$token}"
  ],
]);

echo $response->getBody();

Code
 
curl --request POST \
  --url https://api.cakemail.dev/lists/[list ID]/contacts/[contact ID]/unsubscribe \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]'

Using a combination of adds, imports and unsubscribes, you now know how to keep your list in sync with our Contact API.

You can explore the full API reference for more advanced features in the Contact API.