Webhooks

Webhooks allow your application to receive real-time notifications when email events occur, such as deliveries, opens, clicks, and bounces.

Overview

NevarMail supports both inbound webhooks (receiving emails from external providers) and outbound event webhooks (notifications about email events).

Inbound parse webhook

NevarMail can receive inbound emails via provider webhooks. Currently, SendGrid Inbound Parse is fully supported.

Setup

Configure your inbound domain in NevarMail settings
Set up the webhook URL in your provider's dashboard, or let NevarMail configure it automatically:

POST /api/config/inbound-parse

This endpoint:

Reads your INBOUND_EMAIL_DOMAIN and NGROK_DOMAIN environment variables
Configures SendGrid Inbound Parse to forward emails to your NevarMail instance
Returns the configured webhook URL

Check configuration

GET /api/config/inbound-parse

{
  "configured": true,
  "hostname": "inbound.yourdomain.com",
  "url": "https://your-domain.ngrok-free.app/api/webhooks/inbound",
  "sendgridReady": true
}

Event webhooks (coming soon)

Outbound event webhooks will allow you to receive notifications when email events occur. Configure a webhook URL and NevarMail will POST event data to your endpoint in real time.

Planned event types

Event	Description
`email.sent`	Email was accepted by the provider
`email.delivered`	Email was delivered to the recipient
`email.opened`	Recipient opened the email
`email.clicked`	Recipient clicked a link
`email.bounced`	Email bounced
`email.complained`	Recipient marked as spam

Planned webhook payload format

{
  "event": "email.delivered",
  "timestamp": "2026-03-22T12:00:03.000Z",
  "data": {
    "emailId": "550e8400-e29b-41d4-a716-446655440000",
    "recipient": "user@example.com",
    "provider": "sendgrid"
  }
}

Webhook payloads will be signed with a secret key so your application can verify that requests are genuinely from NevarMail. Signature verification details will be provided when this feature launches.

Need webhooks now?

While outbound event webhooks are in development, you can:

Poll the analytics API -- Use GET /api/analytics/stats/:emailId to check event status
Use inbound routing -- Configure inbound routing rules to forward emails to webhook URLs
Track events manually -- Use POST /api/analytics/track to record events from your own webhook handlers