Sending API

The Sending API is Mailvora's REST interface for applications. It sends transactional email such as invoices, receipts, sign-in codes and alerts, and reports what happened to each message.

Base URLhttps://api.<your-domain>/v1
AuthenticationAuthorization: Bearer mv_live_… (or mv_test_…)
FormatJSON over HTTPS
IdempotencyIdempotency-Key header on POST /v1/messages
EventsSigned webhooks (Mailvora-Signature)

The in-app API quickstart page (/developers) has copy-ready Node, Python and PHP examples.

Authentication

Create a key in the console under API keys. A key looks like mv_live_<12 characters>_<40 characters>; mv_test_ keys process messages without delivering them. The secret is shown once and stored only as a hash.

Give each application its own key with only the permissions it needs, restrict it by IP address and sender domain, set an expiry, and rotate it regularly.

Sending a message

curl https://api.example.com/v1/messages \
  -H "Authorization: Bearer $MAILVORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from":"billing@school.example","to":"parent@example.org",
       "template":"invoice","variables":{"number":"INV-1042"}}'

202 Accepted means the message was stored and queued, not that it was delivered. Track progress with GET /v1/messages/{id}, in the console, or through webhooks. Statuses: scheduled, cancelled, queued, processing, accepted_by_mta, delivered, deferred, bounced, failed, suppressed and sandboxed (test keys).

Repeating a request with the same Idempotency-Key returns the original result instead of sending twice, so it is safe to retry after a timeout.

Endpoints

MethodPathPermission
POST/v1/messagesmessages:send
GET/v1/messagesmessages:read
GET/v1/messages/{id}messages:read
POST/v1/messages/{id}/cancelmessages:send
GET/v1/messages/export.csvmessages:read
GET/v1/templatestemplates:read
POST/v1/templatestemplates:write
POST/v1/templates/{id}/previewtemplates:read
GET/v1/suppressionssuppressions:read
POST/v1/suppressionssuppressions:write
DELETE/v1/suppressions/{email}suppressions:write
GET/v1/domainsdomains:read
GET/v1/webhookswebhooks:read
POST/v1/webhookswebhooks:write
GET/v1/usageusage:read
GET/v1/mailboxesmailboxes:read

Webhooks

Register an HTTPS endpoint in the console to receive message events: scheduled, queued, accepted, delivered, deferred, bounced, complained, failed, suppressed, unsubscribed and cancelled (each prefixed with message.). Every request carries these headers:

HeaderMeaning
Mailvora-Signaturet=<unix time>,v1=<hex HMAC-SHA256> over "<t>.<raw body>", keyed with the endpoint secret
Mailvora-Event-IdUnique event ID (use it to ignore duplicates)
Mailvora-Event-TypeFor example message.delivered
Mailvora-Delivery-IdThis delivery attempt's ID
Mailvora-Delivery-AttemptAttempt number, starting at 1

Verify the signature over the raw body and reject timestamps older than five minutes to prevent replay. Failed deliveries are retried with exponential backoff and can be replayed from the console.

Bounces, complaints and suppressions

Hard bounces, spam complaints and one-click unsubscribes (RFC 8058) add the address to the organisation's suppression list automatically; later messages to it are refused without being sent. Remove an entry with DELETE /v1/suppressions/{email} once the problem is fixed.

See also

Help

Are you sure?