Webhooks & Events

IvyMail tracks every email event (delivery, bounce, complaint) and makes them available through the dashboard logs and optional webhooks.

Event types

Event	Description	Trigger
`delivered`	Email accepted by recipient's mail server	SES delivery notification
`bounced`	Email permanently rejected	Hard bounce from recipient server
`complained`	Recipient marked email as spam	Complaint feedback loop
`suppressed`	Send blocked by IvyMail	Recipient on suppression list
`failed`	Send failed before reaching SES	Invalid config, unverified domain, etc.

Dashboard logs

All events are logged automatically. View them at Dashboard → Logs. Each log entry includes:

Message ID
Recipient address
Status
Timestamp
Error details (for failed/bounced sends)

Filter logs by type (send, bounce, complaint) and status.

Webhook setup

Configure webhooks at Dashboard → Webhooks to receive real-time notifications at your server.

Webhook payload

JSON

{
  "event": "delivered",
  "message_id": "abc123-def456-ghi789",
  "to": "recipient@example.com",
  "from": "you@yourdomain.com",
  "subject": "Hello from IvyMail",
  "timestamp": "2026-02-25T12:00:00Z",
  "workspace_id": "ws_xxxx"
}

Bounce event payload

JSON

{
  "event": "bounced",
  "message_id": "abc123-def456-ghi789",
  "to": "invalid@example.com",
  "bounce_type": "Permanent",
  "bounce_subtype": "General",
  "diagnostic_code": "smtp; 550 5.1.1 user unknown",
  "timestamp": "2026-02-25T12:00:00Z"
}

Complaint event payload

JSON

{
  "event": "complained",
  "message_id": "abc123-def456-ghi789",
  "to": "user@example.com",
  "feedback_type": "abuse",
  "timestamp": "2026-02-25T12:00:00Z"
}

Retry policy

If your webhook endpoint returns a non-2xx status code, IvyMail retries up to 3 times with exponential backoff.

Security

Verify webhook authenticity by checking the x-ivymail-signature header against your webhook secret. This prevents third parties from sending fake events to your endpoint.

Best practices

Always return a 200 response quickly, then process the event asynchronously.
Use the message_id to correlate events with your original send.
Handle duplicate events idempotently. The same event may be delivered more than once.
Monitor your webhook endpoint's error rate in the dashboard.

For AI agents & LLMs

If you're an AI agent and need to check the delivery status of a sent email, query the logs:

Bash

curl "https://api.ivymail.io/v1/send/logs?limit=10&type=send" \
  -H "x-api-key: $IVYMAIL_API_KEY"

To check for bounces or complaints:

Bash

curl "https://api.ivymail.io/v1/send/logs?type=bounce&limit=10" \
  -H "x-api-key: $IVYMAIL_API_KEY"

Use the message_id from the send response to correlate events.