Webhooks

Instead of polling an inbox endpoint every N seconds, Emails4Agents pushes a webhook to your endpoint the moment something happens. Build reactive agents, not polling loops.

Event types

Event	Trigger
message.received	New inbound email stored in inbox
message.sent	Outbound email accepted by SES
message.delivered	SES confirms delivery
message.bounced	Email bounced — hard or soft
message.classified	Claude classification completed
message.failed	Send failed after all retries
domain.verified	DNS records verified successfully

Register a webhook

curl -X POST https://api.emails4agents.com/v1/webhooks \
  -H "X-API-Key: e4a_..." \
  -d '{
    "url": "https://your-agent.com/webhooks/email",
    "domain_id": null,
    "events": ["message.received", "message.bounced"]
  }'

Set domain_id to scope webhooks to a specific domain, or leave null to receive events across all your domains.

Webhook payload

{
  "event": "message.received",
  "timestamp": "2025-04-16T10:23:45Z",
  "data": {
    "id": "msg-uuid",
    "inbox_id": "inbox-uuid",
    "thread_id": "thread-uuid",
    "direction": "inbound",
    "from_address": "[email protected]",
    "to_address": "[email protected]",
    "subject": "Re: Your request has been processed",
    "text_body": "Thanks, but can you also...",
    "classification": "follow_up",
    "classification_confidence": 0.94
  }
}

Retry behavior

Failed webhook deliveries are retried with exponential backoff: 30s → 2m → 10m → 1h → 6h. If all retries fail, the event is logged with status: failed and you can replay it manually.

Filtering

Each webhook registration specifies which events to receive. You can register multiple webhooks pointing to different endpoints with different event filters — useful for routing message.bounced to a deliverability monitor and message.received to your agent handler.