Transactional email guide

​

How it works

Sending transactional email with Loops has two steps.

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

​

Compose your email

There are two ways to create emails in Loops: 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.

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.loops.so/api/v1/transactional

Payload

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

{
  "transactionalId": "clfq6dinn000yl70fgwwyp82l",
  "email": "[email protected]",
  "dataVariables": {
    "name": "Chris",
    "passwordResetLink": "https://example.com/reset-password"
  }
}

You can add contacts to your audience from this call by adding "addToAudience": true to your payload.

​

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

​

Testing transactional emails

You can test your transactional email integration by sending to email addresses with @example.com and @test.com domains (for example [email protected] and [email protected]).

Everything will work as normal (e.g. you will receive success responses from the API), but no emails will be sent to @example.com or @test.com email addresses, making this a good way to test transactional emails without affecting your sending domain’s reputation.

​

Errors

​

Links look like x-webdoc://....

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.