SendGrid Source

SendGrid is a trusted platform for transactional email and email marketing. Segment makes it easy to get your data from SendGrid (and lots of other sources) into your Data Warehouse for advanced analysis.

Take your company’s analysis to the next level by having SQL access to all your SendGrid data alongside your customer event data in Redshift and Postgres.

With your SendGrid data in your warehouse, you’ll be able to analyze your email opened, email clicked and marketing campaigns in SQL. Even cooler, you’ll be able to join your SendGrid data with the Segment event data you’re already sending to your warehouse, so you can now do things like combining your email opens and clicks with website activity and analyzing them using your favorite business intelligence and sql querying tools.

SendGrid is a trusted platform for transactional email and email marketing. Visit Website

Take your company’s analysis to the next level by adding Sendgrid as a Source to Segment. We’ll automatically collect events like Click or Delivered and objects such as Recipients or Campaigns and load them into your data warehouse.

Getting Started

  1. From your workspace’s sources page, click add source.

  2. Choose Sendgrid.

  3. Give the source a nickname and a schema name. The nickname will be used to designate the source in the Segment interface, and the schema name is the namespace you’ll be querying against in your warehouse. Both can be whatever you like, but we recommend sticking to something that reflects the source itself, like 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!

  4. Provide your API Key. In order to pull information about your contacts, we’ll make requests to SendGrid’s API with our sync component. You can create an API Key by navigating to Settings > API Keys, clicking General API Key.

    You will then be prompted to name that key and given the option to adjust the settings. We recommend providing read permissions for Email Activity and Marketing Activity.

  5. 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.

  6. Copy the auto-generated Webhook URL and paste it into SendGrid’s Event Notification settings pane under Settings > Mail Settings.

  7. Once you enable the Event Notification, you’re good to go! Press Next, and then Finish to wrap up the setup flow.

Event URL

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.

Components

Sync

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. Please note: If you don’t use Sendgrid’s marketing campaigns features, these collections will be empty in Sendgrid and you’ll see “Zero data synced” in your runs. The webhook will still be processing activity data (but only activity data) for you though!

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 source syncs and warehouse syncs are independent processes. Source runs pull your data into the Segment Hub, and warehouse runs flush that data to your warehouse. Sources will sync with Segment every 3 hours. Depending on your Warehouses plan, we will push the Source data to your warehouse on the interval associated with your billing plan.

At the moment, we don’t support filtering which objects or properties get synced. If you’re interested in this feature, please let us know!

Streaming

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. Note, if you don’t use SendGrid’s marketing features, this will be the only data that we receive from SendGrid. 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 destination.

Collections

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, all their properties, and ID linkages between objects, view the visual schema here or download it in PDF form here.

CollectionTypeDescription
activityEventThe union of all SendGrid event tables. Useful for creating funnels
_openEventRecipient has opened the HTML message. You need to enable Open Tracking for getting this type of event.
clickEventRecipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event.
bounceEventReceiving server could not or would not accept message.
deliveredEventMessage has been successfully delivered to the receiving server.
processedEventTriggered when the email is processed
droppedEventYou 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
deferredEventRecipient’s email server temporarily rejected message.
unsubscribeEventRecipient clicked on message’s subscription management link. You need to enable Subscription Tracking for getting this type of event.
spam_reportEventRecipient marked message as spam.
listsObjectGroups of contacts. Will only return data if you’re using Marketing Campaign featurs of SendGrid.
segmentsObjectSlices of lists. Will only return data if you’re using Marketing Campaign featurs of SendGrid.
recipientsObjectAll contacts who have received an email, with information about their last activities and custom activities. More Info. Will only return data if you’re using Marketing Campaign featurs of SendGrid.
campaignsObjectAll campaigns you’ve created in Sendgrid. More Info. Will only return data if you’re using Marketing Campaign featurs of SendGrid.

If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!