Skip to main content

​
Getting started

In the dashboard → API keys → create a key. It looks like sv_live_…. Pass it as Authorization: Bearer sv_live_… on every request. Keys are workspace-scoped; create one per service or environment and revoke freely.
POST /inboxes { "local_part": "support-bot" } returns an address on the shared mail.sentvia.ai domain, live immediately — no DNS setup. See Inboxes.
Two options: register a webhook for message.received (push, recommended), or poll GET /messages?inbox_id=…. For low-latency agents, stream events over the realtime WebSocket.
Use POST /messages/{id}/reply — Sentvia derives the recipient and sets the In-Reply-To/References headers automatically. See Threads.
Add rules with POST /lists (kind: allow/block, direction, pattern). See Allow & block lists. Bounces and complaints are auto-suppressed separately.

​
Errors

Missing or invalid API key. Check the Authorization: Bearer … header and that the key hasn’t been revoked.
A plan limit was hit. The error tells you which: inbox_limit_reached, custom_domains_require_paid_plan, dedicated_subdomain_requires_scale, or storage_limit_reached. Upgrade from Billing.
That inbox address is already in use (addresses are globally unique on the shared domain). Pick a different local_part.
A single email’s attachments must fit within ~7 MB (the encoded message stays under the 10 MB provider limit). Split large files or share a link instead. See Attachments.
Every recipient was suppressed (a prior bounce/complaint) or on your block list, so there was no one deliverable. The response lists the blocked addresses.

​
Deliverability

Hard bounces add the address to your automatic suppression list so you don’t keep sending to it. Check the recipient is valid; subsequent sends to a suppressed address are dropped.
Publish all returned DNS records (DKIM, SPF, DMARC, MAIL-FROM) exactly, with no extra quoting, and give DNS a few minutes to propagate. See the DNS guides and Deliverability.
Pass a unique client_id on POST /messages. A repeated client_id returns the original message instead of sending again — safe to retry after a timeout.
Authenticate with a verified custom domain (SPF/DKIM/DMARC), warm up volume gradually, and keep bounce/complaint rates low. Full guidance in Deliverability.