Webhooks Guide

Overview

Each mailbox can have one or more webhooks. When a message arrives, Mailto.Bot sends an HTTP POST to each registered URL with the full message payload as JSON.

• Delivery is near-instant — typically under 500 ms from message receipt.
• Failed deliveries are retried with exponential back-off (see Retry behaviour).
• Your endpoint must respond with a 2xx status within 10 seconds.
• Multiple webhooks on the same mailbox each receive their own delivery.

Registration

Register a webhook with POST /api/mailboxes/:name/webhooks. You can use HTTPS or HTTP (HTTP is allowed for local development).

curl -X POST \
  https://mailto.bot/api/mailboxes/abc123/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook" }'

You can list or delete webhooks from the API Reference or the Dashboard.

Payload format

Mailto.Bot sends a Content-Type: application/json POST to your URL with the following body:

{
  "event": "message.received",
  "mailbox": "abc123",
  "message": {
    "id": "msg_01HXZ...",
    "from": "sender@example.com",
    "to": ["abc123@mailto.bot"],
    "subject": "Hello from the webhook",
    "text": "Plain-text body here.",
    "html": "<p>Plain-text body here.</p>",
    "attachments": [],
    "receivedAt": "2026-04-15T20:00:00.000Z"
  }
}

Handling events

Your endpoint should acknowledge receipt immediately and process the event asynchronously. If processing takes more than 10 seconds, Mailto.Bot will consider the delivery a failure and retry.

// Express.js example
app.post('/webhook', express.json(), (req, res) => {
  const { event, mailbox, message } = req.body;

  if (event === 'message.received') {
    console.log('New message in', mailbox, ':', message.subject);
    // Process message...
  }

  // Always respond 2xx quickly
  res.sendStatus(200);
});

Retry behaviour

If your endpoint returns a non-2xx response or times out, Mailto.Bot retries the delivery with exponential back-off:

Webhook failures are visible in the Dashboard under your mailbox settings. You can re-enable a paused webhook by editing it in the Dashboard.

Testing with ngrok

During development your server runs on localhost, which Mailto.Bot cannot reach. Use ngrok to expose a public tunnel to your local server.

# Install ngrok (https://ngrok.com) then:
ngrok http 3000

# ngrok outputs a public URL like:
# Forwarding  https://abc123.ngrok.io -> http://localhost:3000

# Register that URL as your webhook:
curl -X POST \
  https://mailto.bot/api/mailboxes/abc123/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://abc123.ngrok.io/webhook" }'