Transactional Email API (2026): What It Is and How to Send with Rovela

What a transactional email API is, which messages it covers, and how to send with Rovela: POST /emails, a verified domain, Idempotency-Key, and delivery tracking.

What a transactional email API is

A transactional email API is how your product sends the mail a person just caused — a sign-up code, a password reset, an order receipt, a security alert — over a normal HTTP request. Each message goes to a specific recipient and carries information they requested or triggered. That is different from a newsletter blasted to a list. Rovela’s transactional email product is built around that pattern: you POST a JSON body to /emails, Rovela queues the message, DKIM-signs it with your domain’s key, SPF-aligns it, and gives you a message id to track what happened next.

This pillar is the “what and how” of a transactional email API, with Rovela as the concrete product. It is not a rewrite of Transactional vs Marketing Email (that post is the category distinction), not Transactional Email for AI Apps (AI-app patterns), and not the Send Your First Email in 5 Minutes onboarding walkthrough. If you are choosing a transport, start with Email API vs SMTP; if you already know you want HTTPS, keep reading.

Start from the Email API product page, the Quick Start, the Send Email API, and Authentication.

Why products use an API instead of a mail server

Transactional mail has to be correct, timely, and traceable. A password-reset message that never arrives, or arrives twice with two different links, is a support ticket. An API helps because:

Your app already speaks HTTP. A server-side POST with Authorization: Bearer and a JSON body fits the same stack as the rest of your backend. There is no official Rovela SDK to install — the API is plain HTTP and JSON at https://api.rovela.dev (Installation).
Acceptance is synchronous; delivery is not. A 200 with {"object":"email","id":"…"} means Rovela accepted and queued the message, not that it is already in the inbox (Quick Start). You can later GET /emails/:id or subscribe to delivery webhooks.
Retries can be made safe. An Idempotency-Key header (up to 256 characters) makes a retry of the same request within 24 hours return the original response instead of sending again (Idempotency Keys for Email APIs).
The domain is yours. The from address must be on a verified sending domain. Unverified domains are refused with 400. See Verified Domain Email API and What Is an Email Domain?.

What you send, field by field

The Send Email API accepts:

Field	Required	Notes
`from`	yes	e.g. `"Acme <hello@yourdomain.com>"`, on a verified domain
`to`	yes	One address or an array. `to` + `cc` + `bcc` ≤ 50 recipients
`subject`	yes*	Not required when a template supplies one
`html` / `text`	one of these or `template`	Send both HTML and text when you can
`template`	no	`{ id, variables }` — mutually exclusive with `html` and `text`
`cc` / `bcc`	no	Count toward the 50 cap and toward quota
`reply_to`	no	Where replies should go
`scheduled_at`	no	Future ISO 8601 timestamp (include the offset)
`tags`	no	Labels returned with the message
`headers`	no	Custom headers
`topic_id`	no	Only send to contacts subscribed to that topic
`attachments`	no	`{ filename, content (base64), content_type }`

Quota is charged per recipient, not per message: three people in to/cc/bcc cost three of the monthly allowance. A batch of 100 messages to two recipients each costs 200.

Send the first transactional message

Prerequisites: an account, a verified sending domain, and an API key shaped like re_…. Prefer sending_access for production senders — it can send and nothing else. Reading a message, rescheduling, or cancelling needs full_access or a dashboard session (Authentication). There is no separate sandbox key; a free-plan key sends real mail (Quick Start, pricing).

curl -X POST https://api.rovela.dev/emails \
  -H "Authorization: Bearer re_your_sending_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: verify-signup-8f3a2c" \
  -d '{
    "from": "Acme <no-reply@yourdomain.com>",
    "to": "alice@example.com",
    "subject": "Your Acme code: 482913",
    "html": "<p>Your verification code is</p><p style=\"font-size:28px;letter-spacing:6px\"><b>482913</b></p><p>It expires in 10 minutes.</p>",
    "text": "Your verification code is 482913. It expires in 10 minutes."
  }'

The Idempotency-Key is what makes a timed-out retry safe: the reader gets one code, not two that disagree. The full recipe for generating, hashing, and checking a code is in the verification code example and Sending OTP Codes by Email.

From application code the same request is a fetch or urllib call — see Send Transactional Email from Your App and HTTP Email API. For a command-line walkthrough of headers, errors, batch, and cancel, see Send Email with curl.

The messages almost every product sends

Sign-up / login codes and magic links — generate the secret on your server, send HTML + text, key the request per attempt. Examples: verification codes, Sending OTP Codes by Email.
Password resets — a single-use, short-lived link from your domain. Password reset example, Secure Password Reset Emails.
Welcome mail — often a stored template so copy can change without a redeploy. Welcome template example, Welcome Email from a Template, Email Templates API Guide.
Invoices and receipts — attach a PDF in the same POST. Invoice attachment example, Send an Invoice Email with a PDF Attachment.
Reminders and follow-ups — batch (up to 100) or scheduled_at. See Batch Transactional Email API and Scheduled Email Sending.

SaaS teams packing several of these into one product may prefer Email API for SaaS Apps. Notification-style ops alerts are covered in Email Notification API.

After the `200`: status, events, and webhooks

GET /emails/:id (and GET /emails/:id/events) needs a full_access key or a session. For production, subscribe a webhook instead of polling: Webhooks overview, Transactional Email Webhooks. The events that should change something on your side are typically email.bounced, email.complained, and — for marketing/contacts — contact.unsubscribed. email.opened and email.clicked fire only when tracking is enabled on the sending domain.

If you also need people to read mail at you@yourdomain.com, Rovela hosts mailboxes and webmail; that is a different surface from the sending API. See Transactional Email API + Hosted Mailboxes and Inbound and Outbound Email API.

Production checklist

Verified sending domain; from matches it (Verified Domain Email API)
Production key is sending_access, server-only, never in a browser or mobile app
Every user-triggered send carries a stable Idempotency-Key
HTML and text bodies (or a stored template)
Webhooks for bounces and complaints, signatures verified (Verifying Webhook Signatures)
Know the 50-recipient cap and per-recipient quota
Use POST /emails/batch for personalized transactional fan-out, not a marketing broadcast (Marketing emails / broadcasts)

FAQ

Is a transactional email API the same as SMTP? No. SMTP is a mail transport you speak from a client or library; an email API is an HTTP interface that accepts JSON and then talks SMTP to the rest of the internet for you. Comparison: Email API vs SMTP. Migrating an app: Migrate SMTP to an Email API.

Does Rovela have an official SDK? No. Any language that can make an HTTPS request works (Email API).

Can I send marketing campaigns through POST /emails? You can send individual messages, but list fan-out, one-click unsubscribe, and topic suppression are what broadcasts are for. The distinction is explained in Transactional vs Marketing Email.

What does sending_access allow? Enough to queue mail via POST /emails and POST /emails/batch. Reading, rescheduling, and cancel need full_access or a dashboard session.

Does a 200 mean the user already has the email? No — accepted and queued. Use GET /emails/:id, events, or webhooks.

Ship the API, let Rovela deliver

Treat transactional mail as a first-class part of your product: a verified domain, a server-side sending_access key, a JSON POST to /emails, and an idempotency key per logical send. Rovela queues, signs, and delivers; your app stays on HTTP. When you are ready, send the first message and then wire the rest of the journey from the guides above.