Enabling Triggered Emails

Follow

Before you can create triggered emails, 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

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 Dynamic Yield the most updated state of the cart content of 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 (Web)

    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.

Identify Your Visitors Onsite

Identify onsite visitors to associate a Dynamic Yield generated 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). Once 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 External ID-based Implementation.

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 that have opted in. This option is only relevant if your identifier is email. Learn more about 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. 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 table below.
    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 opt-in msg, 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. You should 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 table below.
    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 Hashed Email

    
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"
  }
});

Once the User Email Feed is synced, it overrides any previous opted-in and opted-out information from the previous version of the User Email Feed and from the Messages Opted-In and Opted-Out Events. 

Tip: It is recommended to start with a User Email Feed onboarding, to immediately allow Dynamic Yield send emails to all of your opted-in users, even if you later decide to manage opted-in users with client-side events. 

Integrate Your ESP

We recommended that you send the triggered emails through your ESP. That way, you can see the performance data in your ESP analytics, and you can manage frequency together with the rest of your email program. Dynamic Yield supports the following integration options (click each one for integration instructions):

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 will send the triggered emails for you. Each customer can receive a dedicated IP and warm-up can be supported upon request. For details, contact your Technical Account Manager. They will provide you with sender authentication and reverse DNS entries that you will 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 will need to delete or archive any existing triggered email campaigns.

Permitted IPs

If you're using Custom ESP, Responsys or Emarsys, please add the following IPs to your allowed list, based on your DY platform location

US:

3.92.38.28
3.227.221.249
54.145.37.112
75.101.154.167

EU:

18.197.234.165
3.127.189.219
18.158.108.19
18.192.189.87

 

Completed all steps?

Great! You can now create your first triggered email campaign