SendGrid

The SendGrid task sends pre-rendered email content, created by the Render Email Content plugin, to SendGrid, an Email Service Provider (ESP), for bulk processing. This task uses SendGrid's v3 Web API which is faster than sending email over SMTP (like the Create Email Content task does).

Note:

The SendGrid plugin is not installed by default. It is available for download on the . Make sure that the plugin version you download is compatible with your Workflow version. The latest plugin version: 1.13.0, provided in the 2022.2 download package, is backwards compatible with Workflow down to version 2020.1.
In order to use HTTPS it is essential to use the latest version of the plugin, available for download on the . It provides HTTPS support for Connect 2021.1 and above.
To be able to send email using the SendGrid plugin, you need a SendGrid account and API key.

The SendGrid plugin's settings allow you to:

Tag the emails with category names, which help organize your email analytics (see About categories).
Set a time at which the emails should be sent (see Scheduling parameters).
Add custom headers specifying specific handling instructions for your email. (To get an idea of what these could be used for, see SendGrid's blog post about email headers.)

In addition, you may specify the unsubscribe group to associate with the email, along with an optional array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page. This requires adding a custom header, not in the plugin's properties, but in the template, via a Control Script. How to add custom headers via a Control Script is explained with an example in the Designer help. The header's name should be asm and its value a JSON string with the unsubscribe group (group_id, required) and the groups to display (groups_to_display, optional, max. 25); for example: "group_id":12345,"groups_to_display":[12345,23456,34567]" (see also: SendGrid's documentation).
Note that any other custom headers will not be processed. Only the asm header will be used.

In a basic email Workflow process, this task will be preceded by the Render Email Content plugin and will be followed by a Delete task to terminate the process.

Input

This task must receive either Metadata or JSON Job Data containing information regarding pre-rendered email messages. The Render Email Content task outputs information about the email messages that it pre-rendered either in the current Metadata or in the form of a JSON structure.

Extra attachments

To add attachments, in addition to those specified in the original email template, you should modify the input of the task, which is the Metadata or JSON Job Data file outputted by the Render Email Content task.

To specify an extra attachment, you have to use the key/value pair "disposition":"attachment".

To let the plugin know where it can find the attachment, you can either provide a full path ("url"), for example:
[{"url":"file:///C:/Terms-and-Conditions.pdf","disposition":"attachment"}]
or
[{"url":"http://www.example.com/image.png","disposition":"attachment"}]
or a Connect File Store ID ("fileid"), for example:
[{"fileid":100034, "disposition":"attachment"}]

Optionally, you may provide a name ("name") to override the name that the plugin creates for an extra attachment.
Examples:
[{"fileid":100034,"name":"example.pdf","disposition":"attachment"}]
[{"url":"file:///C:/Terms-and-Conditions.pdf","name":"terms.pdf","disposition":"attachment"}]

All attachments should be combined in one array:
[{"url":"file:///C:/Terms-and-Conditions.pdf","disposition":"attachment","name":"Terms.pdf"},{"name":"Take action Mandie.pdf","disposition":"attachment"}]

The order of the key/value pairs is not important.

Note: Any attachments added via Workflow cannot be added to the EML file which is produced by the Render Email Content task.

Processing

The plugin communicates with the Connect Server to retrieve each email message's body, any attachments and the plain text version (if available) from the File Store, using the folder ID and file names specified in the output of the Render Email Content task.
It then transforms the files into email messages as specified by SendGrid and sends the emails via the SendGrid v3 Web API.

Output

This task does not make any changes to the Metadata or the Job File.

Properties

General Tab

SendGrid API:
- API Key: Enter your API key, retrieved from SendGrid. It will be used for authentication with the SendGrid v3 Web API. A valid key is required to send email messages.
- Data Source (see Input):
  - Metadata: Metadata containing information about email messages. The Render Email Content task can output information about the email message(s) that it pre-rendered in the current Metadata.
  - JSON: A JSON Job File containing information about email messages. The Render Email Content task can output a JSON object or an array of JSON objects containing information about email messages. For an example of the JSON structure see the Render Email Content task.
- Categories (optional): Enter a single category name (e.g. invoice) or an array of category names (e.g. ["invoice","brand1"]) for the messages. The maximum length of each category name is 255 characters. You can specify up to 10 categories per request. See About categories.
- Send At (optional): Enter a UNIX timestamp specifying when you want your email to be sent from SendGrid. This can be left empty if you want the email to be sent at the time of your API request.
- Headers (optional): A JSON object containing key/value pairs of header names and the value to substitute for them. Example: {"x-my-header":"my-value"}.
  If they contain Unicode characters, you must ensure that these are properly encoded.
  Custom header names normally start with "x-".
  The following headers are reserved and cannot be used as custom header: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC.
Debug settings:
- Send all messages to the Test Address: When this option is checked, SendGrid will only send the emails to the given Test Address. This allows you to review the result and to test ESP specific options like open rates and click through statistics.
- Log email messages: Check this option to get a copy of each message in the Messages window of Workflow. You can use this to verify that the messages match the format required by the ESP.

Note: Information about the Connect Server (host, user name etc.) is taken from the Workflow Preferences (see OL Connect preferences).

Advanced properties

To get access to the following properties tabs, right-click the plugin in the process and select Advanced Properties.

On Error Tab

For a description of the options on the On Error tab see Using the On Error tab.

Miscellaneous Tab

The Miscellaneous tab is common to all tasks.

It contains a text area (Task comments) that lets you write comments about the task. These comments are saved when the dialog is closed with the OK button and are displayed in The Task Comments Pane.

Check the option Use as step description to display the text next to the icon of the plugin in the Process area.

The tab also provides an option to highlight the task in The Process area with the default color, set in the Preferences (see Colors), or the color selected or defined under Highlight color on this tab.
To revert the selected highlight color to the default color, open this tab, turn the Highlight option off and close the dialog with the OK button; then turn highlighting back on.
Highlighting can also be turned on and off via the task's contextual menu and with the Highlight button on the View ribbon.