Triggered Email Scenario Guide For Developers

This page contains conceptual, scenario, and procedural information that you can use in preparing to use triggered send emails. It discusses API calls you can use to trigger send emails created in the application. The content of the emails and the interaction to trigger to send the emails can be created in the application. See the Triggered Emails Guide for more information. The Marketing Cloud SOAP API is the preferred method to integrate triggered send emails with your business applications due to its superior error-handling capability and the ability to retrieve tracking data.

This page discusses email messages. You can also create triggered messages for delivery through SMS functionality. Use the REST API to send triggered SMS messages via MobileConnect.

A triggered email is an email communication sent to an individual (subscriber) in response to a subscriber action. For example, sending a confirmation message after a customer makes a purchase is a triggered email.

The following graphic illustrates the process to initiate a triggered email:

To set up your integration to use this process, you must:

• Identify the triggering events and create the code that triggers the email.
• Create the triggered email message interaction.

You identify the events that trigger the email and create code outside of Marketing Cloud to call the triggered email interaction that sends the email. Examples of triggering events include:

• Completing a web form
• Purchasing a product through your website
• Abandoning the shopping cart
• Performing a search

Your code also captures any subscriber information necessary to send the message. At a minimum, the subscriber email address is required to send the triggered email. You then create code to cause the events that trigger an email to call the Marketing Cloud API and pass the subscriber information to Marketing Cloud.

The API call executes the interaction, which sends the email.

When you define a triggered email interaction (sometimes called a triggered send definition), you provide information that the system uses each time an email is triggered. Interactions have a unique External Key value that is used by the API calls to initiatethe interaction.

A send classification lets you define parameters for an email job in a central location and reuse those parameters for multiple triggered email interactions.

The content is the message to send when the interaction is triggered. You create triggered email content with the screens on the Content tab within Marketing Cloud. You use the same tools that are available to create user-initiated email. For example, you can target the message using personalization and dynamic content. See the online help available in the application for more information.

You can select a subscriber list for the triggered email interaction. When a subscriber who is not already on the selected list triggers the interaction, you can choose to have the application add the subscriber to the list. When a subscriber who is already on the selected list triggers the interaction, you can choose to have the application update the subscriber information.

If your account has data extensions enabled, you can select a data extension for the triggered send instead of a subscriber list. The data extension behaves the same way as the list, except that the fields that are required to add a subscriber are based on the definition of the data extension instead of on the subscriber attributes. The data extension you use must be created from the TriggeredSendDataExtension template.

Do not identify any column as a primary key when you create a data extension from the TriggeredSendDataExtension. TriggeredSendDataExtensions are designed to have a single row for each triggered email request.

The send options you specify on a triggered email interaction relate to how the interaction tracks statistics from the messages.

You can also specify a keyword to categorize the triggered email interaction. API calls can use the keyword to find one or more related triggered email interaction.

Triggered email interactions must be started before you can use them to trigger live or test emails. You can use the send options on the interaction to prevent activity from your test sends from appearing in tracking and reports. Any more isolation of test sends from your production environment must be done using the code around the triggering events.

Marketing Cloud collects summary tracking and subscriber-level tracking for a triggered email. You can see this tracking in the application or retrieve the tracking with the API.

When a subscriber triggers an email, the List Detective tool scans the email address. The List Detective protects your deliverability by preventing the sending of email to bad addresses. See the application online help for more information on List Detective. If the email address of the person triggering the email is identified as bad by List Detective, the system does not send the email message, so the send does not appear in your tracking. If you collect the triggering email addresses in a data extension, the List Detective prevents bad email addresses from being collected.

If your account has message priority enabled, Marketing Cloud can allow you to choose the priority of triggered sends. Priority dictates the time a new triggered send request could remain queued for processing. Once processing is completed, the request is handed off to mail processing systems to evaluate message content and send the rendered message content via the Marketing Cloud sending engine. You can designate the following priorities:

• High: Queued immediately.
• Medium: Queued up to 3 minutes by default. It then takes up to 1 minute to send the email.
• Low: Queued every 5 minutes. It then takes up to 5 minutes to send the email.

Marketing Cloud offers the ability to use asynchronous processing at the API layer with triggered sends. Asynchronous processing allows your API calls to be queued in an async server before being processed. When using asynchronous processing, an instantaneous response lets your system know that the call has been queued. The response does not provide details on if the request was invalid due to missing required fields or other validation concerns. If you need immediate feedback on these types of errors, use standard synchronous processing.

HTML attributes are a type of attribute that can be used only with triggered sends. Subscriber attributes of this type can contain more than the 2000 characters are allowed in a normal subscriber attributes. HTML type attribute can contain Unicode characters to be delivered to an email template dynamically.

Ideal use cases for HTML attributes are passing preprocessed tabular data (like an order confirmation) along with other subscriber information when an event is triggered.

The name of an attribute indicates whether the attribute is of the HTML type. Attributes with the prefix HTML__ (two underscores) are treated differently by the triggered send email engine. Using HTML attributes in the content of an email is similar to using other attributes:

%%HTML__table%%

HTML attributes don't have robust support for link tracking, so ideal use cases don't rely on the need to track links in the HTML content.

The data extension used to capture triggered send subscriber data supports automatic data retention policies. When defining a triggered send with a data extension, you specify how long to retain the data. The default is six months. You can select a retention period ranging from one day to forever. The system deletes the data at the end of the retention period. Subscriber data is not removed by the data retention policy; only the data extension data is removed.

You can delete data from the data extension, as well as import the data back in using AMPscript.

This feature obscures any information permanently stored in Marketing Cloud (other than the subscriber key) that would personally identify a subscriber. This includes email address and subscriber name. Marketing Cloud one-way hashes the information that comes into our system, and Marketing Cloud has the only hash key. Data is encrypted and decrypted by Marketing Cloud. For future reconciliation purposes, customers are encouraged to keep a copy of all their subscriber records.

Please contact your account representative if you would like to activate the data retention or data obscuring features.

Use triggered emails to provide automated, personalized responses to your customers' activities on your website. Emails are trackable, targeted, and sent in real time. With triggered emails, you can:

• Track your opens, clicks, and emails.
• Capture subscribers to give the option to opt-in to mailing lists.
• Target the content of emails by using tools such as personalization, dynamic content, and
• AMPscript.
• Achieve high deliverability and scalability.
• Maintain the ability to change content over time.

Use auto-forward and auto-reply with messages processed by Reply Mail Management.

• Define and send a message triggered by an event within Marketing Cloud, such as a subscriber adding themselves to a list using Web Collect, or by an event outside of Marketing Cloud, such as an action on your website.

Before you can use the Marketing Cloud API to trigger emails, you need the following information:

• You need a user on your account that is enabled to use the API. You use the API user's name and password to log in to your account programmatically. Contact your Marketing Cloud account manager to create an API user for your account.
• Your organization must identify the events that trigger the email message.
• You need to capture the subscriber attributes that are needed in the content of the email message for personalization and dynamic content.

You need the External Key of the interaction to trigger. The interaction can be created within the application or by using the API.

Use the following location to create and test your triggered emails. For the SOAP API, you need the WSDL (Web Service Description Language) file that resides at this location: https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/etframework.wsdl

The following scenarios cover the most common business processes around triggering emails with code samples.

If you choose to create and manage your triggered email interaction and view tracking in the application, you use the API to trigger an email when the triggering event occurs. You use only the first two scenarios:

• Triggering an Email
• Determining the From Information at Send Time

If you choose to create and manage your triggered email interaction and retrieve tracking with the API, you also use the remaining scenarios:

• Creating a Triggered Email Interaction
• Pausing an Interaction
• Updating a Triggered Email Interaction
• Publishing Changes to an Interaction
• Starting a Triggered Email Interaction
• Retrieving Tracking Data

You must start the triggered email interaction after you create it in order for the interaction to send emails. To change the interaction after you start it, you must pause the interaction. After you make the updates, you must publish changes and restart the triggered email interaction.

If you use the feature to determine the from email address at send time, the system uses the subscriber owner as the from address. In this case, the owner email address cannot be the same email address used by Reply Mail Management (RMM).

The Subscriber.Owner property on the TriggeredSend object is primarily for dynamically changing from name / from address.

The Subscriber.Owner.Client property is used to specify an On Your Behalf account to associate the subscriber with.

Use the following code to cause events in your website or application to trigger a Marketing Cloud email. If you work within an Enterprise 2.0 account, specify the ClientID property for the business unit in which the triggered send resides.

For information on ETIntegrationFramework, review Choose Your Programming Language.

You use the following code to cause events in your website or application to trigger a Marketing Cloud email with a From Name and From Address specific to a subscriber attribute. For example, you could use this functionality to send an email message that is from the regional sales manager responsible for the state the subscriber resides in.

Response (If an invalid email address was passed)

Creating a triggered email interaction through the API allows you to avoid using the application interface. For example, you might use this functionality if you have created your own interface for creating triggered email interactions.

You must start the triggered email interaction before the interaction sends emails.

You must pause the triggered email interaction before you can make changes to it. Pausing the interaction sets the status to Paused and prevents the interaction from sending emails. Requests for the triggered email are queued to be sent after you start the interaction.

To pause a TriggeredSendDefinition, set the state of the TriggeredSendDefinition to Inactive. In the Inactive state, the TriggeredSendDefinition is accepting and queuing TriggeredSend requests. In this state, a marketer can make modifications to the definition and associated email and content areas and publish changes by setting the RefreshContent property to True.

Updating the triggered email interaction is the process of changing the message content or other parameter of the interaction. You must pause the interaction before you can update it. You must publish changes after you update in order for the changes to be available to the interaction.

When updating a TriggeredSendDefinition, set only the properties you want to update and the key of the TriggeredSendDefinition.

After you update a triggered email interaction, you must publish the changes to make them available. You publish changes by setting the RefreshContent property to True. After you publish the changes, you must start the interaction in order for it to resume sending emails.

Starting a triggered email interaction sets the status to Active and allows the interaction to send emails in response to trigger events. You must start a triggered email interaction after you create it and after you publish changes to it.

You can view tracking data in the application or retrieve it using the SOAP API.

Results

You use the following API objects when sending triggered emails.

• TriggeredSendDefinition - The triggered email interaction
• TriggeredSend - An instance of the email being triggered
• TriggeredSendCreateResult - The result of creating a TriggeredSend object
• TriggeredSendExclusionList - Used to exclude subscribers from a send definition
• TriggeredSendType (Enum) - The triggered send type, represented by a numeric value
• TriggeredSendStatus (Enum) - The triggered send status, represented by a numeric value
• SendClassification - The send classification of the triggered email interaction
• DeliveryProfile - The record that contains the IP address, domain, header inclusion, and footer inclusion information for the triggered email interaction
• SenderProfile - The record that contains the from name and from email address for the triggered email interaction

• OpenEvent - An instance of a subscriber opening an email
• SentEvent - An instance of a subscriber being sent an email
• NotSentEvent - An instance of an email not being sent to a subscriber due to an issue with the subscriber information-for example, the subscriber being unsubscribed
• BounceEvent - An instance of an email bouncing
• UnsubEvent - An instance of a subscriber unsubscribing
• ClickEvent - An instance of a subscriber clicking a link in an email
• ForwardedEmailEvent - An instance of a subscriber forwarding an email message using the Forward-to-a-Friend feature
• ForwardedEmailOptinEvent - An instance of a new subscriber opting in to a mailing list after receiving an email forwarded using the Forward-to-a-Friend feature

See the list of error codes for possible errors when sending triggered emails.

• Type: System
• Message
• Triggered Send Definition Cannot Be Activated

• Type: System
• Message
• Triggered Send Definition Cannot Be Canceled

• Type: System
• Message
• Triggered Send Definition Cannot Be Deactivated

• Type: System
• Message
• Triggered Send Definition Cannot Be Updated

• Type: System
• Message
• Triggered Send Definition Cannot Be Deleted

• Type: System
• Message
• Triggered Send Definition Content Cannot Be Refreshed

• Type: Validation
• Message
• Triggered Send Definition Object ID or Customer Key Not Found

• Type: Validation
• Message
• Triggered Send Type Not Found

• Type: Validation
• Message
• Triggered Send Definition Object ID Found

• Type: Validation
• Message
• Triggered Send Definition Email ID or Partner Key Not Found

• Type: Validation
• Message
• Triggered Send Definition Send Classification Not Found

• Type: Validation
• Message
• Triggered Send Definition Not Found

• Type: Validation
• Message
• Triggered Send Definition Email Not Found

• Type: Validation
• Message
• Triggered Send Definition List Not Found

• Type: Validation
• Message
• Triggered Send Definition Header Content Not Found

• Type: Validation
• Message
• Triggered Send Definition Footer Content Not Found

• Type: Validation
• Message
• Triggered Send Definition From Name Not Found

• Type: Validation
• Message
• Triggered Send Definition From Address Not Found

• Type: Validation
• Message
• Triggered Send Definition List Required

• Type: Validation
• Message
• Triggered Send Definition Auto Add or Auto Update Not Found

• Type: Validation
• Message
• Triggered Send Definition Delivery Profile Header Content Not Found

• Type: Validation
• Message
• Triggered Send Definition Delivery Profile Footer Content Not Found

• Type: Validation
• Message
• Triggered Send Definition Customer Key Invalid

• Type: Validation
• Message
• Triggered Send Definition Name Invalid

• Type: Validation
• Message
• Triggered Send Definition Email Subject Invalid

• Type: Validation
• Message
• Triggered Send Definition Email Partner Key Invalid

• Type: Validation
• Message
• Triggered Send Definition List Partner Key Invalid

• Type: Validation
• Message
• Triggered Send Definition From Name Invalid

• Type: Validation
• Message
• Triggered Send Definition From Address Invalid

• Type: Validation
• Message
• Triggered Send Definition Keyword Invalid

• Type: Validation
• Message
• Triggered Send Definition BCC Email Invalid

• Type: Validation
• Message
• Triggered Send Definition Dynamic Email Subject Invalid

• Type: Validation
• Message
• Triggered Send Definition Email Invalid

• Type: Validation
• Message
• Invalid Personalization String

• Type: Validation
• Message
• Triggered Send Definition Send Window Open Invalid

• Type: Validation
• Message
• Triggered Send Definition Send Window Close Invalid

• Type: Validation
• Message
• Send Speed Governor Not Enabled

• Type: Validation
• Message
• BCC Email Not Enabled

• Type: Validation
• Message
• Multipart MIME Not Enabled

• Type: Validation
• Message
• Dynamic Content Not Enabled

• Type: Validation
• Message
• All Subscribers Access Not Enabled

The details of the error response include these error IDs and codes, but that response may not include the message associated with these errors.

• Type: Validation
• Messages
• Triggered Send Object not found
• Resolution
• Ensure you are passing a TriggeredSend object into the API call

• Type: Validation
• Messages
• The Triggered Send Definition is not completely configured or in a new status. Please check Triggered Send Definition configuration. (Needs to be updated)
• Resolution
• Complete the configuration of the Triggered Send Definition or start the Triggered SendDefinition.

• Type: Validation
• Messages
• Triggered Send Definition ID/Customer Key is invalid (misspelled in code)
• Triggered Send Definition ID/Customer Key don't match (misspelled in code)
• Triggered Send must be in an Active or Inactive status
• No Triggered Send Definition ID or External key supplied (needs to be updated)
• Triggered Send Definition ID is invalid (needs to be updated)
• The Triggered Send Object must contain the Triggered Send ID or the Customer Key (Needs to be updated)
• The TriggeredSendDefinitionID provided is not valid for this account. Please check Triggered Send Definition configuration (Needs to be updated)
• Invalid Customer Key
• The Triggered Send Definition is not completely configured or in a new status. Please check Triggered Send Definition configuration.
• Resolution
• Ensure the Triggered Send Definition is started.
• Ensure the Triggered Send Definition object contains a populated CustomerKey or ObjectID property.
• Ensure the Triggered Send Definition object CustomerKey or ObjectID property is valid.
• If the message states "Exception occurred during [CreateTriggeredSend]", contact Marketing Cloud support.

• Type: System
• Messages
• Exception occurred during [CreateTriggeredSend]
• Resolution
• Contact Marketing Cloud support

• Type: System
• Messages
• Exception occurred during [CreateTriggeredSend]
• Resolution
• Contact Marketing Cloud support

• Type: System
• Messages
• Exception occurred during [CreateTriggeredSend]
• Resolution
• Contact Marketing Cloud support

• Type: Validation
• System
• Messages
• Unhandled exceptions related to TriggeredSend subscriber processing
• Subscriber was excluded by domain exclusion list.
• Subscriber Owner FromEmail property value is set to an invalid email address
• Resolution
• If using the FromEmail property on the Subscriber's Owner object, ensure the value is a valid email address
• If this code is on the Subscriber in the SubscriberFailures array on the TriggeredSendCreateResult object, log the subscriber and mark them undeliverable (as the email address' domain in on the Marketing Cloud spam filter).
• Contact Marketing Cloud support

• Type: Validation
• Messages
• The Triggered Send Object must have subscribers associated with it
• Resolution
• Add one or many Subscribers to the TriggeredSend object

• Type: Validation
• Messages
• Unable to queue Triggered Send request. There are no valid subscribers.
• Triggered Send request was not queued. There are no valid subscribers.
• Resolution
• If using SOAP, check the SubscriberFailures array on the TriggeredSendCreateResult object
• Ensure all required attributes of the subscriber are passed in

You can pass the following strings in as the value of the TimeZone parameter, and they are converted to the appropriate numeric strings.

• Triggered Emails Guide
• Mobile Messages
• MobileConnect API
• Send Classifications
• Data Extensions
• Triggered Emails Guide
• What Happens When You Click Send?
• AMPscript Guide
• Reply Mail Management Instruction Guide
• Error Codes
• Asynchronous Processing