By using SendGrid Source with your SendGrid data in your data warehouse, you’ll be able to analyze your email activity (opens, clicks, deliveries, and bounces), lists, and recipients via SQL. Additionally, you can join your SendGrid data with Segment event and other source data you’re already sending to your warehouse, so you can correlate product feature usage with email activity, or tie referral sources into your customer journey analysis.
This documentation is managed by Segment. If you have any questions please contact Segment’s support team at firstname.lastname@example.org.
- Create a Segment account
- Add SendGrid in the “Cloud Apps” Category and enter your credentials
- Setup a warehouse by bringing your own or having Segment setup and host
- Give the Source a nickname and schema name. We recommend sticking to something that reflects the source itself, like
SendGridfor nickname and
sendgrid_prodfor the schema name.
- You’ll soon see SendGrid data in your data warehouse
Note that you can add multiple instances if you have multiple SendGrid accounts. That’s why we allow you to customize the source’s nickname and schema name!
In order to pull information about your contacts, we’ll make requests to SendGrid’s API with our sync component. So the first step in setting up the integration is to retrieve your API Keys and drop them into the Segment interface. You can create an API Key by navigating to Settings > API Keys, clicking General API Key.
We recommend providing read permissions for Email Activity and Marketing Activity.
Finally, copy the resulting API Key into the Segment interface, taking care to trim any errant trailing spaces from copying and pasting, and press connect.
In the next step, copy the auto-generated Webhook URL and paste it into SendGrid’s Event Notification settings pane under Settings > Mail Settings.
Once you enable the Event Notification, you’re good to go! Press Next, and then Finish to wrap up the setup flow.
SendGrid has a single Event URL location. By using the SendGrid source, you will be using your only Event URL location. If you remove a pre-existing URL, then that location will no longer receive events.
SendGrid has a sync component, which means we’ll make requests to their API on your behalf on a 3 hour interval to pull the latest data into Segment. In the initial sync, we’ll grab all the SendGrid objects (and their corresponding properties) according to the Collections Table below. SendGrid objects will be written into a separate schema, corresponding to the source instance’s schema name you designated upon creation.
Our sync component gets resources from SendGrid and forwards them to Segment using an upsert API, so the dimensional data in your warehouse loaded will reflect the latest state of the corresponding resource in SendGrid. For example, if
lists.recipient_count goes from
200 between syncs, on its next flush to your warehouse, that tickets status will be
The SendGrid source also has a streaming component which listens in real time for inbound webhooks from SendGrid’s Event Notifications and batches the events to be uploaded on your next warehouse flush. These events are only ever appended to your warehouse. At present, there is no way to retrieve email event history from SendGrid, so you will only have access to data that we’ve collected after you successfully enable this component of the source integration.
Collections are the groupings of resources we pull from your source. In your warehouse, each collection gets its own table.
Object collections are updated with each sync. These are pulled via our sync component.
Event collections are append only, represent a user action or activity, and may be likened to fact tables in a traditional data warehouse.
For a complete visual breakdown of the SendGrid collections and all their properties, view the Visual Schema here.
|activity||Event||The union of all SendGrid event tables. Useful for creating funnels|
|_open||Event||Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event.|
|click||Event||Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event.|
|bounce||Event||Receiving server could not or would not accept message.|
|delivered||Event||Message has been successfully delivered to the receiving server.|
|processed||Event||Triggered when the email is processed|
|dropped||Event||You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota|
|deferred||Event||Recipient’s email server temporarily rejected message.|
|unsubscribe||Event||Recipient clicked on message’s subscription management link. You need to enable Subscription Tracking for getting this type of event.|
|spam_report||Event||Recipient marked message as spam.|
|lists||Object||Groups of contacts.|
|segments||Object||Slices of lists.|
|recipients||Object||All contacts who have received an email, with information about their last activities and custom activities. More Info|