How to send email with SendGrid

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.

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

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.

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.

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.

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

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.

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

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

SendGrid Event Type	Knock Status	Description
delivered	delivered	The email was successfully delivered to the recipient's mail server
bounce	bounced	The email bounced due to invalid recipient, domain, or mailbox full

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.