API Introduction

​

Authentication

Start here if you want to use the Cocoonmail API to add contacts to your Cocoonmail audience, update their attributes, and send events to Cocoonmail.

Authentication Steps

To begin, you need an API key. Go to the Cocoonmail ‘API Key’ page in the Settings section and click on “Generate key”.

This generates an API key. You can give it a name that is easy to understand.

We suggest using a different API key for different purposes. You can remove an API key anytime by clicking the trash icon.

When making an API call, add an Authorization header and set the API key as a Bearer token:

You can test your API key by making a GET request to https://webhook.cocoonmail.com/webhook/api_key/validate/. If successful, you will receive { "success": true }

As a Curl request (replace pbkdf2_sha256$600000$8ELnVRTWG2JddDkU3gP59U$eZFMR4pr349lcc3gTHK24vPthVMsY279jpoL/W2g3Mo= with your own API key):

Copy

"curl https://webhook.cocoonmail.com/webhook/api_key/validate/ -H "Accept: application/json" -H "X-COCOONMAIL-API_KEY: pbkdf2_sha256$600000$8ELnVRTWG2JddDkU3gP59U$eZFMR4pr349lcc3gTHK24vPthVMsY279jpoL/W2g3Mo="

​

Rate Limiting

To ensure the quality of service for all users, our API is rate limited. This means there’s a limit to the number of requests your application can make to our API in a certain time frame. The baseline rate limit is 10 requests per second per team.

Rate Limiting Details

To see your current usage, we provide the following response headers in every API response:

• x-ratelimit-limit: The maximum number of requests you can make per second.
• x-ratelimit-remaining: The number of requests remaining in the current rate limit window.

Here is an example of a successful response with rate limit headers:

If you exceed this limit, you’ll receive a response with HTTP status 429 Too Many Requests. Here is an example of a failed response with rate limit headers:

It’s important to handle these 429 responses in your application. We recommend implementing retries with an exponential backoff strategy.

If your use case requires a higher limit, please contact us and we’ll be happy to discuss your needs.

​

SDKs

SDKs are software packages built on top of the API, making it easier to integrate into your project.

​

Unofficial SDKs

The following SDKs are community-submitted and have not been officially reviewed or endorsed by Cocoonmail. We recommend thoroughly testing and reviewing the code before integrating it into your project.

• Laravel by PlutoLinks
• PHP by PlutoLinks
• Ruby on Rails by Daniel Friis

Submit an SDK

​

Contacts

Manage contacts.

​

Mailing lists

View your mailing lists.

​

Events

Send events to trigger emails in workflow.

​

Transactional email

Send a transactional email.

​

Custom fields

View your account’s custom contact properties.

​

API key

Test your API key.