Documentation / Product / Integrations / SendGrid

SendGrid: Send Triggered Emails

You can use Lytics to trigger a SendGrid transactional email to your customers when they enter a Lytics audience. For example, send a welcome email when a customer moves from unknown to known, or a retention email when a customer becomes disengaged.

Integration Details

  • Implementation Type: Server-side.
  • Implementation Technique: REST API with audience triggers.
  • Frequency: Real-time.
  • Resulting data: An email sent to users entering the Lytics audience selected with the SendGrid templated selected. The payload of this send request may be populated with Lytics profile data and content recommendations for the user depending on configuration.

The workflow uses SendGrid's v3 Mail Send API to deliver emails with the template you select during configuration. Thus before you can set up this workflow, you must first have created the dynamic transactional template you will use in your SendGrid account. Each time a user enters the audience selected during configuration, the workflow will:

  1. Populate a payload with Lytics user profile fields and content recommendations as described in the fields section below.
  2. Use the Mail Send API to trigger the email.

The workflow will then wait for more users to enter the audience, and repeat this process as necessary.

Note: SendGrid's v3 API does not support "Legacy" Transactional Templates, thus they are not supported by this integration. If you have any legacy templates in your SendGrid account, they will not be available to choose from when selecting the template for this workflow. Please ensure that you first migrate any existing legacy template you may want to use. See SendGrid's legacy template migration documentation here.

Fields

As mentioned above, the payload to the SendGrid Mail Send endpoint is populated with the following keys under personalizations.dynamic_template_data:

  • User Fields: Populated as key/value pairs where the key is the name of the user field.
  • Content Recommendations: Stored under the recommendations key. See the example below for formatting.

Example email payload:

{
    "template_id": "abc",
    "from": {
        "email": "[email protected]"
    },
    "reply_to": {
        "email": "[email protected]"
    },
    "personalizations": [{
        "to": [{
            "email": "[email protected]",
            "name": "Full Name"
        }],
        "dynamic_template_data":{
            "name":"Sample Name",
            "address01":"1234 Fake St.",
            "address02":"Apt. 123",
            "city":"Place",
            "recommendations": [
                {  
                    "url":"www.getlytics.com/blog/post/intent_through_content",
                    "title":"Understanding User Intent Through Content",
                    "description":"Customer Intent comes from understanding the connection between engagement and its contexts. Content modeling and affinity graphs makes interpretation of intent a lot easier. Learn how marketers can benefit from this.",
                    "topics":[  
                        "customer data platform",
                        "data science",
                        "content marketing",
                        "personalization"
                    ],
                    "topic_relevances":{  
                        "content marketing":1,
                        "customer data platform":1,
                        "data science":1,
                        "personalization":1
                    },
                    "primary_image":"https://www.getlytics.com/img/blog/posts/intent_through_content/intent_through_content-bg.gif",
                    "author":"",
                    "created":"2016-06-08T16:11:45.599594093Z",
                    "id":"-3435113786560588929",
                    "sitename":"Lytics",
                    "stream":"default",
                    "path":[  
                        "blog",
                        "blog/post",
                        "blog/post/intent_through_content"
                    ],
                    "aspects":[  
                        "article"
                    ],
                    "language":"unknown",
                    "updated":"2016-06-09T12:49:36.870359765Z",
                    "fetched":"2016-06-09T12:49:35.812654441Z",
                    "meta":[  
                        "og:locale/en_us",
                        "og:site_name/lytics",
                        "og:title/understanding user intent through content",
                        "og:type/article",
                        "og:url/https://www.getlytics.com/blog/post/intent_through_content"
                    ],
                    "confidence":0.5916079783099615,
                    "visited":true
                }
            ]
        }
    }]
}

Configuration

Follow these steps to set up and configure the SendGrid triggered email workflow in the Lytics platform.

  1. Navigate to the Integrations page and select the SendGrid tile. SendGrid Tile
  2. Click New Workflow, and then click the Send Triggered Emails tab.
  3. Select the authorization you would like to use.
  4. In the Audience drop-down list, select a Lytics audience. These are the users who will receive the email.
  5. In the From Email Address field, enter the email address that you would like the email to appear to be sent from.
  6. In the Template drop-down list, select the template you would like to use. (This list is populated with the dynamic transactional templates that exist in your SendGrid account. If you don't see the template you wanted to use, double-check the Dynamic Transactional Templates section of your SendGrid account)
  7. Under Show Advanced Options, you have additional configuration options you may wish to set/change:

    1. From the Email Field drop-down list, select the Lytics user field in your account that contains the user's email address. By default, this will simply "Email Address", but if there is another field you'd like to use, you can change it here.
    2. In Name Field drop-down list, you can optionally select the Lytics user field that contains the email recipient's name (eg, "Full Name"). Again, this is optional.
    3. In Fields to Include, you can select additional Lytics user fields that you would like to send to SendGrid in order to personalize the email. (See the personalize the email section below.)

    sg send configure

Click Start Send to begin the workflow.

Personalizing the Email

In this integration, you can send Lytics user fields to SendGrid for use in personalizing the email. It's important to design and test your template carefully before setting up this workflow to ensure your emails will look the way you want them to.

SendGrid dynamic templates support Handlebars syntax for substitution (see SendGrid's docs about using Handlebars here), so you just need to make sure that your template has the right variable name for the Lytics user field that are being sent.

Let's say you want to personalize our email to show a known user's first name in the greeting line. There is a user field, called "First Name" (the slug for which is first_name). You can see the slug for the field in parentheses here in the "Fields To Include" section when we are setting up the workflow:

SG Configure Personalize Fields

In SendGrid, the template HTML should look something like this (such that the variable name matches the Lytics user field slug exactly):

<h1>Welcome, {{first_name}}!<h1>