​
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 email properties, 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 or email content and the receipient’s email address and the email properties needed for the email.

Read on for more details about creating, editing and sending transactional emails.

​
Compose your email

To create emails in Cocoonmail: using our editor.

​
Use our editor

You can create emails in the editor, letting you add formatting and easily attach the files with attachment attribute.

You can add dynamic data into your emails by using email properties (like first_name). Read on for more information about email properties.

​
Add email properties

Email properties let you insert dynamic values into each transactional email you send. Once you have added email properties into your email, you specify the value of each email property in the API call to send each transactional email.

Let’s say you want to update first name and last name of the email.

For this we add two email properties to the email: first_name and last_name.

{

  first_name:first name,

  last_name:last name

}

To send data to these fields, simply include the email properties in your API call as normal.

​
Important information about email properties

  • Make sure that when you send a transactional email using the API that you include all email properties in your request. If you do not include the correct set of email properties in your API call, the send will fail.
  • Email properties names are case-sensitive (meaning FirstName and first_name are different variables).
  • Email properties names can only contain:
    • letters
    • numbers
    • underscores
    • dashes
  • Email properties values sent over the API can be string or number.

​
Publish the email

To enable sending the email, select active in the dropdown.

​
Send your email

Two Email properties were used in the email and there is a transactional ID needed as part of our API call. Any email properties 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://webhook.cocoonmail.com/webhook/transactional/

Payload

You can copy an email’s example payload from its Publish page in Cocoonmail by clicking the “Show payload” button.

 {

    "transactional_id":"<string>",

    "email":["<string>", "<string>"],

    "email_properties":{

        "first_name":"<string>"

    },

    "add_email_address_to_contact": "<Boolean>",

    "attachments": [

        {

            "filename": "event.ics",

        }

    ]

}

If not with transactional’s ID :

 {

    "email":[""<string>"", ""<string>""],

    "email_content":""<string>"",

    "from_email_address":""<string>"",

    "email_properties":{

        "first_name":""<string>""

    },

    "add_email_address_to_contact": "<Boolean>",

    "attachments": [

        {

            "filename": "<string>",

        }

    ]

}

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