SendGrid is a popular customer communication platform for transactional and marketing emails.
This Adobe Experience Platform destination leverages the SendGrid Marketing Contacts API, which allows you to export your first-party email profiles and activate them within a new SendGrid audience for your business needs.
SendGrid uses API bearer tokens as an authentication mechanism to communicate with the SendGrid API.
The following items are required before you start configuring the destination.
Before activating data to the SendGrid destination, you must have a schema, a dataset, and segments created in Experience Platform. Refer also to the limits section further below on this page.
The SendGrid API used for creating the mailing list from email profiles requires unique email addresses to be provided within each profile. This is irrespective of whether it is used as a value for email or alternate email. Because the SendGrid connection supports mappings for both email and alternate email values, please ensure that all email addresses used should be unique within each profile of the Dataset. Otherwise, when the email profiles are sent to SendGrid, this will result in an error and that email profile will not be present in the data export.
Currently, there is no functionality in place to remove profiles from SendGrid when they are removed from audiences in Experience Platform.
SendGrid supports the activation of identities described in the table below. Learn more about identities.
Target Identity | Description | Considerations |
---|---|---|
Email address | Note both plain text and SHA256 hashed email addresses are supported by Adobe Experience Platform. If the Experience platform source field contains unhashed attributes, check the Apply transformation option, to have Platform automatically hash the data on activation. Note that SendGrid does not support hashed email addresses, so only plain text data without transformation is sent to the destination. |
Refer to the table below for information about the destination export type and frequency.
Item | Type | Notes |
---|---|---|
Export type | Profile-based | You are exporting all members of a segment, together with the desired schema fields (for example: email address, phone number, last name), as chosen in the select profile attributes screen of the destination activation workflow. |
Export frequency | Streaming | Streaming destinations are “always on” API-based connections. As soon as a profile is updated in Experience Platform based on audience evaluation, the connector sends the update downstream to the destination platform. Read more about streaming destinations. |
To help you better understand how and when you should use the SendGrid destination, here are sample use cases that Experience Platform customers can solve by using this destination.
Marketing teams using SendGrid can create a mailing list within SendGrid and populate it with email addresses. The mailing list now created within SendGrid can subsequently be used for multiple marketing activities.
To connect to the destination, you need the View Destinations and Manage Destinations access control permissions. Read the access control overview or contact your product administrator to obtain the required permissions.
To connect to this destination, follow the steps described in the destination configuration tutorial. In the configure destination workflow, fill in the fields listed in the two sections below.
Within the Adobe Experience Platform console, navigate to Destinations.
Select the Catalog tab and search for SendGrid. Then select Set up. After you have established a connection to the destination, the UI label changes to Activate Segments.
You are shown a wizard which assists you in configuring the SendGrid destination. Create the new destination by selecting Configure new destination.
Select the New Account option and fill in the Bearer Token value. This value is the SendGrid API Key previously mentioned in the prerequisites section.
Select Connect to destination. If the SendGrid API Key you provided is valid, the UI displays a Connected status with a green check mark, you can then proceed to the next step to fill in additional information fields.
While setting up this destination, you must provide the following information:
You can enable alerts to receive notifications on the status of the dataflow to your destination. Select an alert from the list to subscribe to receive notifications on the status of your dataflow. For more information on alerts, see the guide on subscribing to destinations alerts using the UI.
When you are finished providing details for your destination connection, select Next.
Read Activate profiles and audiences to streaming audience export destinations for instructions on activating audiences to this destination.
Refer to the below images for details specific to this destination.
Select one or more audiences to export to SendGrid.
In the Mapping step, after selecting Add new mapping, you are shown the mapping page to map the source XDM fields to the SendGrid API target fields. The images below demonstrate how to map identity namespaces between Experience Platform and SendGrid. Please ensure the Source field Email should be mapped to the Target field external_id as shown below.
Similarly, map the desired Adobe Experience Platform attributes that you want to export to the SendGrid destination.
After completing the mappings, select Next to advance to the review screen.
Select Finish to complete the setup.
The comprehensive list of supported attribute mappings that can be set up for the SendGrid Marketing Contacts > Add or Update Contact API is below.
Source Field | Target Field | Type | Description | Limits |
---|---|---|---|---|
xdm: homeAddress.street1 |
xdm: address_line_1 |
String | The first line of the address. | Max Length: 100 characters |
xdm: homeAddress.street2 |
xdm: address_line_2 |
String | An optional second line for the address. | Max Length: 100 characters |
xdm: _extconndev.alternate_emails |
xdm: alternate_emails |
Array of String | Additional emails associated with the contact. |
|
xdm: homeAddress.city |
xdm: city |
String | The contact’s city. | Max Length: 60 characters |
xdm: homeAddress.country |
xdm: country |
String | The contact’s country. Can be a full name or an abbreviation. | Max Length: 50 characters |
identityMap: |
Identity: external_id |
String | The contact’s primary email. This is required to be a valid email. | Max Length: 254 characters |
xdm: person.name.firstName |
xdm: first_name |
String | The contact’s name | Max Length: 50 characters |
xdm: person.name.lastName |
xdm: last_name |
String | The contact’s family name | Max Length: 50 characters |
xdm: homeAddress.postalCode |
xdm: postal_code |
String | The contact’s ZIP code or other postal code. | |
xdm: homeAddress.stateProvince |
xdm: state_province_region |
String | The contact’s state, province, or region. | Max Length: 50 characters |
To validate that you have correctly set up the destination, follow the steps below:
Select Destinations > Browse to navigate to the list of destinations.
Select the destination and validate that the status is enabled.
Switch to the Activation data tab, then select an audience name.
Monitor the audience summary and check the count of profiles corresponds to the count created within the dataset.
The SendGrid Marketing Lists > Create List API is used to create unique contact lists within SendGrid by joining the value of the list_name attribute and the timestamp of the data export. Navigate to the SendGrid site and check if the new contact list conforming to the name pattern is created.
Select the newly created contact list and check if the new email record from the dataset you created is being populated within the new contact list.
Additionally, also check a couple of emails to validate if the field mapping is correct.
All Adobe Experience Platform destinations are compliant with data usage policies when handling your data. For detailed information on how Adobe Experience Platform enforces data governance, see the Data Governance overview.
This SendGrid destination leverages the below APIs: