Quickstart

The core workflow is one multipart request: upload the document, include the recipient address, set a cost cap, and optionally use dry_run=true first for a no-charge quote.

Have a member key? Use sk_live_ for setup, then create an agent credential with mail.send. Use the returned sk_agent_ or sk_agent_test_ key for this request.

Inbound thread fields are optional advanced context. Leave them out for normal outbound sends.

curl -X POST https://mailbox.bot/api/v1/mail \
  -H "Authorization: Bearer sk_agent_test_..." \
  -H "X-Mailbox-MD-Version: 3" \
  -H "X-Max-Cost-Cents: 1500" \
  -F "document=@notice.pdf" \
  -F "recipient_name=State of Delaware" \
  -F "recipient_company=Division of Corporations" \
  -F "recipient_line1=401 Federal Street, Suite 4" \
  -F "recipient_city=Dover" \
  -F "recipient_state=DE" \
  -F "recipient_zip=19901" \
  -F "mail_class=certified_return_receipt" \
  -F "dry_run=true"

Do not infer speed, tracking, or proof from carrier marketing names. Choose the enum by the required outcome, then use dry_run=true to compare authenticated cost before sending live mail.

Every webhook is HMAC-SHA256 signed. Your dashboard shows a visual progress tracker with fulfillment photos, available tracking info, and timestamps at each stage.

import crypto from "node:crypto";

export function verifyMailboxWebhook(rawBody, signature, secret) {
  const match = signature.match(/^([^:]+):t=(\d+),v1=([a-f0-9]+)$/);
  if (!match) return false;

  const [, keyPrefix, timestamp, expected] = match;
  const signedPayload = `${timestamp}.${rawBody}`;
  const digest = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  return keyPrefix.startsWith("whsk_") &&
    crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(expected));
}

GET /v1/mail?q=Austin&limit=20
GET /v1/mail?q=TEST1Z999AA1000065&status=mailed
GET /v1/mail?q=invoice&created_after=2026-06-01&created_before=2026-06-30

{
  "event": "package.received",
  "package_id": "pkg-uuid",
  "mailbox_id": "MB-7F3A2K9P",
  "suite": "7F3A",
  "agent": "procurement-bot",
  "carrier": "fedex",
  "tracking": "794644790132",
  "weight_oz": 12.4,
  "photos": [
    "https://cdn.mailbox.bot/pkg/7F3A2K9P_001.jpg"
  ],
  "received_at": "2026-02-09T14:32:00Z"
}

POST /v1/agents/:id/credentials
Authorization: Bearer sk_live_...

{ "scopes": ["mail.send", "package.read", "webhook.manage"], "environment": "test" }

Returns an sk_agent_test_ key. Use it on any production endpoint — same code, no charge, HMAC-signed webhooks fire normally.

These guards apply identically to both sandbox and live keys — test the integration once and the same protections run in production: