Email API: what it is, how it works, and what to check before you pick one

An email API is a way to send and receive email over HTTP. Your application makes an authenticated request, the provider handles delivery, and it hands events and replies back to you as structured data.

It replaces running your own mail server, hand-building message formats and clicking through a campaign tool. A good one also tells you, through typed errors, whether to retry. This page explains how it works, then gives you a checklist. The examples use SendRaven, because those are the endpoints we can vouch for.

An email API is a way to send and receive email over HTTP

You send a request. The provider does the mail part. You get a response now and events later.

In SendRaven, the shape looks like this:

POST https://api.sendraven.ai/v1/emails
Authorization: Bearer sk_live_…
Content-Type: application/json

The URL is the endpoint. The bearer header carries your API key (sk_live_…). The JSON body holds the sender, recipient, subject and content. The exact fields are in the emails API reference in the docs.

Running your own mail server is a fine hobby. It just shouldn't be the thing standing between your users and their password resets.

How an email API works, step by step

Five steps cover most of it.

1. Request in. You authenticate with an API key or an OAuth token. Permissions are scoped, so a key can be limited to what it needs.
2. Send. POST /v1/emails sends one message. POST /v1/emails/batch sends up to 100 per call and returns 207 when some entries fail, so you can see which ones.
3. Schedule. Set scheduled_at to a timestamp or plain words like 'in 3 days'.
4. Template. Templates use {{variables}}, HTML-escaped on substitution. Rendering fails on a missing variable instead of sending a blank where a name should be.
5. Events out. Signed webhooks tell you what happened, and you can verify they came from the provider.

Attachments go up to 10MB per message. List endpoints use cursor pagination (default 50, max 100).

The four jobs a modern email API does

Sending is table stakes. The conversation is the job.

1. Send transactional mail. Receipts, password resets, alerts. One call, one message, one result you can act on.

2. Receive. Inbound replies arrive as threads, joined to the original message on Message-ID and never on subject. The text field has quoted history and signature stripped, with raw_text as the fallback. GET /v1/threads?awaiting_reply=true lists conversations waiting on you, and POST /v1/threads/:id/handled clears the flag. Replies are free and don't count toward usage. More on this in our send and receive email API with reply threads.

3. Send marketing mail. Contacts, audiences, segments, topics, and campaigns with preview. One suppression list, scoped by kind.

4. Act safely. Per-key guardrails for software that sends with nobody watching. We cover those in the checklist below.

Email API vs SMTP comes down to what your code needs to know

Both move mail. The difference is what your code gets to learn afterward.

With SMTP, you hand a message to a server and read a status line. With an HTTP API, you send JSON and get a structured response. That gives you typed errors, idempotency keys and batch results with per-entry failures. Your code can tell a retryable problem from a permanent one without parsing text.

So ask one question. Does your code need to decide something after sending? If yes, an HTTP API fits better. If you only need to relay mail from an old app that speaks SMTP, SMTP is fine.

With SendRaven, you integrate through:

• The REST API at https://api.sendraven.ai/v1.
• The OpenAPI document at https://api.sendraven.ai/openapi.json, which describes the endpoints and fields.
• The remote MCP server at https://mcp.sendraven.ai/mcp, for agents.
• The runnable examples in Node, Python, Claude over MCP and OpenAI Agents.

Transactional and marketing email can share one API

Many teams end up with two products and two suppression lists that disagree. Someone unsubscribes in one tool and keeps getting mail from the other.

SendRaven uses one API and one plan. Each domain gets two sending identities: mail. for transactional and news. for campaigns. Each has its own reputation, so a newsletter cannot trash the reputation of your password resets. The reasoning is in one plan for transactional and marketing email.

A few rules keep marketing mail honest:

• Unsubscribe cancels queued sends. It doesn't just suppress the address and leave later steps scheduled.
• A campaign is refused before it starts if the bounce or complaint rate says so.
• Marketing-class email has exactly one recipient per message.
• Only permanent bounces are suppressed, and suppression is scoped by kind.

What to check before you pick an email API

Run this list against any provider, including us.

• Pricing meter. Are you billed on emails sent or contacts stored? Are inbound replies counted?
• Inbound handling. Do replies come back as threads, or as raw webhooks with quoted history and no link to the message they answer?
• Error semantics. Can your code tell 'retry' from 'stop'?
• Idempotency. Does a retry send once?
• Separate streams. Do transactional and marketing mail have separate reputations?
• Guardrails. What can a leaked or misbehaving key do?
• Compliance paperwork. What is published, and what is only promised?
• How you integrate. REST, OpenAPI, MCP, examples. Check what actually exists.

Here is how SendRaven answers the ones that need detail.

Pricing meter

We bill emails sent. Never contacts stored. Inbound replies are free. See how you pay per email sent, not per contact.

Error semantics

Out of plan returns 402 plan_limit_reached, not 429. A 429 usually means wait and retry. A 402 means retrying changes nothing. Your code, and any model driving it, can tell the difference.

Idempotency

A retry with the same idempotency key delivers once, and retries are not counted twice. Nothing to retry, in the good sense.

Guardrails for software that sends on its own

A credential handed to an agent can send to anyone, as often as it likes, unless the provider says otherwise. Per-key limits in SendRaven:

A key cannot change its own limits or approve its own drafts. A held send is not a failure.

Compliance

SendRaven is GDPR compliant. A DPA and a subprocessor list are published on our website. SOC 2 is in progress. We don't offer data residency.

Email API pricing: per email sent versus per contact stored

Two meters exist. Per-contact pricing charges for the rows in your database, whether or not you mail them. Per-email pricing charges for what you send. We were paying for rows, not for mail, so we built the second kind.

One counted email is one outbound recipient. To, Cc and Bcc each count. Retries are not counted twice.

Free: $0/month. 3,000 emails/month, unlimited contacts, inbound included, 1 workspace, 1 sending domain, 7-day history. Sending pauses at the limit and is never auto-upgraded. A payment method is required to activate sending.

Standard: from $19/month at 50K emails. Volume pricing is automatic, so there is no tier to pick. Published points:

Standard includes unlimited sending domains, 90-day history, SSO and up to 10 people.

Enterprise: custom, suggested from around 1M emails a month.

For comparisons with other providers, see the dated checks on /compare and the full pricing page. We don't quote other vendors' prices here, because they change.

Start sending with one API call

1. Create an API key.
2. Verify a sending domain.
3. Add a payment method. It is required before any sending, including on Free.
4. Call POST /v1/emails.

You can send your first email in the quickstart and look up fields in the emails API reference. Then try the runnable examples in Node, Python, Claude over MCP and OpenAI Agents.

If an agent will operate it, connect the remote MCP server at https://mcp.sendraven.ai/mcp. It has 55 tools and is open source. The local option is the npm package @sendraven/mcp.

What we do not claim

These are trade-offs, stated plainly.

• No deliverability figure. We do not have a decade of warm IPs or an abuse team of forty, and we will not quote a deliverability figure until we have earned one.
• No data residency. We don't offer it for now.
• SOC 2 is in progress. It is not done.

Start free

Start free: 3,000 emails a month, unlimited contacts, no per-contact pricing. Send your first email in the quickstart with one API call, or connect the MCP server if an agent will do the sending.

FAQ

What is an email API?

An email API is a way to send and receive email over HTTP. Your application makes an authenticated request, the provider handles delivery, and you get events and replies back as structured data. SendRaven's version is a REST API at https://api.sendraven.ai/v1, starting with POST /v1/emails.

How does an email API work?

You authenticate with a bearer API key or OAuth token, send a JSON request, and get a response right away. Later, signed webhooks and threads tell you what happened and who replied. Batches of up to 100 go through POST /v1/emails/batch, which returns 207 when some entries fail.

What is the difference between an email API and SMTP?

Both move mail. With SMTP you hand a message to a server and read a status line. With an HTTP API you get structured responses, idempotency keys and typed errors, so your code can decide what to do after sending.

What is the difference between a transactional and a marketing email API?

Transactional mail is one-off and triggered by an event: receipts, password resets, alerts. Marketing mail goes to audiences and needs contacts, segments, topics and unsubscribe handling. SendRaven covers both with one plan for transactional and marketing email, using separate mail. and news. sending identities so each has its own reputation.

Is there a free email API?

Yes. SendRaven's Free plan is $0/month with 3,000 emails/month, unlimited contacts, inbound included, 1 workspace, 1 sending domain and 7-day history. A payment method is required to activate sending, and sending pauses at the limit rather than upgrading you.

How is an email API priced, per email or per contact?

Providers use either meter. SendRaven bills emails sent, never contacts stored, and inbound replies are free. Standard starts at $19/month for 50K emails, with published points like $35 at 100K and $379 at 1M. See the pricing page.

Can an email API receive replies, not just send?

Some can. SendRaven joins inbound replies to the original message on Message-ID, never subject, and returns them as threads with quoted history stripped from text. GET /v1/threads?awaiting_reply=true lists conversations waiting on you. Read more about the send and receive email API with reply threads.

How do I stop a retry from sending the same email twice?

Send an idempotency key with the request. A retry with the same key delivers once, and retries are not counted twice against your usage.

What happens when I hit my plan limit?

SendRaven returns 402 plan_limit_reached, not 429, so your code knows retrying won't help. On Free, sending pauses at the limit and is never auto-upgraded.

Can an AI agent use an email API safely?

Yes, if the key has limits. SendRaven has per-key guardrails: a daily send limit (429 daily_limit), a recipient allowlist (403 recipient_not_allowed) and requires_approval, which holds sends as pending_approval for a person to release. A key cannot change its own limits or approve its own drafts.

Is SendRaven GDPR compliant, and is there a DPA?

SendRaven is GDPR compliant. A DPA and a subprocessor list are published on our website. SOC 2 is in progress. We don't offer data residency.