Event Types
EuroMail sends webhook notifications for key email lifecycle events:
| Event | Description |
|---|---|
delivered | Email was accepted by the recipient's mail server |
bounced | Email was permanently rejected (hard bounce) |
deferred | Email delivery was temporarily delayed and will be retried |
complained | Recipient marked the email as spam via ISP feedback loop |
opened | Recipient opened the email (when tracking is enabled) |
clicked | Recipient clicked a link in the email (when tracking is enabled) |
Signed Payloads
Every webhook payload is signed with HMAC-SHA256 using your webhook signing secret. The signature is included in the X-EuroMail-Signature header. Always verify the signature before processing a webhook to ensure it was sent by EuroMail and not a third party.
import hmac
import hashlib
def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(), payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)Webhook Payload Example
{
"event": "delivered",
"timestamp": "2026-03-09T14:32:01Z",
"email_id": "em_01JQ5K8WMFZ9XRTVB3GH6EDCN4",
"from": "[email protected]",
"to": "[email protected]",
"subject": "Your order has shipped",
"domain": "yourdomain.com",
"smtp_response": "250 2.0.0 OK",
"tls_used": true,
"ip_address": "65.109.223.190"
}Automatic Retry with Exponential Backoff
If your webhook endpoint returns a non-2xx response or times out, EuroMail retries delivery with the following schedule:
- 1 minute after the first failure
- 5 minutes after the second failure
- 30 minutes after the third failure
- 2 hours after the fourth failure
- 24 hours after the fifth failure
After five failed attempts, the event is marked as undeliverable and logged in the dashboard. You can manually replay failed events from the webhook event log.
Configuration
Webhook URLs can be configured per domain or per account. Use the API or dashboard to set up endpoints:
curl -X POST https://api.euromail.dev/v1/webhooks \
-H "X-EuroMail-Api-Key: em_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/webhooks/euromail",
"events": ["delivered", "bounced", "complained"],
"domain": "yourdomain.com"
}'Omit the domain field to receive events for all domains on your account.
Dashboard Testing and Event Log
The dashboard provides a webhook testing tool that sends a sample event to your endpoint, showing the request, response, and signature verification result. The event log displays all webhook deliveries with status, response codes, and retry history, making it straightforward to debug integration issues.