Documentation / Product / Integrations / SendGrid

SendGrid: Export Audiences (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 job uses SendGrid's v3 Mail Send API to deliver emails with the template you select during configuration. Thus before you can set up this job, 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 job 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 job 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 job. 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 export in the Lytics platform. If you are new to creating jobs in Lytics, see the Jobs Dashboard documentation for more information.

  1. Select SendGrid from the list of providers.
  2. Select the Export Audiences (Triggered Emails) job type from the list.
  3. Select the Authorization you would like to use or create a new one.
  4. Enter a Label to identify this job you are creating in Lytics.
  5. (Optional) Enter a Description for further context on your job.
  6. In the Audience drop-down list, select a Lytics audience. These are the users who will receive the email.
  7. In the From Email Address field, enter the email address that you would like the email to appear to be sent from.
  8. 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)
  9. (Optional) Under Show Advanced Options, you have additional configuration options you may wish to set/change:
  10. (Optional) 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.
  11. (Optional) In Name Field drop-down list, you can optionally select the Lytics user field that contains the email recipient's name (eg, "Full Name").
  12. (Optional) 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.)
  13. Click Start Export.

    sg send configure

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 job 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 in the "Fields To Include" section when you are configuring the job.

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>