Skip to main content
By the end of this guide you’ll have a live Sentvia inbox, a sent message, and a webhook ready to receive replies — everything your AI agent needs to start reading and writing email. You only need an API key and a terminal.
1

Get an API key

Open the Sentvia dashboard and navigate to API keys. Click Create key, give it a name, and copy the value — it looks like sv_live_…. Store it in an environment variable; you won’t be able to view the full key again after leaving that page.
Every request is authenticated with Authorization: Bearer sv_live_…. See Authentication for key management best practices.
2

Create an inbox

Send a POST /inboxes request with a local_part (the part before the @) and an optional display_name. The inbox is live immediately — no DNS setup, no waiting.
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" }'
The response includes the inbox id and its full address on the shared mail.sentvia.ai domain. Save the id — you’ll need it in the next step.
{ "id": "b1f2…", "address": "support-bot@mail.sentvia.ai" }
3

Send an email

Use POST /messages to send your first email from the inbox. Pass the inbox_id you received in the previous step, along with the recipient, subject, and body.
curl -X POST https://sentvia-api-production.up.railway.app/v1/messages \
  -H "Authorization: Bearer sv_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": "INBOX_ID",
    "to": ["customer@example.com"],
    "subject": "Hello from your agent",
    "text": "This email was sent by an AI agent via Sentvia."
  }'
The response includes the message id, a thread_id, and the Message-ID header. Keep the thread_id to follow the conversation as replies come in.
4

Receive the reply

When the customer replies, Sentvia threads the message and fires a message.received event to your webhook. Register your endpoint in one request:
curl -X POST https://sentvia-api-production.up.railway.app/v1/webhooks \
  -H "Authorization: Bearer sv_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.com/sentvia", "events": ["message.received"] }'
The response returns a signing secret (shown only once) — use it to verify that deliveries genuinely come from Sentvia. For the full verification flow, see Receiving email.

Next: explore the concepts

Inboxes, sending, receiving, and threading explained in depth.