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 friends@segment.com.
SendGrid for nickname and sendgrid or sendgrid_prod for the schema name.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 100 to 200 between syncs, on its next flush to your warehouse, that tickets status will be 200.
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.