What Are Email Webhooks, and Do You Need Them?
What is an email webhook? A plain-English guide to delivered, bounced and opened events, when your SaaS needs webhooks, and how to set them up with Claude Code.
Quick answer
An email webhook is an automatic message your email service sends to your project the moment something happens to an email, such as delivered, bounced or opened. Your project can then act on it, like flagging a bad address. Many small SaaS products don’t need webhooks at first: checking send logs answers most questions.
Last checked: October 2026
On this page
Your email service’s settings have a section called “Webhooks,” and Claude Code may have mentioned them too. This guide explains what an email webhook is, which email events you can track, and whether your SaaS needs webhooks yet.
It’s for people building with Claude Code who don’t write code themselves. You’ll know whether to set webhooks up now or later, and what to tell Claude Code.
What is an email webhook?
An email webhook is an automatic message your email service sends to your project when something happens to an email you sent. Instead of your project asking “did it arrive yet?” over and over, the email service tells it straight away.
Think of a delivery company texting you when your parcel arrives, instead of you refreshing the tracking page every hour.
A webhook has two parts:
| Part | What it is |
|---|---|
| A listening address | A web address in your live project, such as yourcompany.com/webhooks/email, that’s ready to receive these messages. Developers call it an endpoint. |
| A list of events | The things you want to hear about, such as bounces or deliveries, chosen in your email service’s settings. |
When an event happens, the email service sends a short package of details to that address: who the email went to, which email it was, and what happened. Your project can then save it, flag a problem or alert you. Webhooks only work once your project is live, because the service needs a public address to send to.
What email events can you track: delivered, bounced, opened?
Most email services report a similar set of events. The names vary a little, but this table covers the ones you’ll see most often.
| Event | What it means | Useful for |
|---|---|---|
| Sent | The email service accepted your email and will try to deliver it | Confirming your project sent it at all |
| Delivered | The recipient’s mail server accepted the email | Showing the email reached the other end |
| Delayed | Delivery failed for a temporary reason, such as a full inbox, and the service keeps trying | Spotting slow deliveries |
| Bounced | The recipient’s mail server permanently refused the email, often because the address doesn’t exist (a “hard bounce”) | Flagging bad addresses so you stop sending to them |
| Complained | The person marked your email as spam | Stopping further emails to that person |
| Opened | The email was opened, with big limits (see below) | Rough numbers only |
| Clicked | Someone clicked a link in the email | Seeing whether people use a link, such as “Verify your email” |
“Delivered” doesn’t mean “in the inbox.” Resend, for example, defines delivered as reaching the recipient’s mail server. Which folder it lands in after that is up to the person’s email provider.
“Opened” is a rough signal at best. Open tracking usually has to be switched on, as with SendGrid’s Open Tracking setting. And Apple’s Mail Privacy Protection stops senders from seeing whether a message was opened, because Apple Mail can load an email’s images when it arrives rather than when someone reads it. For transactional email (the emails your product sends because a user did something), a click tells you far more than an open.
Do you need email webhooks?
For many small SaaS products, not yet. Webhooks earn their place when your project needs to react automatically to what happens to an email. If you only want to know what happened, send logs usually cover it.
| Situation | Do you need webhooks? |
|---|---|
| A user says they never got their reset email, and you want to know why | No. The send logs answer this. |
| You want a regular look at how many emails went out and bounced | Usually no. Logs or your email service’s reports cover it. |
| Your SaaS should mark a user’s email address as invalid the moment it bounces | Yes |
| You want to show, inside your product, whether a team invite was delivered | Yes |
| You want to stop emailing someone after they mark you as spam | Maybe. Check whether your service already does this. |
| You send a few hundred emails a month and nothing needs to happen automatically | No. Leave it for later. |
On the spam row: many services keep a suppression list of addresses they won’t send to again. Resend, for example, adds an address automatically after a hard bounce or spam complaint.
If you’re unsure, start without webhooks; adding them later doesn’t change the emails you’ve built. For working out what happened to a single email, see how to check whether your emails actually sent.
When SimpleSends is connected to Claude Code (through a connector, which lets Claude Code use another service while you build), Claude Code can read your send logs and delivery status. So you can ask in plain English:
A customer says they didn’t get their password reset email this morning. Can you check the send logs and tell me what happened?
Claude Code looks up the email and tells you whether it went out, whether it was delivered and, if it wasn’t, what the receiving server said.
How do you set up email webhooks with Claude Code?
A webhook needs three pieces, and Claude Code builds the ones that live in your project.
- A listening address in your project, which receives webhook messages and decides what to do with each one.
- A check that messages are genuine. Anyone can send data to a public address, so your project should confirm each message came from your email service, usually with a signing secret. Like an API key (a private code that lets your project use a service), it belongs in your hosting settings. Here’s where keys and secrets should go.
- The webhook switched on in your email service, with your listening address and the events you want.
Tell Claude Code what you want to happen, not how to build it:
When an email to one of my users bounces, I’d like my SaaS to mark their email address as invalid and ask them to update it next time they log in. Please set up whatever webhook this needs. Explain the plan before you make changes, and tell me anything I need to do myself.
Claude Code will lay out the plan: the listening address, which events to use, where the secret goes and how to test it. If a step happens in your email service’s settings, it will tell you what to enter and where.
Services retry when your site doesn’t answer, so the same event can arrive twice; ask Claude Code to ignore repeats. Then test before you rely on it:
Send a test email to an address that will bounce, then show me that my SaaS marked that address as invalid.
For more ways to check your emails before real users see them, read how to test your emails.
If you build with Claude Code and don’t write code, SimpleSends is made for you: connect it once, then ask Claude Code about any email in plain English.
Frequently asked questions
Is a webhook the same as an API?
Not quite. An API is how your project asks a service for something or tells it to do something, such as send an email. A webhook works the other way around: the service contacts your project when something happens. Most email services offer both, and many projects use the API to send and a webhook to hear back.
What happens if my site is down when a webhook arrives?
Most email services try again. Postmark, for example, retries several times over roughly the next hour if your site returns an error or doesn’t respond, and Resend lets you replay events your site missed. Ask Claude Code to make your listening address handle the same event twice safely, because retries can cause repeats.
Do I need a separate webhook for each event?
Usually not. With most services you give one listening address and choose which events it should receive, such as bounces and deliveries. Your project then sorts each message by its event type. Start with only the events you’ll act on, so your project isn’t storing data nobody uses.
Are email webhooks secure?
They can be. Because your listening address is public, anyone could send it fake data. Services handle this in different ways: Resend lets you verify that each request is genuine, and Postmark recommends a username and password on the address plus only accepting requests from its own IP addresses. Ask Claude Code to add whichever check your service supports.
Can I test a webhook before I rely on it?
Yes. Some services, such as Postmark, send a test to your listening address when you set the webhook up and show whether it worked. You can also ask Claude Code to send test emails that trigger real events, like a bounce, and then confirm your project reacted the way you expected.
Sources (6)
- Event Types (Webhooks)(checked October 5, 2026)
- Webhooks (introduction)(checked October 5, 2026)
- Event Webhook Reference, Twilio SendGrid Docs(checked October 5, 2026)
- Webhooks overview, Postmark Developer Documentation(checked October 5, 2026)
- Use Mail Privacy Protection on iPhone, Apple Support(checked October 5, 2026)
- Protect email privacy in Mail on Mac, Apple Support(checked October 5, 2026)
Keep reading
More on The prompt moment →Choosing a Sending Domain and From Address for Emails
Choosing a sending domain and from address for your SaaS emails: why a subdomain helps, how to name the sender, and when to skip a noreply address.
5 min read
Where to Put API Keys: .env Files Explained
Where to put API keys: a .env file while you build, your hosting settings when you go live, never your code. Plain-English steps for people using Claude Code.
6 min read
Amazon SES for Beginners: Is It Worth the Setup?
Amazon SES for beginners: what it costs, the AWS account, sandbox and permissions setup it needs, who it suits, and an option built for people who don’t code.
8 min read