Skip to main content

Reliability & Observability

When email is part of a production workflow, you need to know what happened to every message. mailbot gives you message-level visibility and reliable event delivery.

Message lifecycle​

Every message goes through a clear lifecycle with events at each stage:

EventMeaning
message.sentMessage accepted for delivery
message.deliveredLanded in the recipient's inbox
message.openedRecipient opened the email
message.clickedRecipient clicked a link
message.bouncedRejected by recipient server
message.receivedInbound reply from a contact

Each event is delivered to your webhook endpoint in real time with full context — message ID, thread ID, inbox ID, sender, recipient, and timestamps.

Retry policy​

mailbot retries failed webhook deliveries up to 3 times with exponential backoff:

  • Retry 1: 10 seconds after initial failure
  • Retry 2: 60 seconds after first retry
  • Retry 3: 300 seconds after second retry

Your endpoint must return a 2xx status code within 30 seconds. After all retries are exhausted, the event is marked as failed.

Event replay​

Failed webhook events can be replayed from the dashboard. This means:

  • No events are permanently lost due to temporary endpoint failures
  • You can inspect the full payload of any failed delivery
  • Replay sends the exact same event to your endpoint again

Webhook signatures​

Every webhook payload is signed with HMAC-SHA256 so you can verify it came from mailbot:

  • X-Mailbot-Signature: the HMAC signature
  • X-Mailbot-Timestamp: Unix timestamp of the event

Always verify signatures in production. See Webhooks for verification code.

Idempotency​

Use the messageId field as an idempotency key. Your handler should be safe to call multiple times with the same event, since retries can produce duplicate deliveries.

Bounce and complaint handling​

mailbot monitors delivery health per inbox:

  • Inboxes are auto-disabled when bounce rate exceeds 10%
  • Inboxes are auto-disabled when complaint rate exceeds 0.3%
  • Warning headers notify you before thresholds are hit

This protects your domain reputation and ensures deliverability stays high across all accounts.

Debugging​

When something goes wrong:

  1. Check the Webhooks section in your dashboard for failed deliveries
  2. Inspect the full event payload and response from your endpoint
  3. Replay failed events to retry processing
  4. Check the Audit Log for a timeline of all send/receive activity

Best practices​

  • Return 200 immediately — process events asynchronously in a background job
  • Always verify signatures — never process unverified payloads
  • Handle duplicates — use messageId as an idempotency key
  • Use HTTPS only — mailbot does not deliver to HTTP endpoints
  • Monitor your dashboard — check for failed webhook deliveries regularly