API

Every request needs an Authorization header with your API key. Keys start with mb_live_ (production) or mb_test_ (test mode). Mint keys at your dashboard and treat them like passwords — they grant full account access at the scopes you select.

Authorization: Bearer mb_live_<your-key-here>

Create an order

curl -X POST \
  -H "Authorization: Bearer mb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"quantity":500,"message":"Hi {{first_name}}, …","campaign_type":"handwritten"}' \
  https://mailbots.ai/api/v1/orders

The response includes the order id. Upload your recipient list to /orders/:id/recipients next, then pay through the dashboard or by hitting /orders/:id/checkout.

List mailed orders

curl -H "Authorization: Bearer mb_live_..." \
  "https://mailbots.ai/api/v1/orders?status=mailed&limit=20"

Pull tracking for an order

curl -H "Authorization: Bearer mb_live_..." \
  "https://mailbots.ai/api/v1/orders/01K.../tracking"

Get pushed updates instead of polling. Mailbots POSTs JSON to your URL with two headers: X-Mailbots-Event and X-Mailbots-Signature (HMAC-SHA256 of the raw body, hex-encoded, prefixed sha256=).

Register

curl -X POST \
  -H "Authorization: Bearer mb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.example.com/mailbots-webhook","events":["order.mailed","piece.delivered"]}' \
  "https://mailbots.ai/api/v1/webhooks"

The response includes a secret shown ONCE — store it. Use it to verify every incoming delivery.

Verify a delivery (Node)

import crypto from 'node:crypto';

function verifyMailbotsSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const [, received] = signatureHeader.split('=');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received, 'hex')
  );
}

// In your handler:
const raw = await readRawBody(req);
const sig = req.headers['x-mailbots-signature'];
if (!verifyMailbotsSignature(raw, sig, process.env.MAILBOTS_WEBHOOK_SECRET)) {
  return res.status(401).end();
}
const event = JSON.parse(raw);
console.log(event.event, event.order_id);

Event types

When you mint a key you select which scopes it carries. Default keys carry all scopes; restrict if a key only needs read access.

• orders.create — POST /orders
• orders.read — GET /orders, /orders/:id, tracking, analytics
• orders.update — PATCH /orders/:id, upload recipients
• orders.delete — DELETE /orders/:id
• account.read — GET /account
• account.manage — manage API keys
• webhooks.manage — manage webhook subscriptions

List endpoints accept ?limit= and ?offset=. Default limit=20, max 100. Total row count returns in the pagination.total field.

Prefix your key with mb_test_ instead of mb_live_ to test against Stripe's test environment. Test orders never charge real money or mail real cards. Switch back to your live key when you're ready to ship.

Standard limit: 60 requests/minute per key. List endpoints: 30 requests/minute. Hit the limit and you'll get a 429 with a Retry-After header. Need higher limits? Email support@mailbots.ai.

• 401 — missing, malformed, or revoked API key
• 403 — your key lacks the required permission scope
• 404 — order, piece, or webhook not found
• 400 — validation error (details in details)
• 429 — rate limit exceeded
• 500 — server error; safe to retry with backoff

Email support@mailbots.ai with your account email and a sample request — we usually respond within a business day.