SendGrid

Step-by-step guide to send your event data from RudderStack to SendGrid.

SendGrid is a cloud-based email marketing platform built for marketers and developers. It helps businesses deliver billions of transactional and marketing emails every month.

RudderStack supports SendGrid as a destination to which you can seamlessly send your customer data.

Getting started

Before configuring SendGrid as a destination in RudderStack, verify if the source platform is supported by SendGrid by referring to the table below:

Connection Mode	Web	Mobile	Server
Device mode	-	-	-
Cloud mode	Supported	Supported	Supported

To know more about the difference between cloud mode and device mode in RudderStack, refer to the RudderStack Connection Modes guide.

Once you have confirmed that your source platform supports sending events to SendGrid, follow these steps:

• From your RudderStack dashboard, add the source. From the list of destinations, select SendGrid.

• Assign a name to the destination and click on Next. You should then see the following screen:

Connection settings

The connection settings required to configure SendGrid as a destination in RudderStack are listed below:

• Enter your SendGrid API Key.

To get the SendGrid API Key, click here.

• Enter the Subject.

You can also send the Email subject via the subject field in the track properties. For more information, refer to the Track section below.

• Next, enter the Template ID.

To get your template ID or create a new one, go to your SendGrid dashboard. Then, click on Email API and go to Dynamic Templates.

You can also set the Template ID via the templateId field in the track properties. Note that the template ID passed in the track properties will override the Template ID field specified in the RudderStack dashboard.

• Next, you can enable or disable the Get email ID by traits option. If enabled, RudderStack searches for the user's email inside the user's traits. If it is found, then the event can be sent to SendGrid without any track call properties.

This option is only useful when the properties in the track are empty. SendGrid also requires either the templateId or content to be present for a successful event delivery.

• Enter the email address in the Reply-To Email option, where the email ID replies or bounces will be returned.

• In Reply-To Name , enter the user's name associated with the above email address.

You can also send the email ID and name inside replyTo in the track properties. Note that these fields will override the Reply-To Email and Reply-To Name fields set in the RudderStack dashboard.

For more information on how to send these details via the replyTo object, refer to the refer to the replyTo section below.

• Next, enter the IP Pool Name.

The length of the IP Pool Name must be between 2 and 64 characters. For detailed steps on creating the IP pool name, refer to the SendGrid documentation.

From

• Enter the user's Email address through which the email will be sent.

For more information on creating a verified sender identity, refer to this SendGrid documentation.

• Enter the Name associated with above email ID.

You can also include email and name inside the from object in the track call (shown below). Note that this will override the Email and Name fields specified in the RudderStack dashboard.

from:{
    "email": "[e-mail]",
    "name": "test"
}

Event names

• Next, create the list of events for which the track calls will be made.

Any track call made with an event name that is not specified in this list will be discarded.

Content

• To specify the content of your email, enter the type and value.

  • The type field is the value type to be included in the value field.

  • The value field contains the actual value that is to be included in the email.

The content array can also be sent via track properties (shown below), which will override the dashboard settings.

content: [
    {
        "type": "text/plain",
        "value": "sample text"
    }
]

Attachments

Use the Attachments settings to specify any attachments you want to include in your email. The individual settings are as follows:

• content: This should be a Base64-encoded string.

• type: The attachment type contains the type of content you are attaching e.g. "text/plain", "text/html", etc.

• filename: Use this setting to specify the attachment's file name.

• disposition: This option specifies how you would like the attachment to be displayed.

• content ID: Use this option when disposition is set to inline and the attachment is an image.

SendGrid requires that each attachment element must contain content and filename. The attachments can also be sent via the track call (shown below), which will override the dashboard settings.

attachments:[
    {
        "content": "base64encodedString",
        "filename": "index.html",
        "type": "text/html",
        "disposition": "attachment"
    }
]

ASM

The ASM settings allow you to handle the user's unsubscribing activity. The configurable options are:

• Group ID: This option specifies the unsubscribe group to associate with this email.

• Groups: This option contains the array of unsubscribing groups that would be displayed in the unsusbcribing preferences page.

SendGrid requires that the Group ID should always be present if the asm object is to be sent.

Email settings

• To include a default footer in every mail, enable the Footer option. When enabled, the text option contains the plain content of footer. The HTML contains the HTML content of footer.

The footer can also be sent via track properties (shown below), which will override the dashboard settings.

mailSettings:{
    "footer": true,
    "footerText": "plain text",
    "footerHtml": "html content"
}

• To send a test mail and ensure everything is correct, you can enable the Sandbox Mode setting.

The sandbox mode can also be enabled or disabled via the track properties (shown below), which will override the dashboard setting.

mailSettings:{
    "sandboxMode": true
}

Tracking settings

The following table describes the various tracking settings to be configured in the RudderStack dashboard:

Setting	Description
Click Tracking	Allows you to track if a recipient clicked a link in your email.
Click Tracking enable text	Indicates if this setting should be included in the text/plain portion of your email.
Open Tracking	Allows you to track if the email was opened by including a single pixel image in the body of the content.
Substitution Tag	When Open Tracking is enabled, this setting allows you to specify a substitution tag that you can insert in the email body at a specific location.
Subscription Tracking	Allows you to insert a subscription management link at the bottom of your email's text and HTML bodies.
Text	When Subscription Tracking is enabled, this setting refers to the string to be appended to the email with the subscription tracking link.
HTML	When Subscription Tracking is enabled, this is appended to the email with the subscription tracking link.
Substitution Tag	Refers to the tag that will be replaced with the unsubscribe URL.
GAnalytics	Allows you to enable Google Analytics tracking.
utm source	Refers to the name of the referrer source, e.g. Google.
utm medium	Refers to the name of the marketing medium, e.g. Email.
utm term	This setting is used to identify any paid keywords.
utm content	Allows you to differentiate your campaign from advertisements.
utm campaign	Corresponds to the name of the campaign.

The utm source, utm medium, utm term, utm content, utm campaign options are associated with the GAnalytics setting on the dashboard.

Finally, click on Next to complete the setup. SendGrid will now be enabled as a destination in RudderStack.

Track

The track call lets you send an event to SendGrid along with its properties. Note that the properties specified in the track call will override the settings specified in the RudderStack dashboard.

Note that SendGrid requires either the templateId or content to be present in the body. Otherwise, the event will be discarded.

A sample track call is shown below:

rudderanalytics.track('testing',
      {
          "personalizations": [
          {
            "to": [
              {
                "email": "[e-mail]",
                "name": "Name"
              }
            ],
            "cc": [
                {
                    "email": "[e-mail]",
                    "name": "CCUser"
                },
                {
                    "email": "[e-mail]",
                    "name": "CCUser2"
                }
            ],
            "subject": "subject"
          }
        ],
        "from": {
            "email": "[e-mail]",
            "name": "Name here"
        },
        "attachments":[
            {
                "content": "base64encodedString",
                "filename": "index.html",
                "type": "text/html",
                "disposition": "attachment"
            }
        ],
        "content":[
            {
                "type": "text/html",
                "value": "<p>Hello</p>"
            }
        ],
        "templateId": "value",
        "headers":{
            "key": "value"
        },
        "customArgs":{
            "key": "value"
        },
        "categories": ["sample","values","here"],
        "sendAt": 1617260400,
        "batchId": "some valid batch ID",
        "subject": "Subject Value",
        "mailSettings":{
          "bypassBounceManagement": true,
          "bypassSpamManagement": true,
          "bypassUnsubscribeManagement": true,
          "footer": true,
          "footerText": "text",
          "footerHtml": "html",
          "sandboxMode": true
        },
        "replyTo":{
          "email": "[e-mail]",
          "name": "Name"
        },
        "replyToList":[
            {
                "email": "[e-mail]",
                "name": "Test"
            }
        ],
        "field1": "value"
  });

The following sections highlight some important things to keep in mind while using the track call to send customer data to SendGrid.

categories

SendGrid allows the categories array to have a maximum of 10 values.

customArgs

If customArgs is not provided in the track call, the non-default fields are taken as custom fields. In the sample track call above, field1 will be mapped inside customArgs.

Email settings

To send the event to SendGrid successfully, the following points must be kept in mind:

• In the mailSettings, you cannot combine bypassListManagement with bypassBounceManagement, bypassSpamManagement, and bypassUnsubscribeManagement.

• If bypassListManagement is present, then neither bypassSpamManagement, bypassBounceManagement, or bypassUnsubscribeManagement can be present.

personalizations

SendGrid requires that the personalizations array should be present in every event and each object must contain the field to.

• If the Get email ID from traits option is enabled in the RudderStack dashboard and the properties are not sent in track call, RudderStack will look for email in the event traits. If found, RudderStack will create a personalizations object and assign email to the to field.

• In case both Template ID and content are not assigned in the dashboard settings, the event will not be sent as either of templateId or content is required.

replyTo

Note that SendGrid does not allow only name to be sent in the replyTo object. email must be present too, otherwise the replyTo object will be ignored.

A sample replyTo object is as shown:

replyTo:{
    "email": "[e-mail]",
    "name": "test"
}

asm

It is mandatory to have the groupId field inside the asm object.

Event name

As mentioned in the Connection settings section above, the event names for which a track call is made must be specified in the RudderStack dashboard. In the sample track call above, testing is the event name that should be configured in the RudderStack dashboard. Otherwise, this event will be discarded.

content

Each object inside content array must contain the type and value fields. If these fields are absent, then the object will be dropped. However, note that the event will not be discarded.

attachments

Each object inside attachments array must at least contain the content and filename fields. If these fields are absent, then the object will be dropped. However the event will not be discarded.

Contact us

If you come across any issues while configuring or using SendGrid with RudderStack, you can contact us or start a conversation in our Slack community.