SendGrid

Connect your SendGrid account to GoodPostal for API-based email sending with robust webhook event tracking.

Prerequisites

• A SendGrid account (a trial account works for testing)
• A verified sender identity or authenticated domain in SendGrid

Setup Steps

1. 1

   Generate an API key

   In the SendGrid dashboard, go to Settings > API Keys > Create API Key. Full Access is the simplest choice. If you prefer Restricted Access, enable the four permissions listed below, not just Mail Send. Copy the generated key immediately, it will not be shown again.
2. 2

   Add the provider in GoodPostal

   Go to Configure > Email Providers and click "Add Provider". Select SendGrid, enter a name, and paste your API key.
3. 3

   Test the connection

   GoodPostal checks the API key against your SendGrid account before saving. If the test fails, verify the key is valid and has the permissions listed below.
4. 4

   Leave webhook setup switched on

   Set up webhooks automatically is checked by default. Leave it checked and GoodPostal configures the SendGrid event webhook for you, as described below.

API Key Configuration

Mail Send (to send your campaigns):
  - mail.send

User Account (so GoodPostal can check the key when
you save the connection):
  - user.profile.read

Tracking (so GoodPostal can switch on SendGrid's
hosted unsubscribe link, placed inside your email's
footer design):
  - tracking_settings.subscription.read
  - tracking_settings.subscription.update

Event Notification (so GoodPostal can configure
your webhooks):
  - user.webhooks.event.settings.*

If the key has Mail Send only, GoodPostal cannot turn on the
unsubscribe link and you will need a custom tracking domain
before you can send.

Webhook Setup

Webhooks are how GoodPostal tracks delivery events for your campaigns. You do not set them up by hand. GoodPostal registers the webhook on your SendGrid account over the API.

1. 1

   Leave automatic setup checked

   When you add SendGrid, the Set up webhooks automatically checkbox is already on. Leave it on and save the connection.
2. 2

   GoodPostal configures SendGrid for you

   GoodPostal points the SendGrid event webhook at its own endpoint, switches on every event it tracks, turns on Signed Event Webhook, and stores the signing key. There is nothing to copy or paste.
3. 3

   Re-run it whenever you need to

   Open Configure > Email Providers, select your SendGrid connection, and use Re-configure webhooks on the Webhook & Tracking card. Use this after you rotate an API key or if setup did not finish the first time.

Events GoodPostal Tracks

Automatic setup switches on all of these in SendGrid:

• Processed
• Delivered
• Opened
• Clicked
• Bounced
• Dropped
• Deferred
• Spam Report
• Unsubscribe
• Group Unsubscribe
• Group Resubscribe

Signature Verification

SendGrid uses ECDSA signatures for webhook verification. The signature is sent in the X-Twilio-Email-Event-Webhook-Signature header, with a timestamp in X-Twilio-Email-Event-Webhook-Timestamp.

Automatic setup turns on Signed Event Webhook and saves the public key that SendGrid returns, so verification works without any input from you. Events that fail verification are rejected. If your SendGrid plan does not offer signed webhooks, GoodPostal tells you so when setup finishes.

Troubleshooting

• 403 Forbidden when sending - Check that your API key has Mail Send permission
• "SendGrid API key is invalid or unauthorized" when saving - The key is wrong, revoked, or missing the user.profile.read permission
• Emails not being delivered - Verify your sender identity or domain is authenticated in SendGrid
• Webhooks not working - Open your SendGrid connection in Configure and check the Webhook & Tracking card. If it is not set up, use Re-configure webhooks

See also: Webhook Configuration Guide