API reference
Email provider webhook
Public endpoint that receives delivery event POSTs from your email provider. You configure the URL in your provider dashboard; Nudgel handles the rest.
Endpoint
This endpoint is called by your email provider, not by your application. You configure the URL in your provider's dashboard, and the provider POSTs delivery event payloads to it as messages are processed.
Authentication
The endpoint is public — it does not require a Nudgel API key or session token, because your email provider has no way to supply one. The tenantId in the URL path routes the event to the correct tenant.
Where the provider supports request signing (e.g., Postmark's X-Postmark-Signature), Nudgel validates the signature and rejects unsigned or incorrectly signed payloads. For providers that do not sign requests, the event is accepted if the payload shape is valid.
TENANT ID
Per-provider URLs
| Provider | URL |
|---|---|
| AWS SES (via SNS) | /v1/webhooks/email/ses/{tenantId} |
| Postmark | /v1/webhooks/email/postmark/{tenantId} |
| SendGrid | /v1/webhooks/email/sendgrid/{tenantId} |
| Mailgun | /v1/webhooks/email/mailgun/{tenantId} |
| Brevo | /v1/webhooks/email/brevo/{tenantId} |
| Mailjet | /v1/webhooks/email/mailjet/{tenantId} |
Full example URL:
https://api-raven-cloud.autotribes.app/v1/webhooks/email/postmark/8ad4f7c2-9e3b-4a1c-bc2f-1d8e3a9b7c4dHandled events
Nudgel normalizes provider-specific event payloads into a common internal format and writes rows to delivery_events. The following event types trigger additional actions:
| Event | Message status update | Suppression added? |
|---|---|---|
| Delivered | delivered | No |
| Hard bounce | bounced | Yes — hard_bounce |
| Soft bounce | bounced | No |
| Spam complaint | complained | Yes — spam_complaint |
| Unsubscribe | unsubscribed | Yes — unsubscribed |
| Open | No change | No |
| Click | No change | No |
Response
Nudgel returns 200 OK with an empty body for all valid payloads. Providers use the 200 response to confirm the event was received. If a provider does not receive a 200, it will retry — Nudgel is idempotent on webhook delivery events.
Returns 400 if the payload cannot be parsed, 404 if the tenant ID does not exist, and 422 if the provider name is not recognized.