Using the API to send emails

It is possible to use the Autopilot API to send emails by using custom activities and playbooks.

Step 1 - Set up a custom activity

The first step is to pick the custom activity you would like to use to trigger your playbook. This might be as simple as "Send email", but you might want to send emails only when certain events are called. For this example we’ll use "Send email" since it is generic and can be used to send mail in any scenario.

To set up the custom activities, go to "Activities" on the left hand Autopilot menu, then click "New activity".

If you haven’t created an activity before you might be prompted to create an API key, when you do select "Custom API (advanced)" and create it then come back to the API screen.

I’m going to call my activity "Send email".

The next part is important because the attributes are what you are going to use in the email you end up sending. We can control all aspects of the email output using Merge tags, and we want each one of these to be an attribute for that purpose. Make sure you turn "Track as touch" off for this activity, since sending someone an email isn’t a case of them interacting with the system.

We will send these values via the API and include them in the email which is sent. Rather than having one big "Body" block, you could divide this up into different sections of content in the ultimate email.

Step 2 - Set up a playbook

Click done on creating the new activity, then click on "Campaigns" in the left hand menu and go to "New campaign", selecting "Playbook" as the type before clicking "Next".

Use "Start from scratch" and click "Create".

Give the playbook a title like "Send email", and then select "A specific activity occurs" for "People enter when".

You will then be presented with a list of activities to choose from. Search for "Send email" and you should see the activity you created earlier. Select that one.

Step 3 - Add a message to the playbook

Click "Add message" and then "Create new message"

For Message name use anything you like, for this example we will say "Generic message"

Now, for the subject we want to use the activity attribute we created on the "Send message" custom activity.

To do this:

1) Click the little Merge tag icon on the subject line.

2) Search for "Send email".

Click the one at the bottom, which is our custom activity called "Send email"

3) Then select "Subject" from the list of attributes.

4) Then do the same for the preview.

Once you have, click the blue "Next" button.

5) Select the template you would like to use for your email. Since we’re going to be sending all of the email contents through an attribute, I am going to pick the simplest possible template, "Simple text". You might want to select a more complex template, and use different attributes in the payload to customize the email more, but for this example we’re going to send ALL the content in a single Body attribute.

6) Delete the image row, and delete all the text in the main box. Depending on your plan you can delete the footer too. If you do this you’ll need to put an "Unsubscribe" link after the body merge tag, otherwise the email will not be able to be saved. There is an exception for transactional emails. If you’re approved for these and the emails sent via the API will be transactional, then you can remove the unsubscribe link too.

Click in the sliver of content shown, and then click on "Insert merge tag".

Like before, search for "Send email", and then click on "Body".

Click "Publish" on the preview screen, and once back at your playbook turn the switch to ON to turn on this playbook.

7) Once you have created the message it is important you edit the message to make it so people can receive it more than once. In Autopilot the default is to only allow a given message to be sent to someone once. This is to prevent accidentally sending the same message and annoying people. In this case though, we don’t want that restriction.

Go to edit the message in your playbook.

Once in the message, click the "Edit" button under "People can receive this message" and change it to "More than once".

You can enable transactional too, if you buy a custom IP address for sending email. This will allow you to overwrite sending limits and also remove the unsubscribe link.

Click "Save" to make this modification, then we are ready to send emails via the API.

Step 4 - Sending emails

Now that our playbook is published, we are able to use the API to send emails. Learn more in the Custom activities guide. Here’s an example of sending a custom activity which will cause our playbook to send an email. This example will add the contact if they don’t already exist. If they do already exist it will find that contact and send to them:

curl --location\
     --request POST 'https://api.ap3api.com/v1/activities/create'\
     --header 'X-Api-Key: PUT-YOUR-REAL-KEY-HERE'\
     --header 'Content-Type: application/json'\
     --data-raw '{
       "activities": [
         {
           "activity_id":"act:cm:send-email",
           "fields": {
             "str::first": "Chris",
             "str::last": "Smith",
             "str::email": "chris.smith@example.com"
           },
           "attributes": {
             "str:cm:subject": "Find out how to send emails via the API",
             "str:cm:preview": "A full guide to sending emails",
             "str:cm:body": "<p><strong>Bolded text for your pleasure</strong></p>"
           }
         }
       ]}'

This will send a "Send email" activity to Autopilot, which will then create or update the person as needed. The person will then enter the playbook and be sent the "Generic message" which will be filled in using the attributes from the API call.

Note that while this is being done by an API call, it can still take a minute or two for the playbook to respond and send the message.

Sending HTML in the Body

You may have noticed in the above example I was able to send HTML markup in the body of the email. This means you can create complex emails using this technique. Here’s a more substantial example of doing that:

curl --location\
     --request POST 'https://api.ap3api.com/v1/activities/create'\
     --header 'X-Api-Key: PUT-YOUR-REAL-KEY-HERE'\
     --header 'Content-Type: application/json'\
     --data-raw '{
       "activities": [
         {
           "activity_id":"act:cm:send-email",
           "fields": {
             "str::first": "Chris",
             "str::last": "Smith",
             "str::email": "chris.smith@example.com"
           },
           "attributes": {
             "str:cm:subject": "Hey you: Find out how to send emails via the API",
             "str:cm:preview": "A full guide to sending emails",
             "txt:cm:body": "<p><br /><h4>Find out more about sending emails in Autopilot</h4><br /><br /></p><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" class=\"btn btn-primary\" style=\"border-collapse: separate; mso-table-lspace: 0pt; mso-table-rspace: 0pt; width: 100%; box-sizing: border-box; min-width: 100% !important;\" width=\"100%\">  <tr>    <td align=\"center\" style=\"font-family: sans-serif; font-size: 14px; vertical-align: top; padding-bottom: 15px;\" valign=\"top\">      <table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"border-collapse: separate; mso-table-lspace: 0pt; mso-table-rspace: 0pt; width: auto;\">        <tr>          <td style=\"font-family: sans-serif; font-size: 14px; vertical-align: top; background-color: #3498db; border-radius: 5px; text-align: center;\" valign=\"top\" bgcolor=\"#3498db\" align=\"center\"> <a href=\"\" style=\"display: inline-block; color: #ffffff; background-color: #3498db; border: solid 1px #3498db; border-radius: 5px; box-sizing: border-box; cursor: pointer; text-decoration: none; font-size: 14px; font-weight: bold; margin: 0; padding: 12px 25px; text-transform: capitalize; border-color: #3498db;\">Take action now</a> </td>        </tr>      </table>    </td>  </tr></table>"
           }
         }
       ]}'