Documentation / Product / Integrations / SendGrid

SendGrid: Import Audiences

Importing user and activity data from SendGrid results in new users and/or existing user profiles supplemented with SendGrid campaign activity data. You can use this data to build and refine your existing Lytics audiences to power better, cross-channel campaigns.

Integration Details

  • Implementation Type: Server-side.
  • Implementation Technique: User import REST API, Activity Webhooks.
  • Frequency: User data is batch imported daily. Activity data, if configured, is received real-time.
  • Resulting data: Full user profiles for all SendGrid contacts or users in the selected lists. If configured, activity data related to marketing campaigns and transactional emails at the event level will be collected as additional user fields.

This integration utilizes the SendGrid APIs to receive user data. On each run of the job, it will:

  1. Export all contacts in your SendGrid account, or if you've configured import lists or segments, it will filter to only contacts in the selected lists and segments.
  2. For each contact imported it will:
    1. Get that contact's list membership.
    2. Ingest the collected user data into the sendgrid_users stream.

If the Import email events option is selected during the configuration process, on the first run of the job it will also:

  1. Check if webhooks are set up in the SendGrid account.
  2. Automatically apply the proper settings to your SendGrid account to enable activity data to be sent to Lytics.
  3. After this, user activity is received in Lytics via webhook, reformatted on ingestion, and available in the sendgrid_activity stream.


The following fields are included in the default mapping of the sendgrid_users stream:

Source FieldLytics User FieldDescriptionType
emailemail unique idEmailstring
idsendgrid_id unique idSendGrid User IDstring
emailemaildomainEmail Domainstring
first_namefirst_nameFirst Namestring
last_namelast_nameLast Namestring
last_clickedsg_last_clickedLast Clicked (SendGrid)date
last_emailedsg_last_emailedLast Emailed (SendGrid)date
last_openedsg_last_openedLast Opened (SendGrid)date
list_idssg_list_idsSendGrid List IDs[]string
list_namessg_list_namesSendGrid Lists[]string
segment_idssg_seg_idsSendGrid Segment IDs[]string

Lytics will import all custom fields from SendGrid, however this stream does not automatically map these fields. If you would like to map the imported custom fields to Lytics user fields, contact customer support for assistance.

The following fields are included in the default mapping of the sendgrid_activity stream:

Source FieldLytics User FieldDescriptionType
emailemail unique idEmailstring
n/achannelsthe channel this event was received from, set to email[]string
eventemail_bounce_ctEmail Bouncedint
categoryemail_categoryEmail Categoriesmap[string]intsum
eventemail_click_ctEmail Clickedint
eventemail_complaint_ctEmail Complaintint
timestampemail_first_bounce_tsFirst Email Bounceddate
timestampemail_first_complaint_tsFirst Email Complaintdate
timestampemail_first_sent_tsFirst Email Sentdate
timestampemail_firstclick_tsFirst Email Clickeddate
timestampemail_firstopen_tsFirst Email Openeddate
timestampemail_last_bounce_tsLast Email Bounceddate
timestampemail_last_complaint_tsLast Email Complaintdate
timestampemail_last_sent_tsLast Email Sentdate
timestampemail_lastclick_tsLast Email Clickeddate
timestampemail_lastopen_tsLast Email Openeddate
eventemail_open_ctEmail Openedint
eventemail_sent_ctEmail Sentint
urlemail_urlsEmail Urls Clicked on[]string
emailemaildomainEmail Domainstring
urlhashedurlsHashed Urls Visitedmap[string]intsum
timestamplast_active_tsLast Activedate
last_channel_activitiesLast Activity By Channelmap[string]time
bounce_typesg_bounce_typeSendGrid Bounce Type[]string
marketing_campaign_namesg_campaignsSendGrid Campaigns[]string
experience_idsg_conversionsConverted on SendGrid Experiencemap[string]int
eventsg_email_actionSendGrid Email Actionsmap[string]intsum
eventsg_email_opensSendGrid Email Opensint
experience_idsg_impressionsReached with SendGrid Experiencemap[string]int


Follow these steps to set up and configure an import of SendGrid in the Lytics platform. If you are new to creating jobs in Lytics, see the Jobs Dashboard documentation for more information.

  1. Select SendGrid from the list of providers.
  2. Select the Import Audiences job type from the list.
  3. Select the Authorization you would like to use or create a new one.
  4. Enter a Label to identify this job you are creating in Lytics.
  5. (Optional) Enter a Description for further context on your job.
  6. Select the Import Email Events checkbox, to allow email event data to be sent to Lytics via webhooks. This will only turn on webhooks if they are not already configured to another destination within your SendGrid account. You can also manually set up SendGrid webhooks to go to Lytics by following these instructions.
  7. From the Import Lists input, select the list(s) to import users from. If left blank, users will not be filtered by list.
  8. From the Import Segments input, select the segment(s) to import users from. If left blank, users will not be filtered by segment.
  9. Click Start Import. sendgrid-import-audiences-0521