Receiving email

Inbound email to any of your inboxes is parsed, threaded, and delivered to you two ways: webhooks (push, recommended) or polling with GET /messages.

Register a webhook

curl -X POST https://api.sentfrom.ai/v1/webhooks \
  -H "Authorization: Bearer sf_live_…" -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.com/sentfromai", "events": ["message.received","message.bounced"] }'

The response returns a signing secret — shown once. Store it; you’ll use it to verify every delivery.

Events

Event	Fires when
`message.received`	An inbound email arrives at one of your inboxes.
`message.delivered`	An outbound message was accepted by the recipient’s server.
`message.bounced`	A hard or soft bounce (the address is auto-suppressed).
`message.complained`	A spam complaint (the address is auto-suppressed).
`message.rejected`	The provider rejected the send.

Payload & signature

Each delivery is a JSON POST with two headers:

x-sentfromai-event: message.received
x-sentfromai-signature: sha256=<hmac>

The body is { "event": "...", ...payload }. Verify it by computing an HMAC-SHA256 of the raw request body with your webhook secret:

import crypto from "node:crypto";

function verify(rawBody: string, signature: string, secret: string) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Verify the signature on every request and reject mismatches. Always hash the raw body bytes — re-serializing the JSON will change the signature.

Delivery & retries

Deliveries are retried with backoff on non-2xx responses, so your endpoint can be briefly unavailable without losing events. Respond 2xx quickly (do heavy work async). Attachment metadata — including short-lived signed download URLs — is included in the payload; see Attachments.

Polling alternative

No public endpoint? Poll recent mail instead:

curl "https://…/v1/messages?inbox_id=INBOX_ID&limit=25" -H "Authorization: Bearer sf_live_…"

Get started

Core concepts

Guides

Examples

Agent frameworks

DNS guides

Troubleshooting

Register a webhook

Events

Payload & signature

Delivery & retries

Polling alternative

​Register a webhook

​Events

​Payload & signature

​Delivery & retries

​Polling alternative

Register a webhook

Events

Payload & signature

Delivery & retries

Polling alternative