Webhooks & waiting

Two ways to react to inbound mail: webhooks (push, for always-on agents) and the wait endpoint (pull, perfect for one-shot flows like reading a login code).

Wait for the next email

Holds the connection open until a matching email arrives, then returns it. Query: timeout (seconds, ≤120), match (only return a message containing this text), since (a message id to wait past). Returns the message, or {"message": null, "timeout": true}.

# agent signs up somewhere, then reads the verification code
curl "https://app.cloudbox.biz/api/v1/mail/inboxes/inb_123/messages/wait?timeout=90&match=verification" \
  -H "Authorization: Bearer $CBS_KEY"

Webhooks

Body: url, events (array of message.received, message.sent, message.bounced), optional inbox_id (omit = all your inboxes). The response includes a secret, shown once, for verifying signatures.

Verifying a webhook

Each delivery carries X-CloudBox-Signature: t=<unix>,v1=<hex>. Recompute HMAC-SHA256(secret, t + "." + body) and compare - reject if it does not match or t is stale.

import hmac, hashlib
def verify(secret, sig_header, body):
    parts = dict(p.split("=",1) for p in sig_header.split(","))
    want = hmac.new(secret.encode(), (parts["t"]+".").encode()+body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts["v1"], want)

Deliveries retry with backoff (1m, 5m, 30m, 2h, 8h) and are dead-lettered after five failures.