Release Status Released Supported By Stitch
Availability Free Status Page SendGrid Core Status Page
Default Historical Sync 1 year Default Replication Frequency 30 minutes
Whitelisting Tables and columns Destination Incompatibilities None

Connecting SendGrid Core

SendGrid Core Setup requirements

To set up SendGrid Core in Stitch, you need:

  • Access to the objects you want to replicate from SendGrid. This is required to grant the required permissions to the API key Stitch uses to connect to your SendGrid account.

    For example: If you want to replicate campaign data, you need to be able to access campaigns in your SendGrid account.

Step 1: Create a SendGrid general API key for Stitch

Note: You can’t assign an API key greater permissions than you currently have in SendGrid.

  1. Sign into your SendGrid account.
  2. On the dashboard page, click Settings > API Keys.
  3. Click Create API Key.
  4. In the API Key Name field, enter a name for the key. For example: Stitch API key
  5. In the API Key Permissions section, select Restricted Access.
  6. In the Access Details section, enable the following:
    • Email Activity - Read Access
    • Marketing Campaigns - Full Access (Note: SendGrid doesn’t currently provide a read-only level for this object.)
    • Suppressions - Read Access
    • Template Engine - Read Access
    • Tracking - Read Access
  7. Click Create & View.
  8. The API key will display. Copy the key before closing the page, as SendGrid won’t display it again.

Step 2: Add SendGrid Core as a Stitch data source

  1. Sign into your Stitch account.
  2. On the Stitch Dashboard page, click the Add Integration button.

  3. Click the SendGrid Core icon.

  4. Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.

    For example, the name “Stitch SendGrid Core” would create a schema called stitch_sendgrid_core in the destination. Note: Schema names cannot be changed after you save the integration.

  5. In the SendGrid API Key field, paste your SendGrid API key.

Step 3: Define the Historical Sync

The Sync Historical Data setting will define the starting date for your SendGrid Core integration. This means that:

  • For tables using Incremental Replication, data equal to or newer than this date will be replicated to your data warehouse.
  • For tables using Full Table Replication, all data - including records that are older, equal to, or newer than this date - will be replicated to your data warehouse.

Change this setting if you want to replicate data beyond SendGrid Core’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.

Step 4: Create a replication schedule

In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.

Stitch offers two methods of creating a replication schedule:

  • Replication Frequency: This method requires selecting the interval you want replication to run for the integration. Start times of replication jobs are based on the start time and duration of the previous job. Refer to the Replication Frequency documentation for more information and examples.
  • Anchor scheduling: Based on the Replication Frequency, or interval, you select, this method “anchors” the start times of this integration’s replication jobs to a time you select to create a predictable schedule. Anchor scheduling is a combination of the Anchor Time and Replication Frequency settings, which must both be defined to use this method. Additionally, note that:

    • A Replication Frequency of at least one hour is required to use anchor scheduling.
    • An initial replication job may not begin immediately after saving the integration, depending on the selected Replication Frequency and Anchor Time. Refer to the Anchor Scheduling documentation for more information.

To help prevent overages, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.

Initial and historical replication jobs

After you finish setting up SendGrid Core, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.

Free historical data loads

The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.


SendGrid Core Table Schemas

Replication Method: Key-based Incremental Replication Key : end_time
Primary Key : email API Endpoint: List all blocks

The blocks table contains info about the email addresses currently on your blocks list. There are several causes for blocked emails: A mail server IP address being on an ISP blacklist, blocked by an ISP, or if the receiving server flags the message content.

email
STRING

The email address of the blocked email entry.

created
INTEGER

The Unix timestamp indicating when the email address was added to the blocks list.

reason
STRING

An explanation for the reason of the block.

status
STRING

The status of the block.


Replication Method: Key-based Incremental Replication Key : end_time
Primary Key : email API Endpoint: List all bounces

The bounces table contains info about bounced emails. A bounced email is when the message is undeliverable and returned to the server that sent it.

email
STRING

The email address that bounced.

created
INTEGER

The Unix timestamp of the time the bounce occurred.

reason
STRING

An explanation for the reason the email bounced.

status
STRING

The status of the bounce.


Replication Method: Key-based Incremental Replication Key : timestamp
Primary Key : id API Endpoint: List all campaigns

The campaigns table contains info about all your campaigns.

id
INTEGER

The campaign ID.

title
STRING

The display title of the campaign in the SendGrid Marketing Campaigns UI.

subject
STRING

The subject of the campaign that recipients will see.

sender_id
INTEGER

The ID of the ‘sender’ identity. Recipients will see this as the “From” on your marketing emails.

list_ids

The IDs of the lists the campaign is being sent to.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named campaigns__list_ids and may contain the following attributes:

_sdc_source_key_id
INTEGER

The campaign ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
INTEGER

The list ID.

segment_ids

The segment IDs the campaign is being sent to.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named campaigns__segment_ids and may contain the following attributes:

_sdc_source_key_id
INTEGER

The campaign ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
INTEGER

The segment ID.

categories

The categories associated with the campaigns.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named campaigns__categories and may contain the following attributes:

_sdc_source_key_id
INTEGER

The campaign ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The name of the category.

suppression_group_id
INTEGER

The ID of the suppression group that the marketing email belongs to, allowing recipients to opt-out of emails of this type.

Reference: groups_all.id
custom_unsubscribe_url
STRING

The URL of the custom unsubscribe page provided for customers to unsubscribe from suppression groups.

ip_pool
STRING

The pool of IPs that the email should be sent from.

html_content
STRING

The HTML content of the marketing email.

plain_content
STRING

The plain text content of the marketing email.

status
STRING

The status of the campaign. For example: Draft


Replication Method: Key-based Incremental Replication Key : timestamp
Primary Key : id API Endpoint: List recipients

The contacts table contains info about the contacts in your SendGrid account.

Contact custom fields

Stitch’s SendGrid Core integration will replicate any custom fields associated with contact records.

id
STRING

The contact ID.

created_at
INTEGER

The Unix timestamp of the time the contact was created.

updated_at
INTEGER

The Unix timestamp of the last time the contact was updated.

email
STRING

The email address associated with the contact.

last_emailed
INTEGER

The Unix timestamp of the last time the contact was emailed.

last_clicked
INTEGER

The Unix timestamp of the last time the contact clicked on an email.

last_opened
INTEGER

The Unix timestamp of the last time the contact opened an email.

first_name
STRING

The first name of the contact.

last_name
STRING

The last name of the contact.

custom_fields

The custom fields associated with the contact.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named contacts__custom_fields and may contain the following attributes:

_sdc_source_key_id
STRING

The contact ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

[field_name]
VARIES

The custom field associated with the contact, where [field_name] is the name of the field in SendGrid.

The data type of this field will vary and depends on the type in SendGrid. For example: If this is a text field in SendGrid the field will be a STRING.


global_suppressions

Replication Method: Key-based Incremental Replication Key : end_time
Primary Key : email API Endpoint: List all globally unsubscribed email addresses

The global_suppressions table contains info about global suppressions, or global unsubscribes. Recipients who are globally suppressed will be removed from any email you send.

email
STRING

The email address of the recipient who is globally suppressesd.

created
INTEGER

The Unix timestamp of the time the recipient was added to the global suppression list.


Replication Method: Full Table API Endpoint: List all suppression groups
Primary Key : id

The groups_all table contains info about the groups in your SendGrid account. Groups are specific types of email you want your recipients to be able to unsubscribe from or subscribe to. For example: Newsletters, Invoices, Alerts, etc.

id
INTEGER

The ID of the suppression group.

name
STRING

The name of the suppression group.

description
STRING

A description of the suppression group.

last_email_sent_at
INTEGER

The Unix timestamp of when the suppression group was last emailed.

is_default
BOOLEAN

If true, the suppression group is the default suppression group.

unsubscribes
INTEGER

The number of unsubscribes associated with the group.


Replication Method: Full Table API Endpoint: List all suppressions
Primary Key : email

The group_members table contains a list of email and group_id pairs, allowing you to identify recipients and the groups they are members of.

email
STRING

The email address of the recipient.

group_id
INTEGER

The ID of the group the recipient is a member of.

Reference: groups_all.id

Replication Method: Key-based Incremental Replication Key : end_time
Primary Key : email API Endpoint: List all invalid emails

The invalids table contains info about invalid email addresses. An invalid email occurs when you attempt to send an email to an address that is formatted in a manner that doesn’t meet internet email format standards, or the email doesn’t exist at the recipient’s email server.

For example: Email addresses that don’t include the @ symbol.

email
STRING

The email address marked as invalid.

created
INTEGER

The Unix timestamp of when the email address was added to the invalid emails list.

reason
STRING

The reason the email address was marked as invalid. For example: Mail domain mentioned in email address is unknown


Replication Method: Full Table API Endpoint: List all lists
Primary Key : id

The lists_all table contains info about your recipient lists.

id
INTEGER

The list ID.

name
STRING

The name of the list.

recipient_count
INTEGER

The current number of recipients currently in the list.


Replication Method: Full Table API Endpoint: List all list recipients
Primary Key : id

The lists_members table contains info about members of your lists.

List member custom fields

Stitch’s SendGrid Core integration will replicate any custom fields associated with list member records.

id
STRING

The ID of the list member.

created_at
INTEGER

The Unix timestamp of the time the list member was added to the list.

updated_at
INTEGER

The Unix timestamp of the last time the list member was updated.

email
STRING

The email address of the list member.

list_id
INTEGER

The ID of the list the member belongs to.

Reference: lists_all.id
last_emailed
INTEGER

The Unix timestamp of the last time the list member was emailed by one of your campaigns.

last_clicked
INTEGER

The Unix timestamp of the last time the list member clicked a link from one of your campaigns.

last_opened
INTEGER

The Unix timestamp of the last time the list member last opened an email from one of your campaigns.

first_name
STRING

The first name of the list member.

last_name
STRING

The last name of the list member.

custom_fields

The custom fields associated with the list member.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named lists_members__custom_fields and may contain the following attributes:

_sdc_source_key_id
STRING

The ID of the list member.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

[field_name]
VARIES

The custom field associated with the list member, where [field_name] is the name of the field in SendGrid.

The data type of this field will vary and depends on the type in SendGrid. For example: If this is a text field in SendGrid the field will be a STRING.


Replication Method: Full Table API Endpoint: List all segments
Primary Key : id

The segments_all table contains info about the segments in your SendGrid account, and the conditions required for recipients to be added to the segment.

For example: A segment for recipients with email addresses that contain @stitchdata.com

id
INTEGER

The segment ID.

name
STRING

The name of the segment.

recipient_count
INTEGER

The current number of recipients in the segment.

conditions

Details about the conditions a recipient must meet to be included in the segment.

For example: To be included on a segment for Stitch, email addresses must contain @stitchdata.com. The condition could be:

  • field: email
  • operator: contains
  • value: @stitchdata.com

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named segments_all__conditions and may contain the following attributes:

_sdc_source_key_id
INTEGER

The segment ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

field
STRING

The name of the field used in the condition. For example: email

value
STRING

The value associated with the field in field. For example: @stitchdata.com

operator
STRING

The operator used in the condition. Possible values are:

  • eq (Equal to)
  • ne (Not equal to)
  • lt (Less than)
  • gt (Greater than)
  • contains
and_or
STRING

If applicable, the and or or operation associated with the condition.


Replication Method: Full Table API Endpoint: List recipients on a segment
Primary Key : id

The segments_members table contains info about the members of your segments.

Segment member custom fields

Stitch’s SendGrid Core integration will replicate any custom fields associated with segment member records.

id
STRING

The ID of the segment member.

created_at
INTEGER

The Unix timestamp of the time the segment member was added to the segment.

updated_at
INTEGER

The Unix timestamp of the last time the segment member was updated.

email
STRING

The email address of the segment member.

segment_id
INTEGER

The ID of the segment the member belongs to.

Reference: segments_all.id
last_emailed
INTEGER

The Unix timestamp of the last time the segment member was emailed by one of your campaigns.

last_clicked
INTEGER

The Unix timestamp of the last time the segment member clicked a link from one of your campaigns.

last_opened
INTEGER

The Unix timestamp of the last time the segment member last opened an email from one of your campaigns.

first_name
STRING

The first name of the segment member.

last_name
STRING

The last name of the segment member.

custom_fields

The custom fields associated with the segment member.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named segments_members__custom_fields and may contain the following attributes:

_sdc_source_key_id
STRING

The ID of the segment member.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

[field_name]
VARIES

The custom field associated with the segment member, where [field_name] is the name of the field in SendGrid.

The data type of this field will vary and depends on the type in SendGrid. For example: If this is a text field in SendGrid the field will be a STRING.


Replication Method: Key-based Incremental Replication Key : end_time
Primary Key : email API Endpoint: List all spam reports

The spam_reports table contains info about spam reports made against your messages. Spam reports occur when a recipient indicates they think your message is spam, which their email provider then reports to SendGrid.

email
STRING

The email address of the recipient who marked the message as spam.

created
INTEGER

The Unix timestamp of the time the spam report was made.

status
STRING

The status of the spam report.


Replication Method: Full Table API Endpoint: List all templates
Primary Key : id

The templates_all table contains info about the transactional templates in your SendGrid account. Transactional templates are templates specifically created for transactional email and are different than Marketing Campaign templates.

id
STRING

The template ID.

name
STRING

The name of the template.

versions

Details about each version of the template, if the template is versioned.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named templates_all__versions and may contain the following attributes:

_sdc_source_key_id
STRING

The template ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

template_id
STRING

The ID of the original template.

active
INTEGER

Indicates if the template version is the active version associated with the template.

name
STRING

The name of the template version.

html_content
STRING

The HTML content of the template version.

plain_content
STRING

The plain text content of the template version.

subject
STRING

The subject of the template version.

editor
STRING

The editor used in the SendGrid UI. Possible values are code or design.



Questions? Feedback?

Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.