​
Authentication

Your Cocoonmail API key should never be used client side or exposed to your end users.
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 get started, you’ll need an API key. Visit the Cocoonmail settings page and click “Generate new key”This creates an API key. You can assign it a human-readable name:We suggest using a different API key for different purposes. You can revoke an API key at any time with 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://app.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):
"curl https://app.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.
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:api-successful-responseIf 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:api-successful-responseIt’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.

Javascript

The official JavaScript/TypeScript SDK for Cocoonmail.

Ruby

The official Ruby SDK for Cocoonmail.

​
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.