Home Integrations Marketing Automation SendGrid Integration

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

SendGrid Integration

In this article you'll learn:

  • Steps to send data between Heap and SendGrid via SendGrid's API
  • How to format events and properties being sent between Heap and SendGrid
This doc is for: Admins Architects

Overview

Email Join Key Required

You need to have email addresses attached to your users in Heap to match data between Heap and this source. This property can be set to identity or any custom user property in Heap.

If you are not currently sending email addresses into Heap you will need to use Heap’s APIs to do so. Learn more about attaching email data to users via Heap’s identity API.

Need help? Please post in Community or contact us via the Get support page in Heap.

The Heap SendGrid source automatically captures a number of email events, including opens, clicks, and bounces, and maps them to Heap users.

With the Heap SendGrid source, you can answer questions like:

  • How do users that open your recent feature blast go on to interact with your product?
  • How many email touches does it take to properly nurture a lead to signup?
  • How do your transactional emails influence customer engagement and retention?

An important note about webhooks

When the Sendgrid integration is set up to send events into Heap, a webhook is automatically created.

If you already have webhooks set up on SendGrid, setting up Heap’s SendGrid webhook will replace your existing webhook with one that sends data to Heap.

Likewise, if after setting up Heap, you set up a SendGrid webhook with another service, Heap will stop receiving your SendGrid data. There is no way to recover the data not sent to Heap in this case.

SendGrid does not support multiple webhooks.

To connect the SendGrid source, you’ll need the following:

  1. Admin or Architect privileges in Heap
  2. Access to your SendGrid account or your SendGrid API key

To get started, navigate to Integrations > Directory > SendGrid in Heap and click Set Up in the top right corner of the page.

You will then be prompted to specify an email property if you haven’t set one up already for your selected environment. The selected user property needs to be the user property associated with your users’ email addresses, as this is the property SendGrid uses when sending Heap data about your users.

Once the email property has been set, you’ll be prompted for your SendGrid API key. The value(s) for your SendGrid API key(s) can be found on your SendGrid API keys page. You’re welcome to create a Heap-specific API key if you’d like. The API key provided needs to have at least Restricted Access with Full Access to Event Notification (can be found under Mail Settings).

Enable Click Tracking To Receive Open & Click Events

You’ll need to enable click tracking in SendGrid if you’d like to receive events in Heap when a user opens or clicks a link in an email. Please visit your tracking settings or SendGrid’s documentation to learn more.

After the API key has been provided and validated, the source connection page will present Waiting For Data until the first event data from SendGrid is seen by Heap at which point the connection status will change to Connected.

Please don’t hesitate to reach out to support@heap.io if you have any questions, or if you’re running into trouble with the source connection process.

Data Format

SendGrid source events have the following event types in Heap:

  • Receive Email: The message has been successfully delivered to the receiving server.
  • Open Email: The recipient has opened the HTML message.
  • Click Email Link: The recipient clicked on a link within the message.
  • Process Email: The message has been received and is ready to be delivered.
  • Drop Email: The message has been dropped.
  • Defer Email: The recipient’s email server temporarily rejected the message.
  • Bounce Email: The receiving server could not or would not accept the message.
  • Mark as Spam: The recipient marked the message as spam.
  • Unsubscribe to All Groups: The recipient clicked on the “Opt Out of All Emails” link.
  • Unsubscribe to Group: The recipient unsubscribed from specific group, either by either direct link or by updating their preferences.
  • Resubscribe to Group: The recipient resubscribed to a specific group by updating their preferences.

The following properties are available on each event:

  • Email: The email address of the intended recipient (String).
  • Category: The category of the email (String).
  • Certificate Error: Whether there was a certificate error on the receiving side (Boolean).
  • Sender IP: Which IP address was used to send the email (String).
  • SMTP ID: An ID attached to the message by the originating system (ID).
  • SendGrid Message Id: A unique identifier assigned to individual email messages by SendGrid (ID).
  • SendGrid Event Id: A unique identifier assigned to individual events by SendGrid (ID).

The following properties will also be ingested when applicable based on event type:

  • Advance Suppression Manager Group ID: The ID of the advance suppression manager group (ID).
  • Attempt: The number of delivery attempts (Number).
  • Reason: The reason for email bounce or drop, which given by the MTA for email bounces (String).
  • Bounce Status Code: The status code for the bounce (eg “5.0.0”) (String).
  • Bounce Type: The type of bounce (one of bounce, blocked, or expired) (String).
  • Used TLS: Was TLS used when sending the email? 0 = false, 1 = true (Number).
  • User Agent: The user agent responsible for the event (String).