Docs
/
Contact supportLog inGet started
Overview
Overview
Layouts
Settings and overrides
Sending attachments
Client previews
Amazon SES
Knock (test)
MailerSend
Mailgun
Mailjet
Mailtrap
Mandrill
Postmark
Resend
SendGrid
SMTP
SparkPost
Get startedLog inContact support
Platform
Integrations
In-app UI
API reference
CLI reference
Management API
Developer tools
Tutorials
Integrations
Email
SendGrid

How to send email with SendGrid

How to send transactional email notifications to SendGrid with Knock.

Knock integrates with SendGrid to send email notifications to your users. This page describes how to get started with SendGrid in Knock, including necessary provider configurations and additional data you can pass through to SendGrid.

Features

#
  • Attachments support
  • Delivery tracking
  • Bounce support
  • Knock link and open tracking
  • SendGrid link and open tracking
  • Per environment configuration
  • Sandbox mode

Getting started

#

Connect SendGrid to Knock

#

You can create a new SendGrid channel in the dashboard under the Channels and sources page in your account settings. From there, you'll need to configure the channel for each environment you have.

Here are a few things to note as you configure your SendGrid provider:

  • API key. At a minimum, Knock needs an API key with full access to the Mail Send permission. For webhook-based delivery tracking (recommended), no additional permissions are needed. If you're using polling-based delivery tracking, you'll need to provide an API key with read access to the Email Activity permission (requires a SendGrid paid add-on).
  • Delivery tracking. We recommend using webhook-based delivery tracking, which provides real-time updates without requiring the Email Activity add-on. See the delivery status webhooks section below for setup instructions.
  • Enable email open tracking. If enabled, you can go to the email activity page in SendGrid to check the open status of a given email.
  • Enable email link tracking. If enabled, you can go to the email activity page in SendGrid to check the link open status of a given email.

If you choose to enable open and link tracking, please keep user privacy top of mind and follow the privacy guidelines outlined in SendGrid's documentation.

Channel configuration

#

The following channel settings should be configured per environment. Navigate to Channels and sources in your dashboard account settings, select your SendGrid channel, then click "Manage configuration" under the environment that you'd like to configure.

Fields marked with an * are required.

Knock settings

Sandbox modeboolean

Whether to enable sandbox mode for your SendGrid channel.

Knock open trackingboolean

Whether to enable Knock email-open tracking.

Knock link trackingboolean

Whether to enable Knock link-click tracking.

Provider settings for SendGrid

API keystring*

The API key for your SendGrid account.

Check delivery statusboolean

When set will attempt to check for the delivery status of a message. Only available with SendGrid's Email Activity add-on.

Open trackingboolean

Whether to enable SendGrid email-open tracking.

Link trackingboolean

Whether to enable SendGrid link-click tracking.

From email addressstring | liquid*

The default sender email address (can use Liquid tags).

From namestring | liquid

The default sender name (can use Liquid tags).

When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides here.

Tostring | liquid

The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address.

Ccstring | liquid

The CC email address that email notifications will be sent to (can use Liquid tags).

Bccstring | liquid

The BCC email address that email notifications will be sent to (can use Liquid tags).

Reply-tostring | liquid

The reply-to email address that will be included on email notifications (can use Liquid tags).

Payload overridesJSON (string) | liquid

Provide a JSON object to merge into the API payload that is sent to the downstream provider.

Set optional per-environment conditions for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.

Additional data sent

#

Knock sends the following attributes along with your emails:

  • custom_args.sender: always set to knock.app
  • custom_args.knock_message_id: the ID of the message this email is associated with
  • custom_args.knock_recipient_id: the Knock ID of the recipient this email is being sent to
  • tags[0]: the key of the workflow this message was generated from

You can learn about the role of these SendGrid attributes in the SendGrid API documentation.

Recipient data requirements

#

In order to send an email notification you'll need a valid email property set on your recipient.

Delivery status webhooks

#

Delivery tracking for SendGrid can result in the following status updates to your message:

  • The message delivery is confirmed and Knock updates the message to delivered
  • The message was not delivered and Knock updates the message to undelivered
  • The message was not delivered due to a synchronous bounce and Knock updates the message to bounced

When enabled, SendGrid will send delivery status updates directly to Knock via webhooks, allowing you to track the full lifecycle of your email messages in real-time. This provides more reliable tracking than polling-based methods and captures both synchronous and asynchronous bounce events.

Prerequisites

#

Before enabling delivery status webhooks, you need:

  1. A verified sender identity or domain in SendGrid
  2. A SendGrid channel configured in Knock (see the getting started section above)
  3. Access to your SendGrid webhook settings

Setting up delivery status webhooks

#
1

Enable delivery status webhooks in Knock

  1. Navigate to Channels and sources in your Knock dashboard
  2. Select your SendGrid channel
  3. Click "Manage configuration" for the environment you want to configure
  4. Scroll to the "Incoming message status updates" section and enable incoming webhooks
  5. Copy the generated webhook URL - you'll need this in the next step
2

Configure Event Webhook in SendGrid

In the SendGrid dashboard, configure the Event Webhook to send delivery events to Knock:

  1. Go to Settings > Mail Settings > Event Webhook in your SendGrid dashboard
  2. Enable the Event Webhook if it's not already enabled
  3. In the "HTTP POST URL" field, paste the webhook URL from Knock
  4. Under "Select Actions", enable these event types:
    • Delivered - Tracks successful delivery
    • Bounce - Tracks bounce events (both hard and soft bounces)
  5. Click "Save" to activate the webhook
  6. SendGrid will begin sending events to Knock immediately

Supported delivery statuses

#

When delivery status webhooks are enabled for SendGrid, Knock will update message statuses based on these SendGrid webhook events:

SendGrid Event TypeKnock StatusDescription
delivereddeliveredThe email was successfully delivered to the recipient's mail server
bouncebouncedThe email bounced due to invalid recipient, domain, or mailbox full

Troubleshooting

#

If delivery status updates aren't appearing in Knock:

  1. Check Event Webhook status. Verify the Event Webhook is enabled in your SendGrid Mail Settings.
  2. Verify event selection. Ensure both "Delivered" and "Bounce" events are selected in your Event Webhook configuration.
  3. Verify sender identity. Ensure you're sending from a verified sender identity or domain in SendGrid.
  4. Test the webhook. Use SendGrid's "Test Your Integration" button to send a test event and verify connectivity.
  5. Check event history. Review the Event Webhook activity in SendGrid to ensure events are being sent.