Managing your contacts

In this guide, you will learn the basics of managing your contacts in Cakemail.

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.

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]"}'

from cakemail.models import List, Sender

my_list = api.list.create(
    list=List(
        name='<list name>',
        language='en_US',
        default_sender=Sender(id=sender.id)
    )
)

<?php

$myList = $api->list->create([
    'model_list' => new \Cakemail\Lib\Model\ModelList([
        'name' => '<list name>',
        'language' => 'en_US',
        'default_sender' => new \Cakemail\Lib\Model\Sender([
            'id' => $sender['id']
        ])
    ])
]);

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.

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

api.list.accept_policy(list_id=my_list.id)

<?php

$api->list->acceptPolicy([
    'list_id' => $myList['id']
]);

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.

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]"}'

from cakemail.models import Contact

api.contact.create(
    list_id=my_list.id,
    contact=Contact(email='<contact email address>')
)

<?php

$api->contact->create([
    'list_id' => $myList['id'],
    'contact' => new \Cakemail\Lib\Model\Contact(
        '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.

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"},...]}'

from cakemail.models import ImportContacts, ImportContactData

api.contact.import_contacts(
    list_id=my_list.id,
    import_contacts=ImportContacts(
        import_to='active',
        contacts=[
          ImportContactData(email='<contact email address>'),
          ImportContactData(email='<contact email address>')
        ]
    )
)

<?php

$api->contact->importContacts([
    'list_id' => $myList['id'],
    'contacts' => new \Cakemail\Lib\Model\ImportContacts(
        'import_to' => 'active',
        'contacts' => [
            new \Cakemail\Lib\Model\ImportContactData(
                'email' => '<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.

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]'

contacts = api.contact.list(
    list_id=my_list.id
)

<?php

$contacts = $api->contact->list([
    'list_id' => $myList['id']
]);

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.

You can also show the details of single contact by calling the Show a contact details endpoint along with the contact ID.

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

my_contact = api.contact.get(
    list_id=my_list.id,
    contact_id=<contact ID>
)

<?php

$myContact = $api->contact->get([
    'list_id' => $myList['id'],
    'contact_id' => <contact ID>
]);

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.

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

api.contact.unsubscribe(
    list_id=my_list.id,
    contact_id=my_contact.id
)

<?php

$api->contact->unsubscribe([
    'list_id' => $myList['id'],
    'contact_id' => $myContact['id']
]);

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.