Getting Started with Triggered Emails

Triggered emails enable you to automatically send a personalized email to users based on their behavior. For example: Remind users of items they left in the cart, notify them that a product they viewed is now sold at a lower price, or use any event as a trigger. Triggered emails are supported only for implementations of type Website.

Before you can create triggered email campaigns, you must complete the following steps. These steps are technical and might require a web developer.

1. Report updated cart state
2. Identify your visitors onsite
3. Manage opted-in users
4. Integrate with your ESP

1. Report updated cart state

Report to Dynamic Yield the state of your cart, using one of the following options:

• Implement Add to Cart and Remove from Cart events, both with cart parameters. Learn more about implementing events.
• Implement a Sync Cart State event, to report the most updated state of the cart for each user.
  Sync Cart Event

  Parameters

  • name: Human-readable name, use "Sync Cart".
  • properties: A container for the event properties as specified in the table below.

  Property	Description	Type
  dyType	Must be “sync-cart-v1”	String
  currency	Optional non-default currency used	String  List of supported currencies
  cart	The absolute current cart state (including the last added item). Products should be in order from oldest to newest. Cart Properties:
  	productId: SKU exactly as it appears in the product feed	String
  	quantity	Number
  	itemPrice	Number
  	size: Optional	String

  JavaScript example

  DY.API("event", {
    name: "Sync cart",
    properties: {
      dyType: "sync-cart-v1",
      currency: "any supported currency code", // Optional non-default currency used
      cart: [ //Mandatory, the order of products should be from oldest to newest
        {
          productId: "sku-4324-bg",
          quantity: 2,
          itemPrice: 12.34,
        },
        {
          productId: "item-34454",
          quantity: 1,
          itemPrice: 34.45
        }
      ]
    }
  });

  For the Experience API format, see Sync Cart.

2. Identify your visitors onsite

Identify site visitors to associate a Dynamic Yield user ID for all site visitors (DYID) with a hashed email address or external ID as a cross-channel Customer ID (CUID). There are two ways to do this:

• Identification with a hashed email address:
  • Use the identify schema events (login, signup, and newsletter subscription). For details, see Events for Web.
  • Add a hashed email as a URL parameter in all email links (recommended). When this is added, a custom action added to the site can capture the hashed email from the site URL and trigger an Identify API call.
• Identification with an external ID: Via API. For details, see Identifying users with the Identify API.

3. Manage opted-in users

Not all users opt-in (agree) to email communications. You need to let Dynamic Yield know which users opted-in. There are two ways to do this:

• Upload a User Email feed: Every day, upload a list of email addresses of users who have opted in. This option is only relevant if your identifier is email. Learn more about the User Email feed.
• Fire events on the client-side: You can inform Dynamic Yield about new users who opt in or opt out at the time they do so. Note that opt-in events are only supported on the client-side. This is done by implementing the following events:
  Message opt-In

  Mark individual user emails to receive triggered emails. The email recipient list is managed by Dynamic Yield using these events.

  Message opt-in parameters

  • name: Human-readable name, use "Message Opt-In".
  • properties: A container for the event properties as specified in the following table.

  Property	Description	Type
  dyType	Must be “message-optin-v1”	String
  cuidType	Must be one of the following: “email” – for email "external" – for a custom identifier (such as CRM user ID)	String
  plainTextEmail	Use this property if the cuidType is "email". Value should be a plain text email address. Plain text email addresses are required in this API as they are used for sending the triggered emails.	String
  externalId	Use this property if the cuidType is "External". Value should be a custom user identifier that your ESP can map to email addresses.	String

  For details on using external ID and message opt-in, see External ID-based Implementation.

  JavaScript examples for cuidType of email

  DY.API("event", {
    name: "message opt in",
    properties: {
      dyType: "message-optin-v1",
      cuidType: "email", //can be "external" or "email"
      plainTextEmail: "REPLACE_WITH_EMAIL_ADDRESS", //mandatory valid plain text email address if cuidType is "email"
    }
  });
  

  JavaScript examples for cuidType of external

  
  DY.API("event", {
    name: "message opt in",
    properties: {
      dyType: "message-optin-v1",
      cuidType: "external", //can be "external" or "email"
      externalId: "[REPLACE_WITH_EXTERNAL_ID]", //mandatory if you cuidType is "external"
    }
  });
  

  This event type involves passing a user's plain-text email address, which is considered PII (personally identifiable information). Dynamic Yield maintains PII data in a dedicated personal data storage and complies with security standards in the transfer and persistence of this data. Pass this data only according to local law.

  Message opt-out

  Mark individual user email addresses to not receive triggered emails.

  Message opt-out parameters

  • name: Human-readable name, use "Message Opt-Out".
  • properties: A container for the event properties as specified in the following table.

  Property	Description	Type
  dyType	Must be “message-optout-v1”	String
  cuidType	Must be one of the following: “he” – for email "external" – for a custom identifier (such as CRM user ID)	String
  hashedEmail	Use this property if "cuidType" is "he". Value should be the SHA256 hash of the plain-text email address in lower case.	String
  externalId	Use this property if the cuidType is "External". Value should be a custom user identifier that your ESP can map to email addresses.	String

  JavaScript examples for cuidType of hashed email

  
  DY.API("event", {
    name: "message opt out",
    properties: {
      dyType: "message-optout-v1",
      cuidType: "email", //can be "external" or "he"
      hashedEmail: "REPLACE_WITH_EMAIL_ADDRESS", //mandatory valid hashed email address if cuidType is "he"
    }
  });
  

  JavaScript examples for cuidType of external ID

  
  DY.API("event", {
    name: "message opt out",
    properties: {
      dyType: "message-optout-v1",
      cuidType: "external", //can be "external" or "he"
      externalId: "[REPLACE_WITH_EXTERNAL_ID]", //mandatory if you cuidType is "external"
    }
  });
  
  

When the User Email feed is synced, it overrides any previous opted-in and opted-out information. 

4. Integrate your ESP

We recommended that you send the triggered emails through your ESP. This way, you can see performance data in your ESP analytics, and you can manage message frequency together with the rest of your email program.

Dynamic Yield supports the following integration options (click for integration instructions): Emarsys, SendGrid , Listrak , Responsys , or Custom ESP (any other ESP that supports RESTful APIs).

If your ESP is not included in this list and does not support restful APIs for custom integration, you can still use triggered emails – Dynamic Yield can send the triggered emails for you. We provide you with a dedicated IP, and warm-up can be supported upon request. Contact your Technical Account Manager for more details, and for the sender authentication and reverse DNS entries that you need to update in your DNS host provider.

Note: You can only enable a single integration for triggered emails. If you want to switch to a different ESP, you must delete or archive any existing triggered email campaigns.

Permitted IPs

If you're using a custom ESP, Responsys, or Emarsys, add the following IPs to your allowed list, based on your Dynamic Yield platform location

Completed all the steps?

Great! You can now create your first triggered email campaign.

Triggered Emails without a Dynamic Yield script implementation (early access)

You can now run triggered emails without implementing the Dynamic Yield script on your site. You will still need to be on a Website platform, and not on API. If you want to join the early access program, read the following limitations and contact your account manager:

• Simulation mode doesn't work as it requires the script to run on your site. To QA the campaign, add one or more QA users to an audience (by cookie or event) and target the campaign to these users. 
• Firing opt-in and opt-out events on the server-side is not supported. To update the list of users who are opted-in for emails, upload a User Email feed on a daily basis.
• Reports show clicks, impressions, and users. Without the script, the activity of the users onsite (such as purchases) do not appear in the report. 

Contact your Customer Success Manager for more information.