When email arrives at one of your inboxes, Sentvia parses it, threads it with related messages, and notifies you in real time. You can receive these notifications via webhooks (recommended for production) or by polling the messages API if you prefer a pull-based approach.
Register a webhook
A webhook tells Sentvia where to POST event payloads. You choose which event types to subscribe to — you can subscribe to all events or only the ones your agent needs to act on.
Create the webhook
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", "message.bounced"]
}'
Save the signing secret
The response includes a secret field — a signing key used to verify every future delivery. It is shown only once. Store it in your secrets manager immediately; you cannot retrieve it again.
Events
Sentvia emits the following event types. Subscribe only to the events your agent needs to keep payloads lean.
| 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 mail server. |
message.bounced | A hard or soft bounce occurs — the recipient address is auto-suppressed. |
message.complained | A spam complaint is reported — the recipient address is auto-suppressed. |
message.rejected | The sending provider rejected the message before delivery. |
Payload & signature verification
Each webhook delivery is an HTTP POST to your endpoint with two custom headers and a JSON body.
x-sentvia-event: message.received
x-sentvia-signature: sha256=<hmac>
x-sentvia-signature using a constant-time comparison.
import crypto from "node:crypto";
function verify(rawBody: string, signature: string, secret: string): boolean {
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 any that do not match. Always hash the raw body bytes exactly as received — parsing and re-serializing the JSON will change the byte sequence and invalidate the signature.
Delivery & retries
Sentvia considers a delivery successful when your endpoint responds with any 2xx status code. If your endpoint returns a non-2xx response or does not respond within the timeout window, Sentvia retries the delivery with exponential backoff. This means your endpoint can be briefly unavailable without losing events.
Respond 2xx as quickly as possible and handle any heavy processing asynchronously. Webhook payloads for message.received events include attachment metadata with short-lived signed download URLs — fetch the attachment content after you acknowledge the delivery.
Polling alternative
If you cannot expose a public HTTPS endpoint — for example, during local development or in a closed network — you can poll for recent messages instead.
curl "https://sentvia-api-production.up.railway.app/v1/messages?inbox_id=INBOX_ID&limit=25" \
-H "Authorization: Bearer sv_live_…"
Polling is best suited for development and low-volume use cases. For production workloads, webhooks are strongly recommended — they deliver events in real time and eliminate the latency and overhead of repeated API calls.