​
How it works

Sending transactional email with Cocoonmail has two steps.
1

Create transactional emails

First, you need to create transactional emails within Cocoonmail using our handy email editor. In your email you add data variables, which let you insert custom data into each email you send.
2

Send with the API

To send transactional emails you need to use the Cocoonmail API. All it takes is a simple call to our transactional endpoint. Your request needs to include the ID of the transactional email you created, the receipient’s email address and the data variables needed for the email.
Read on for more details about creating, editing and sending transactional emails.

​
Compose your email

There are two ways to create emails in Cocoonmail: using our editor or import an MJML template.

​
Use our editor

You can create emails in the editor, letting you easily add formatting, images and buttons. You can add dynamic data into your emails by using data variables (like name in the example above). Read on for more information about data variables.

​
Bring your own MJML

You can also upload your own MJML code to use in the email. This is useful if you have a pre-existing template you want to use. Like emails created in our editor, you can add data variables to MJML templates. To add a data variable called PasswordResetLink, you can use it in your MJML like this: 
 <mj-text>{DATA_VARIABLE:PasswordResetLink}</mj-text>
Note the uppercase “DATA_VARIABLE” and the colon before the variable name.

​
Add data variables

Data variables let you insert dynamic values into each transactional email you send. Once you have added data variables into your email, you specify the value of each data variable in the API call to send each transactional email. Let’s say you have a password reset email that is sent once a user clicks a “Reset Password” button in your application. For this we add two data variables to the email: name and resetUrl.
We do not currently offer optional or conditional data variables. Using an empty string "" will also cause the email to fail.
You can insert data variables into the text of the email with the Insert data variable button: You can also add data variables as links (on text, images and buttons). This is how we add resetUrl as the button’s link in our example: If you want to write the tags manually in your content, you can use our dynamic tag syntax. To add a reset URL you can write a tag like this: 
{DATA_VARIABLE:resetUrl}
Data variables are also available in the email sending settings fields, like From, Reply and Subject. Click the > button to view all fields and then click the data variable icon. To send data to these fields, simply include the data variables in your API call as normal.

​
Important information about data variables

  • Make sure that when you send a transactional email using the API that you include all data variables in your request. If you do not include the correct set of data variables in your API call, the send will fail.
  • We do not currently offer optional or conditional data variables. Using an empty string "" will also cause the email to fail.
  • Data variable names are case-sensitive (meaning LastLoggedIn and lastLoggedIn are different variables).
  • Data variable names can only contain:
    • letters
    • numbers
    • underscores
    • dashes
  • Data variable values sent over the API can be string or number.

​
Review your email

On the next page, after clicking Next, you’ll see the API Details section. This contains the data variables used in the email as well as a sample payload for reference. The “Transactional ID” lets you distinguish between different transactional emails when calling the API and is required.

​
Publish the email

To enable sending the email, it needs to be published by clicking Publish.

​
Send your email

In the example above, two Data Variables were used in the email and there is a transactional ID needed as part of our API call. Any data variables created in the email are required when making the API request. Here’s an example of the request for sending this email: Send a POST to this endpoint (make sure to authenticate) 
https://app.Cocoonmail.com/api/v1/transactional
Payload You can copy an email’s example payload from its Publish page in Cocoonmail by clicking the “Show payload” button. 
{
  "transactionalId": "clfq6dinn000yl70fgwwyp82l",
  "email": "favorite@example.com",
  "dataVariables": {
    "name": "Chris",
    "passwordResetLink": "https://example.com/reset-password"
  }
}
Find more details about sending transactional emails with the API in the API docs.
You can test sending transactional email by sending to email address with @example.com or @test.com domains. Using these won’t actually send any emails but everything else works just the same as if email was sent, and avoids affecting your domain reputation while you test your integration.

​
Editing the email

To edit the email, click Edit Draft on the Compose page. The previous published version of the email will remain, and will continue sending until you republish the email. This means you can make changes to transactional emails without disrupting ongoing email sending. When you have a draft, we retain both versions and you can switch between your draft and the published version using the toggles in the top left To publish your changes, simply click Republish and click the confirmation. Your draft will seamlessly become the published version.

​
Metrics

After emails are sent, details are shown in the email’s Metrics page. These include send time and if messages experienced any issues with delivery (bounces or spam complaints).
Note that open and click tracking is disabled for transactional messages to improve deliverability for infrastructure-level communications.

​
Errors

This is a known issue with Apple Mail. Make sure that your links start with https:// or http:// and they should work fine.

​
API (400-level error)

The first place to start is to check the body of the response. It will contain a JSON object with a message property that will give you more information about the error. Here are common reasons that the API might return with a 400-level error:
  • Using the API without a verified domain.
  • Trying to use the API for a transactional email without a published email message.
  • Missing a required parameter: transactionalId, email, or dataVariables.
  • Missing a data variable that is required by the email message.