Getting started
After Triggered Email has been enabled for your account, you can find it under the Channels menu, Triggered Email.
Any of your existing email campaigns which have External event as their recipient source will be listed on the Mail Streams tab. If these do not contain any incompatible settings (see below), they can be used straight away as mail streams. Otherwise they must be copied and their settings updated before they can be used.
Adding a Triggered Email sender address
Once Triggered Email has been activated for your account, new mail streams can only be set up with a dedicated sender address that must be enabled by Emarsys.
A separate sender address is needed because we send the triggered emails using a dedicated infrastructure, to ensure optimal deliverability.
You can have multiple sender addresses on one account, but the ones you use for Triggered Email must be enabled by Emarsys Support and cannot be added via the interface.
About mail streams
A mail stream is an email campaign that is copied, personalized and launched when the event is triggered. It must be associated with an external event and have the dedicated sender address selected in the From (email address) field before it can be activated.
Mail streams are created like any other email campaign (see below).
The Mail Streams tab
The second tab on the Trigger Email page is the Mail Streams list.
This lists all the external event-based email campaigns in your account, as well as any mail streams that have since been created.
In addition to the name, Trigger and Admin (user) who created it, this list provides the following information and controls:
-
Template - The Emarsys template used to create the mail stream. There are three possibilities:
- If it uses an Emarsys template created using one of our older content editors, it shows the template name.
- If it uses a template created using the VCE, it shows Block-based (this will be fixed in a future release to show the template name).
- If no template was used, it will show HTML.
-
Status - The possible statuses are:
- Active - The mail stream is active and can send emails.
- Inactive - The mail stream was active, but has been deactivated and cannot send any emails.
- Activating - The mail stream has just been activated and its settings are being validated.
- In design - The mail stream has not yet been activated.
The recipient source (the selected external event) can only be adjusted prior the campaign is first activated. Once a campaign is activated or you set the source to external event, you cannot change the recipient source anymore.
To change the recipient source, recreate the campaign or contact Emarsys Support.
Incompatible mail streams
If you have created an email campaign and set the recipient source to External event, but have not assigned the right sender domain, it will be listed with the rest of the mail streams but cannot be edited.
Such mail streams are classed as incompatible and are marked as such in the Status column.
Mail streams can also be incompatible if they were scheduled to launch a set time after the external event was triggered.
To use an incompatible mail stream as a triggered email mail stream, you must copy it and then change the settings to make it compatible.
A mail stream may show on the list as both Active and Incompatible. This indicates that the campaign is a valid external event-driven campaign that was launched from the Email Campaigns page, and is using a different sender domain.
Such campaigns will continue to launch emails until they are deactivated, and will be included in the Triggered Email dashboard and reporting. However, they cannot be modified. To reuse the contents you must copy the campaign and change whatever settings (e.g. the sender address) that made the original incompatible.
Trigger sources
You can choose from the following options for triggering your mail stream:
- External events,
- Broadcast events,
- Interactions events.
These are selected in the Trigger settings section of the Email Settings page.
Using external events
When you select External event as the Trigger source, you must choose an external event for your mail stream.
The payload size limit of External events has changed:
We are introducing a limit of 1 MB for the payload size of External events effective October 24, 2023. Events exceeding this limit will not be accepted and you will receive an error response from the API. As a result, External events over the limit will not trigger any Triggered Email campaigns, Automation Center or Interactions programs.
Emarsys then provides the event_id parameter for the selected event in the interface and you can use that in the API call that triggers the mail stream.
External events can be created in the following ways:
- Manually, on the External Events page (Management menu, External Events).
- Manually, in the Trigger Settings section of the Email Settings page (see above).
- Via the API call Creating an External Event.
Using external events is the normal way to use Triggered Email, and you can enjoy all of the supported functionality of the Emarsys email module, such as personalization and reporting.
External events do not have to be unique per mail stream; the same event can trigger multiple mail streams.
Using broadcast events
Broadcast events should be used when you need to send triggered emails to contacts who are not in your contact database.
Here you are provided with the email_id parameter to use in the Launch an email campaign to virtual contacts API endpoint.
Broadcast emails are counted as normal triggered emails for billing purposes. However, they do have the following limitations:
- Personalization - As they do not reference the Emarsys database, you cannot include any personalization based on Emarsys database fields. If you want to personalize the content, you can do so from external sources by adding placeholders to the mail stream content and including them (with the corresponding values) in the JSON package delivered with the API call.
- Reporting - Emarsys does not track the delivery or responses of any broadcast event mail streams. They do not appear in any of the Emarsys reporting screens and neither we collect data for the Open Data views.
- Reply management - Replies to broadcast email campaigns are not processed by Emarsys, which means they do not appear in the Reply Management.
- Attachments - Broadcast mail streams do not support attachments.
- BCC - The BCC feature is not available for broadcast mail streams, but you can add additional email addresses to the API call.
Sending of broadcast emails is supported under the following circumstances:
-
Link tracking: You are not tracking any link in broadcast email campaigns.
- The campaign can be used as a broadcast campaign after untracking all links. To turn off link tracking for on-event type of emails, such as broadcast emails, use the toggles in the Links tab.
- All other tracked links, such as online version and unsubscribe also need to be untracked.
-
Personalization placeholders: You are not using any personalization placeholders that are referring to contact fields, for example:
$pers_12345$orcontact.12345.- You are not using any personalization placeholders that contain legacy personalization variables, for example:
%%test_variable%%.
- You are not using any personalization placeholders that contain legacy personalization variables, for example:
- Custom list unsubscribes: You cannot use custom list unsubscribes that include personalized placeholders, because it can cause issues with broadcast events.
- Customized unsubscribes: You cannot use a customized list unsubscribe link with references to contacts in broadcast email campaigns, as it is not compatible with the base concept of broadcast email. If you are unsure that you use a custom list unsubscribe link, please contact Emarsys Support. For more information, see List-unsubscribe.
-
Predict: You can have Predict enabled for your account, but cannot use predict in broadcast email campaigns.
- You cannot create and send a broadcast email campaign containing predict recommendation.
- Predict recommendation cannot be sent to a broadcast audience.
Using Interactions events
Choose Interactions events if you would like to use the Triggered Email mail stream in Interactions programs.
Triggered Email ignores the opt-in status of the contacts it sends to.
An Interactions program can only be launched once all mail streams in it are active.
Creating mail streams
There are two ways to create a mail stream.
1. Creating a mail stream from an existing email campaign
You can create a mail stream from any existing email campaign in your Emarsys account.
Ensure that you use either Block-based Email templates (using the VCE) or custom HTML templates for creating a mail stream from an existing email campaign. For further information on email templates, see the email templates documentation.
Proceed as follows:
- Copy and rename the email campaign - you can do this from both the Emails list and the Mail Streams list.
- Select the external or broadcast event that will trigger the email.
- Check that the From (email address) field has been correctly updated to the Triggered Email sender address.
After you save your settings, the email will appear as a valid mail stream in the list. You can now make any changes you want and activate it when it is ready to start sending.
2. Creating a new mail stream
You can also create a mail stream from the Triggered Email page.
This opens exactly the same email content editor that you normally use for email creation, but with the following differences.
2.1. Mail stream settings
The Email Settings page has a new section for Mail stream settings. Here you can set the mail stream to force attachments, and add the BCC email addresses.
You don’t have to check the Send only with attachment checkbox in order to be able to send attachments. Every single recipient API call can contain an attachment and Triggered Email will process them as expected.
If you do activate this check box, Emarsys will cancel all emails for this mail stream which were triggered by an API call that did not contain a valid attachment.
These emails will be listed on the Dashboard as Canceled under the Emails not sent section.
2.2. Trigger settings
Instead of the Recipient source, you can choose between external events or broadcast events (see above). You can also create a new external event from this page.
2.3. From (email address)
The From (email address) field on the Email Basics tab of the Content Creation page has your Triggered Email sender address defined. This cannot be changed.
2.4. Scheduling
The Scheduling page only has a button to activate the mail stream.
Personalizing the email content
You can personalize the triggered email with data from your contact database and with data from the transaction.
- To use data from your contact database, simply add personalization variables or conditional content as you would for any other email.
- To use data from the transaction, please see Customize your Email with Data from External Events and Capture Transactional Content for more details.
Using attachments
With Triggered Email you can attach up to 10 files per email. When using attachments you must conform to the following standards:
- Maximum size of all attachments together: 10MB.
- Maximum size of the email: 25MB.
- Supported formats: .doc, .docx, .pdf, .rtf, .csv, .xml, .xlsx, .xls, .txt
- The files must be Base64 encoded and sent with the JSON call.
- Rate limit is 300 requests/minute. Above this number the emails are queued and sent later.
Attachments will also be sent to any email addresses in BCC.
Attachments can only be sent if you are using the API to trigger the mail streams. At the moment, you cannot use attachments in Interactions.
Please also note that the attachments are not stored on the Emarsys side. To keep track of all attachments sent you can use the BCC functionality to send copies to one of your own mailboxes.
JSON sample
A sample JSON package from a triggered email containing an attachment would look like this:
{
"key_id": "3",
"external_id": "t.odinson@example.com",
"data": {
"global":
{
"itemName": "hammer",
"itemPrice": "123",
"<placeholder_name>": "<placeholder_value>",
... }
},
"attachment":
[
{
"filename": "example.pdf",
"data": "ZXhhbXBsZQo="
}
]
}Attachment error codes
There are a number of reasons why an attachment may cause an error.
| HTTP Status Code | Reply Code | Error Message |
| 400 | 5200 | Unable to add attachment; the format must be an array. |
| 400 | 5201 | Unable to add attachment; the file extension must be .pdf. |
| 400 | 5202 | Unable to add attachment; the \"filename\" key is missing. |
| 400 | 5203 | Unable to add attachment; the \"data\" key is missing. |
| 400 | 5204 | Unable to add attachment; the encoding must be base64. |
| 400 | 0 | Attachment too large. |
| 400 | 2004 | Invalid key field ID: [field_id] |
| 400 | 2005 | No value provided for key field: [field_id]. |
| 400 | 2008 | No contact found with the external ID: [key_id] - [external_id]. |
| 400 | 2010 | More contacts found with the external ID: [key_id]. |
| 400 | 5001 | Invalid event ID for customer. |
| 400 | 2012 | Invalid contact ID for customer. |
| 400 | 5005 | No program or campaign is triggered. |
| 400 | 7000 | No attachment was found. |
Forcing attachments
If your triggered email requires an attachment, for example an invoice, you can prevent the email from being launched if the attachment is not present.
To do this, go to the Email Settings page and activate the checkbox Send only with attachment.
If, when the email is triggered, no attachment can be found or the attachment file cannot be sent for one of the reasons described above, an error will be returned and the email will be listed in the reporting Results Summary page under No attachment, and in the drill-down report for the Dashboard Emails not sent section.
Testing mail streams
There are two ways to test a mail stream.
1. Sending a testmail
Before the mail stream is activated, you can use the standard testmail functionality of the email editor to test the design and content of the email.
- If you already have your dedicated sender email address set up, you can use the testmail feature as normal.
- If you do not yet have your sender email address, you must change the recipient source to something other than external event and select a different address. When you are satisfied that the contents are correct, set the source back to external event.
2. Testing the mail stream
Once you have tested the content, you can also test the mail stream by activating it and triggering the external event yourself, before it has been implemented in a live environment.
Activating mail streams
Once you have finished creating the email, you can activate the mail stream in one of two ways:
- Manually, on the Scheduling page (see above).
- Manually, via the toggle on the Mail Streams list (see above).
Activation may take a few minutes, as all the settings are checked and validated. In the event of a setting being incompatible with Triggered Email, you will receive an error notification and must change the settings and activate the mail stream again.
Triggering emails
Once you have successfully activated your mail stream and associated it with the external event, you need to associate that event with whatever activity will trigger the mail stream. You can do this in the following ways:
- Using the API endpoint Triggering External Events to trigger the email on its own.
- Mapping the external event to an event in a third-party platform (if an Emarsys integration for that platform exists).
- Using the API endpoint Triggering External Events to trigger an Interactions program with External Event as the entry point (not recommended - see below).
Using Triggered Email with Interactions
You can map a triggered email to an external event that is the entry node for an automated program. You can also apply filters to event attributes and use them to personalize your content in Interactions.
External data
Any external data contained in the external event API call will be stored by Interactions for each contact, while that contact is in the program. It can be re-used to personalize content in any other emails in the program.
You can also base a program on the results of a triggered email, in which case you should set up a recurring filter entry point and filter for responses to the original email.
You can filter for triggered and transactional emails using segments and categories.
Working with active mail streams
Once a mail stream is active, you have the following options.
Editing active mail streams
You can edit any part of a mail stream, except for the link domain.
To edit the link domain first you need to copy your email campaign and then you can update the link domain of it.
To edit a mail stream complete the following steps:
1. Deactivate the mail stream in either of the following ways:
- Deactivate it via the toggle switch on the Mail Streams list.
- Deactivate it on the Scheduling page.
While a mail stream is inactive, all incoming external events will be ignored and you will not be notified.
2. Copy the mail stream either from the Emails list or from the Mail Streams list.
Copying the mail stream is strongly recommended in case of business-critical emails.
To edit an Email Campaign that is running in an Interactions program, first you need to freeze program, deactivate the mail stream, then you can edit it. When you are ready with the changes, activate the mails stream and resume the program.
3. Edit the copied mail stream.
4. Replace the old mail stream with the new, edited one.
After you saved your settings, the email will appear as a valid mail stream in the list.
5. Activate the updated, new mail stream on the Scheduling page.
Use the same external event or define a new one
You can use the same external event or define a new one, depending on your requirements:
- Using the same external event means you don't have to make any changes to the trigger or the API call, but you will have to manage (pause) the incoming triggers on your side while you deactivate the old mail stream and activate the new one.
- Using a new external event means that you will have to swap the triggers to the new event, but this ensures that no incoming triggers can get lost in the meantime.
Aborting incompatible mail streams
If you have a legacy external event campaign in your mail streams list, you cannot edit or deactivate it but can only abort it.
If you want to make changes to such a campaign, copy it and make the changes to the copy. Then ensure that the copy is a valid mail stream, before activating it and aborting the legacy campaign.
Using Triggered Email with external integrations
If you are using an Emarsys integration with a third-party provider, you should use Triggered Email to send all your transactional emails for the integration.
Simply set up and activate the mail stream as described above, and then map the corresponding external events according to the instructions in the integration manual.
Triggered Email reporting
To view the Reporting page for a mail stream, click the Reporting icon in the Mail Streams list.
This will open at the Trend Reporting tab, showing the responses and conversion rates for the mail stream over time. All the regular reporting screens are also available.
Mail stream reporting is also accessible on the regular Email Analysis page.
Known issues and limitations
Below is a list of the current limitations to this product.
- Mail streams list - Email templates created using the VCE will be listed as Block-based in the Mail Streams list, and not by their name.
-
Editing launched mail streams - Editing of already launched mail streams is only possible by using the Block-Based Editor or the new version of the HTML editor. Using the old version of the HTML editor will result in the following error message: "This email is scheduled or has already been launched and cannot be edited."
- To edit a launched mail stream, click Switch to the new editor at the top of the old version of the HTML editor.
- A/B Testing triggered emails - To correctly test your triggered emails, you need to include them into Interactions programs.
For more information on using Triggered Email with Interactions, see Send email.
Do not use block targeting in combination with Trigger Based email/External Event (Transactional Emails) campaigns.