Skip to main content
An inbox is the fundamental unit of email identity in Sentvia. Every inbox maps to a real email address — like support-bot@mail.sentvia.ai — that your agent can send from, receive into, and use to group related messages into threaded conversations. You typically provision one inbox per agent, per user, or per task.

​
Create an inbox

To create an inbox, send a POST request to /inboxes with a local_part (the portion before the @) and an optional display name. Sentvia automatically appends the default shared domain mail.sentvia.ai unless you specify a verified custom domain.
1

Send the request

curl -X POST https://sentvia-api-production.up.railway.app/v1/inboxes \
  -H "Authorization: Bearer sv_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "support-bot",
    "display_name": "Support"
  }'
2

Receive the inbox object

Response
{
  "id": "b1f2…",
  "local_part": "support-bot",
  "display_name": "Support",
  "address": "support-bot@mail.sentvia.ai"
}

​
Request fields

FieldRequiredDescription
local_partYesThe part before the @. Lowercased automatically; only [a-z0-9._-] characters are allowed.
display_nameNoThe friendly “From” name shown on outbound mail.
domain_idNoA verified custom domain. Defaults to the shared mail.sentvia.ai.
Addresses are globally unique on the shared domain. If the local_part you requested is already taken, the API returns 409 address_taken. Choose a more specific local part — for example, include a tenant ID or UUID — to avoid collisions.

​
List & delete inboxes

You can retrieve all inboxes on your account or remove one you no longer need. 
curl https://sentvia-api-production.up.railway.app/v1/inboxes \
  -H "Authorization: Bearer sv_live_…"
Deleting an inbox is permanent. All messages and threads associated with it are also removed and cannot be recovered.

​
Inbox limits

Each plan includes a fixed number of concurrent inboxes. The table below shows the limit for each tier.
PlanInboxes
Free3
Pro100
Scale1,500
Business15,000
If you attempt to create an inbox beyond your plan’s limit, the API returns 402 inbox_limit_reached with an upgrade: true flag in the response body. You can check your current inbox count at any time in the Sentvia dashboard.
Agents that manage one inbox per end-user scale quickly. Plan for inbox growth early — upgrading mid-flight is seamless, but it’s easier to start on the right tier.

​
Custom domains

By default, all inboxes use the shared mail.sentvia.ai domain. If you want your agents to send and receive from an address on your own domain — like assistant@yourcompany.com — follow the custom domains guide to verify your domain and pass its domain_id when creating inboxes.