Skip to main content
Sentvia gives your agent a full outbound email capability: compose fresh messages, reply to inbound threads, or forward existing messages to new recipients. Every send is automatically threaded, signed for deliverability, and protected by suppression logic that guards your sender reputation.

​
Send a message

To send a new email, issue a POST to /messages with the sending inbox, recipient list, and message content. Both plain-text and HTML bodies are supported — include one or both. 
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"],
    "cc": [],
    "subject": "Your order shipped",
    "text": "Tracking: 1Z…",
    "html": "<p>Tracking: <b>1Z…</b></p>"
  }'
Response
{
  "id": "m_…",
  "thread_id": "t_…",
  "direction": "outbound",
  "from_addr": "support-bot@mail.sentvia.ai",
  "subject": "Your order shipped"
}

​
Request fields

FieldDescription
inbox_idThe inbox to send from. Required.
to, cc, bccArrays of recipient email addresses. At least one to address is required.
subjectThe message subject line. Required.
text / htmlPlain-text and/or HTML body. Provide at least one.
attachmentsBase64-encoded file attachments — see the Attachments guide.
in_reply_toThe Message-ID of the message you are replying to. Used to join an existing thread.
referencesThe full References header chain from the message you are replying to.
client_idOptional idempotency key — see Idempotency below.

​
Reply & forward

When your agent receives an inbound message and needs to respond, use the dedicated reply endpoint. Sentvia derives the recipient address, corrects the subject prefix, and sets all RFC-5322 threading headers for you — you only need to supply the body. 
curl -X POST https://sentvia-api-production.up.railway.app/v1/messages/MESSAGE_ID/reply \
  -H "Authorization: Bearer sv_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Happy to help — here are the next steps.",
    "reply_all": true
  }'
Set reply_all: true to include all original CC recipients, or omit it (defaults to false) to reply only to the sender.

​
Idempotency

AI agents often operate in retry loops. To prevent duplicate emails when a request is retried — due to a timeout, a network error, or an agent re-run — pass a unique client_id with your send request. If Sentvia receives a second request with the same client_id, it returns the original message object instead of delivering a duplicate. 
{
  "inbox_id": "INBOX_ID",
  "to": ["customer@example.com"],
  "subject": "Your order shipped",
  "text": "Tracking: 1Z…",
  "client_id": "order-4821-confirm"
}
client_id values are scoped to your account. Use a value that is unique per logical send event — for example, combine an order ID with an intent label: "order-4821-confirm".

​
Suppression & blocking

Before Sentvia sends any message, it checks every recipient address against two lists:
  • Suppression list — addresses that previously produced a hard bounce or a spam complaint. These are added automatically.
  • Block list — addresses you have explicitly blocked via your account settings. See the Allow & Block Lists guide.
If one or more recipients are suppressed or blocked, Sentvia silently drops those addresses. If no deliverable recipient remains after filtering, the send returns 422 with a body listing the blocked addresses. This automatic suppression protects your sender reputation without requiring any logic in your agent.
A 422 response means your message was not sent. Check the blocked_recipients field in the error body to understand which addresses were suppressed, then decide whether to surface this to your end-user or retry with a different address.