SendGrid
Step-by-step guide to send your event data from RudderStack to SendGrid.
Last updated
Was this helpful?
Step-by-step guide to send your event data from RudderStack to SendGrid.
Last updated
Was this helpful?
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.
Before configuring SendGrid as a destination in RudderStack, verify if the source platform is supported by SendGrid by referring to the table below:
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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
.
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:
asm
It is mandatory to have the groupId
field inside the asm
object.
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.
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.