# Set Up SendGrid

> SendGrid connects to Mailrith with an API key — configure the Event Webhook to keep subscriber statuses in sync when bounces or spam complaints occur.

- Human page: https://mailrith.com/docs/setup-sendgrid
- Category: Campaigns & Delivery
- Reading time: 8 min read

## What this guide covers
Connect SendGrid using an API key and configure the Event Webhook to forward bounce and spam report events back to Mailrith.

## Sections
- Before You Start
- Mailrith Fields
- SendGrid Setup
- Event Webhook

## Visual Reference
![Mailrith email delivery connections page showing connected providers with action controls.](https://mailrith.com/docs/screenshots/email-delivery-connections.png)

The Email Delivery Connections page lists every connected provider. From here you can add a new connection, send a test email, view webhook endpoints, and assign connections to workspaces.

## Before You Start

SendGrid connects to Mailrith with an API key and sends delivery events through the SendGrid Event Webhook. Before starting, prepare these items in SendGrid:

- **A verified sender or authenticated domain:** the From email in Mailrith must be allowed by SendGrid.
- **An API key:** create a key that allows Mail Send access.
- **Event Webhook access:** needed to send bounce, dropped, and spam report events back to Mailrith.
- **A test inbox:** use it to confirm Mailrith can send through the connection before real campaigns use it.

If SendGrid is new for your domain, complete sender authentication first. A valid API key is not enough if the From email is not allowed to send.

## Mailrith Fields

In Mailrith, click [Email Delivery Connections](https://mailrith.com/docs/email-delivery-connections.md) in the left sidebar, click **Create Connection**, choose **SendGrid** in **Select Email Delivery Service**, and enter these fields in **Connect Email Delivery Service**:

- **Connection name:** an internal label, such as "SendGrid Marketing".
- **API Key:** the SendGrid key with permission to send mail.
- **From name:** the sender name subscribers see.
- **From email:** the sender address approved in SendGrid.
- **Workspaces:** the workspaces that are allowed to send through this connection.

## SendGrid Setup

1. Sign in to SendGrid and open the account that should send Mailrith email.
2. Confirm the sender identity first. For long-term sending, use SendGrid domain authentication when possible. If you are only testing, a verified single sender can work, but the From email in Mailrith must match a sender SendGrid allows.
3. If you use domain authentication, open SendGrid's sender-authentication area, start domain authentication, choose the domain, and add the DNS records SendGrid gives you at your DNS provider. Wait until SendGrid shows the domain as verified before testing in Mailrith.
4. Open **Settings** in the SendGrid left sidebar, then open **API Keys**.
5. Click **Create API Key**.
6. Name the key clearly, such as **Mailrith sending** or **Mailrith production sender**.
7. Choose permissions for the key. Use restricted permissions if your SendGrid plan and account settings allow it, and grant the key permission to send mail. Avoid giving broad account access unless your team intentionally approves that choice.
8. Click **Create & View** or the equivalent SendGrid action that creates the key and reveals the value.
9. Copy the API key immediately. SendGrid only shows the full key once.
10. Return to [Email Delivery Connections](https://mailrith.com/docs/email-delivery-connections.md) in Mailrith, click **Create Connection**, and choose **SendGrid**.
11. Paste the API key, enter the From name, enter the SendGrid-approved From email, assign workspaces, and click **Save**.
12. Use **Send Test Email** from the connection row before using the connection in a broadcast, sequence, or automation.

If the test fails, check the API key permission, sender authentication status, SendGrid account status, and whether the From email exactly matches a sender or authenticated domain that SendGrid allows.

## Event Webhook

SendGrid's Event Webhook tells Mailrith when a subscriber bounces, is dropped, or reports spam. Mailrith uses those events to update subscriber status and protect future sends.

1. In Mailrith, click **Email Delivery Connections**, click **Webhooks** on the SendGrid connection, and copy the delivery-event webhook URL exactly.
2. In SendGrid, open **Settings**, then open the **Event Webhook** settings.
3. Create a new event webhook or edit the existing event webhook used for this sender.
4. Paste the Mailrith delivery-event URL as the endpoint URL.
5. Enable bounce, dropped, and spam report events. You can enable delivered, deferred, opened, or clicked events too if your team wants provider-side reporting, but Mailrith needs the problem events to protect subscribers.
6. Save the webhook and make sure SendGrid shows it as enabled.
7. After the next test or small send, check SendGrid's webhook activity if events do not appear in Mailrith.

If Mailrith is not receiving events, check that the exact URL was copied, that the webhook is enabled, and that the selected SendGrid events include the delivery problems Mailrith needs.

## Related Guides
- [Email Delivery Connections](https://mailrith.com/docs/email-delivery-connections.md): Mailrith is provider-agnostic — you connect your own email delivery service and Mailrith handles campaign logic, subscriber targeting, and engagement tracking on top of it.
- [Broadcasts](https://mailrith.com/docs/broadcasts.md): Broadcasts are for newsletters, product launches, announcements, and any message that goes out once to selected subscribers — compose, target, test, and send or schedule from a single workflow.
- [Sequences](https://mailrith.com/docs/sequences.md): Sequences send a series of emails over time as subscribers progress through the steps — ideal for onboarding, nurture campaigns, and educational content that should unfold over days or weeks.