SendGrid is a cloud-based email delivery service provided by Twilio Inc. It can deliver email newsletters and send emails via APIs.
Questetra’s Advanced Edition provides built-in auto-steps that are linked to SendGrid via API: [Twilio SendGrid: Add or Update Contact], [Twilio SendGrid: Add or Update Contact (Custom Fields)] and [Twilio SendGrid: Send Bulk Email] are provided as standard (as of 2023-10).
[Twilio SendGrid: Send Bulk Email] requests SendGrid to send an email using information such as the registered recipient list.
This article explains the settings for sending emails using [Twilio SendGrid: Send Bulk Email] in cooperation between SendGrid and Questetra.
- The services covered by Questetra’s auto-steps are those provided by Twilio Inc (sendgrid.com).
- In this article, we will proceed with an explanation from the perspective of linking Questetra BPM Suite with an organisation that is already using SendGrid for its email distribution operations (i.e. has already completed the construction of its SendGrid environment).
1. SendGrid Items and IDs
List
Side menu: Marketing > Contacts
This is the grouping unit for the email recipients ([Contacts]: email recipients registered for each email address). The default list is [All Contacts]. By adding optional [Lists] and associating individual [Contacts], you can create your own outgoing lists.
The URL of the individual [List] detail page contains the ID.
mc.sendgrid.com/contacts/lists/{List ID}
Segment
Side menu Marketing > Contacts
This is an outgoing list that [Contacts] contained in [All Contacts] or in individual [Lists] are filtered according to a set of conditions. The filtering criteria are based on the metadata attached to the individual [Contacts]. Metadata includes [Reserved Fields] (standard fields) and [Custom Fields] (fields that can be added arbitrarily).
The URL of the individual [Segment] detail page contains the ID.
mc.sendgrid.com/contacts/segments/{Segment ID}
Sender
Side menu Marketing > Senders
The sender’s information is registered as a [Sender] together with the “From” address, “Reply” address and location address. For example, if a company has several brands, a [Sender] may be registered for each brand.
If you open the edit screen of an individual [Sender], its URL contains the ID.
app.sendgrid.com/settings/sender_auth/senders/{Sender ID}/edit
Design
Side menu Design Library
The HTML email templates registered with SendGrid are called [Designs]. The [Design] may contain Handlebars tags into which metadata assigned to the Contact is inserted.
When you open the Preview screen of an individual [Design], the ID is included in its URL.
mc.sendgrid.com/design-library/your-designs/{Design ID}/preview
Handlebars is a template engine used primarily in JavaScript. At the position where Handlebars are written, the specified data values are inserted. For example, the name of the recipient can be displayed in each individual email sent, e.g. “Dear XX”.
SendGrid Document: How to insert a recipient’s First Name in your emails
Unsubscribe Groups
Side menu Suppressions > Unsubscribe Groups
Emails sent by SendGrid must include an unsubscribe link if the recipient does not wish to receive emails. When a recipient clicks on the unsubscribe link, they are added to the specified [Unsubscribe Group] and no further emails will be sent. If several Unsubscribe Groups are registered, emails with other (non-registered) Unsubscribe Groups will still be sent, even if the [Contact] is registered in one Unsubscribe Group.
The ID is shown as a number in the Group ID column of the [Unsubscribe Groups] list.
2. [Twilio SendGrid: Send Bulk Email] Settings
[Twilio SendGrid: Send Bulk Email] composes an HTTP request based on the SendGrid information (e.g. ID) specified in the auto-step when the workflow token arrives, and sends it to SendGrid’s API. SendGrid sends emails based on the received request and returns the assigned Send ID.The auto-step settings screen is divided into tabs for different purposes. Many settings items can be specified as [Fixed Value], [String-type data item] or [Select-type data item]. If set to [Fixed Value], the settings are specific to the workflow app. If set to [String-type/Select-type], different setting values can be specified for each Process. For items that multiple values can be specified, use the String-type (multiple lines) or Select-type (checkbox). For specifying multiple values in a String-type data item, enter one per line.
[API Key and Email Settings]
[C1: Authorization Setting in which API Key is set as token * ]
Select the HTTP authentication settings to be used in this step from the list. If no appropriate authentication settings have been registered, [add] a new HTTP authentication setting and register the API key issued by SendGrid in the [Token].
SendGrid document: Creating an API key
[C2: Sender ID *]
Register the ID obtained from the Sender in the [Fixed Value] input field. (If multiple Senders are registered, it is recommended to create a separate app for each Sender.)
[C3: Scheduled Datetime]
Select and specify the Datetime-type data item. If not specified, the data is sent immediately. If the specified value is in the past or blank, an error will occur when the auto-step is executed.
[Send To]
[C4-A: List IDs to send the emails to]
Specify the ID obtained from [List]. If multiple [Lists] are registered in SendGrid and you specify a [List] for each Process, you can set a [Select-type (checkbox)] (choice ID: List ID, display label: list name, etc.) so that the person in charge of operating will be able to input easier.
[C4-B: Segment IDs to send the emails to]
Specify the ID obtained from a [Segment]. If multiple [Segments] are registered and you specify a [Segment] for each process, setting [Select-type (check box)] will make input operations easier for the person in charge of processing.
If you specify the ‘Male’ and ‘Over 40’ segments as shown in the illustration above, the message will be sent to all ‘Male’ and all ‘Over 40’ destinations. If you want to send to males over 40, create a ‘Male over 40 Segment’ on the SendGrid side.
[C5: Unsubscribe Group ID *]
Register the ID obtained from [Unsubscribe Group] in the [Fixed Value] input field. If multiple [Unsubscribe Groups] are registered, multiple [Senders] are likely to be registered as well. Please pay attention to the combination with the corresponding [Sender].
[Email Content]
[C6-A: Design ID]
Specify the ID obtained from the [Design]. When multiple [Designs] are registered and a [Design] is specified for each Process, setting [Select-type (radio button)] will make input operations easier for the person in charge of processing.
[C6-B: Configure the subject and content without using Design]
Select [On] if you want to prepare the HTML in Questetra without using a [Design] template. When [On] is selected, the setting items in [C6-B1-3] below will be displayed. If you select [On], you must remove the specification in [C6-A: Design ID] by setting it to “Type: Fixed value/Input field: Blank”. If a [Design] ID is specified, an error occurs when the auto-step is executed.
[C6-B1: Subject *#{EL}]
Specifies the string that will be the subject of the email being sent.
[C6-B2: HTML Content *#{EL}]
Register the HTML that will be the body of the email; if you write an EL expression, you can insert data from Questetra’s workflow; if you write Handlebar tags for SendGrid, an email in which the data registered in SendGrid is inserted will be sent.
Reference: Let’s Send an Email Automatically in the Middle of a Workflow (HTML Email chapter)
[C6-B3: Plain Text Content]
Register the email body that will be displayed when an outgoing email is received by an email service that does not support HTML email. If not specified, it will be automatically generated from the body of the HTML email.
[Additional Settings]
[C7: Categories for filtering logs]
[Categories] are strings that serve as tags for managing outgoing emails in SendGrid. Input characters are limited to half-width alphanumeric characters (ASCII); if any other characters are specified, an error will occur during execution of the auto-step. Also, even if you specify nothing in this item, the [Categories] set in the SendGrid [Design] will not be applied and will be empty.[C8: Data item to save ID of the email sending ]
The ID assigned to the outgoing email by SendGrid is stored in a String-type data item.
[C9: Data item to save URL of the email sending status page]
The URL of the SendGrid outgoing email detail page is saved. You can open the SendGrid email detail page from the Process Detail page. (Login required)
3. Sending emails via [Twilio Sendgrid: Send Bulk Email
When the auto-step is executed, SendGrid will send emails based on your settings. Transmissions made by SendGrid are recorded in SendGrid as [Single Sends]. A [Single Send] made by a request from Questetra will be given the name [Questetra-{App ID}-{Process ID}] and the [Single Send] ID.
The individual [Single Send] pages show the send settings, such as the subject line of the outgoing email, the [List]/[Segment] to which it was sent, as well as statistics such as the total number of emails delivered, the number of emails opened and the number of links in the email that were clicked on.
