Skip to main content

Email Events & Suppression

NotifyKit can receive delivery events from your email providers: delivered, opened, clicked, bounced, spam complaints, and more. It uses those events to show what happened to each email after it left NotifyKit, and to stop sending to addresses that hard-bounced or reported spam.

  • Free plan — emails go through NotifyKit's shared provider accounts, and NotifyKit tracks their events for you. Suppression works automatically; there's nothing to set up.
  • Indie and Startup plans — emails go through your own provider accounts, so you connect each provider's events to NotifyKit yourself. See Setting Up Tracking.

What You Get​

  • Event history per email — each email job's page in the dashboard lists the events your provider reported, with timestamps.
  • Automatic suppression — recipients who hard-bounce or mark an email as spam are added to your suppression list, and NotifyKit stops sending to them. See Suppression.

Events are recorded per provider, so set up tracking for every provider you send through.

Setting Up Tracking​

This section is for the Indie and Startup plans. Each provider is set up in API Keys in the dashboard, on that provider's card. You'll copy a webhook URL from NotifyKit into the provider, then copy a key or secret from the provider back into NotifyKit, which NotifyKit uses to check that events really came from your provider.

SendGrid​

  1. In NotifyKit, go to API Keys → Email Event Tracking and click Add Key. Copy the webhook URL shown.
  2. In SendGrid, go to Mail Settings → Event Webhook and add a webhook with that URL.
  3. Select the events to send. To get suppression, include at least Bounced and Spam Reports. Delivered, Opened, Clicked, Unsubscribed and Deferred are also recorded.
  4. Turn on Signed Event Webhook and copy the verification key.
  5. Back in NotifyKit, paste the key and click Save Key. The card shows Enabled.

Resend​

  1. In NotifyKit, go to API Keys → Resend Event Tracking and click Add Secret. Copy the webhook URL shown.
  2. In Resend, go to Webhooks and add an endpoint with that URL.
  3. Select the events to send. To get suppression, include at least email.bounced and email.complained. email.delivered, email.opened, email.clicked and email.delivery_delayed are also recorded.
  4. Copy the endpoint's signing secret (it starts with whsec_).
  5. Back in NotifyKit, paste the secret and save it. The card shows Enabled.

Postmark​

Postmark tracking appears on the Postmark card once your Postmark server token is saved.

  1. In NotifyKit, go to API Keys → Postmark → Event Tracking and click Add Secret. Copy the webhook URL shown.
  2. Choose a strong secret and save it in NotifyKit.
  3. In Postmark, open your server's Webhooks tab and add a webhook with that URL.
  4. Turn on HTTP Basic Auth. Use any username, and use the secret from step 2 as the password.
  5. Select the events to send. To get suppression, include at least Bounce and Spam Complaint. Delivery, Open, Click and Subscription Change are also recorded.

Turning Tracking Off​

Remove the key or secret on the provider's card. NotifyKit then rejects events sent to that URL, so also delete the webhook in your provider's dashboard.

Suppression​

When your provider reports one of these events, the recipient is added to your account's suppression list:

ProviderHard bounceSpam complaint
SendGridbounce events of type bounce (not blocked)spamreport
Resendemail.bounced with bounce type Permanentemail.complained
PostmarkBounce events where Postmark deactivated the address (Inactive: true)SpamComplaint

Temporary failures, such as soft bounces, full mailboxes, or a receiving server blocking the message, do not suppress the address.

What Happens to Suppressed Addresses​

Emails to a suppressed address are not sent. The send request still returns 202 Accepted, but the job fails on its first attempt and is not retried:

{
  "status": "failed",
  "errorMessage": "Recipient user@example.com is suppressed (BOUNCED). This address previously bounced or reported spam."
}

The reason is BOUNCED or SPAM_REPORT. Retrying the job manually fails the same way.

  • Per account — the list belongs to your NotifyKit account. An address suppressed for you isn't suppressed for anyone else.
  • Case-insensitive — User@Example.com and user@example.com are the same address.
  • All providers — once an address is suppressed through one provider, emails to it are blocked whichever provider would send them.
note

To remove an address from your suppression list, for example after the recipient fixed their mailbox, contact support.

Why Suppression Matters​

Repeatedly sending to addresses that bounce or complain damages your sender reputation with your provider and with inbox providers, which can push your other emails into spam or get your provider account restricted. Suppression stops that automatically.