Developers

Send your first email with one HTTP call.

Refiremail is a plain REST API at api.refiremail.com. Send JSON with your key in the Authorization header, from any language. There is no SDK to install.

Request early access How switching works

send.shShell

curl -X POST https://api.refiremail.com/emails \
  -H "Authorization: Bearer $REFIREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "from": "Nimbu <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Order #1042 is confirmed",
    "html": "<p>Thanks, Asha. Your order ships tomorrow.</p>"
  }'

01, Quickstart

From a new account to a delivered email.

Three steps. The first two happen once; the third is the code you keep.

Create an API key
Once your early access is on, create a key in the dashboard under API keys. Give a service that only sends a sending-only key. The key is shown once and stored only as a hash.
Request early access
Verify your domain
Add the DKIM and SPF records we show you. We start checking a minute after you add the domain; how soon they are found depends on your DNS host.
What the records do
Send
Pick your language. Each tab has the .env and the code, and none of them needs an SDK.

NodePythonPHPcURL

.env

# .env
REFIREMAIL_API_KEY=<your Refiremail key>

send.tsTypeScript

const res = await fetch('https://api.refiremail.com/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.REFIREMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'Nimbu <[email protected]>',
    to: ['[email protected]'],
    subject: 'Order #1042 is confirmed',
    html: '<p>Thanks, Asha. Your order ships tomorrow.</p>',
  }),
});

const { id } = await res.json(); // 200 OK → { "id": "…" }

Node 18 or later: fetch is built in.

Shell

pip install requests

.env

# .env
REFIREMAIL_API_KEY=<your Refiremail key>

send.pyPython

import os
import requests

res = requests.post(
    "https://api.refiremail.com/emails",
    headers={"Authorization": f"Bearer {os.environ['REFIREMAIL_API_KEY']}"},
    json={
        "from": "Nimbu <[email protected]>",
        "to": ["[email protected]"],
        "subject": "Order #1042 is confirmed",
        "html": "<p>Thanks, Asha. Your order ships tomorrow.</p>",
    },
    timeout=10,
)
res.raise_for_status()
email_id = res.json()["id"]

.env

# .env
REFIREMAIL_API_KEY=<your Refiremail key>

send.phpPHP

<?php
$ch = curl_init('https://api.refiremail.com/emails');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REFIREMAIL_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'from' => 'Nimbu <[email protected]>',
        'to' => ['[email protected]'],
        'subject' => 'Order #1042 is confirmed',
        'html' => '<p>Thanks, Asha. Your order ships tomorrow.</p>',
    ]),
]);

$email = json_decode(curl_exec($ch), true); // ['id' => '…']

Uses PHP’s curl extension, which most hosts enable.

send.shShell

curl -X POST https://api.refiremail.com/emails \
  -H "Authorization: Bearer $REFIREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "from": "Nimbu <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Order #1042 is confirmed",
    "html": "<p>Thanks, Asha. Your order ships tomorrow.</p>"
  }'

The key goes in the Authorization header.

02, Switch

Switching is a config change, not a rewrite.

Keep your request shapes: point your existing integration at api.refiremail.com, swap in a Refiremail key, and redeploy. Your send code, your templates and your webhook handler stay as they are.

Redo once, on our side. Three things belong to your account rather than your code:

Verify your sending domain with us. The DKIM records are new, because the signing key is ours.
Create your webhook endpoints again. Each gets a new signing secret; a Standard Webhooks check keeps working.
Bring your contacts across with a CSV import or the contacts API.

.envDiff

EMAIL_API_URL=<your current provider’s API>

EMAIL_API_URL=https://api.refiremail.com

EMAIL_API_KEY=<your current key>

EMAIL_API_KEY=<your Refiremail key>from the dashboard

Whatever your code calls them, the base URL and the key are the two values that change. Requests keep their shape: POST /emails with from, to, subject and html, and the same idempotency, pagination and error conventions.

03, Endpoints

Every endpoint.

Every route of the API, with its methods and its status.

Endpoint	Methods	Status	Notes
/emails	POST	Live	Send one email
/emails/batch	POST	Live	Up to 100 emails per call
/emails/{id}	GET	Live	One sent email and its latest event
/emails	GET	Live	Sent emails, newest first
/emails/{id}	PATCH	Live	Reschedule a scheduled email
/emails/{id}/cancel	POST	Live	Cancel a scheduled email
/emails/receiving/{id}	GET	Live	One received (inbound) email
/domains	GETPOSTPATCHDELETE	Live	Plus `POST /domains/{id}/verify`
/api-keys	GETPOSTPATCHDELETE	Live	Full-access or sending-only keys
/contacts	GETPOSTPATCHDELETE	Live	Look up by id or by email
/segments	GETPOSTPATCHDELETE	Live	Plus the contacts in a segment
/topics	GETPOSTPATCHDELETE	Live	Subscription preferences
/broadcasts	GETPOSTPATCHDELETE	Live	Plus send and cancel
/templates	GETPOSTPATCHDELETE	Live	Plus publish; send by id or alias
/automations	GETPOSTPATCHDELETE	Coming	Plus runs and stop. Answers 404 “not available yet” until it opens
/webhooks	GETPOSTPATCHDELETE	Live	Plus secret rotation and event replay
/logs	GET	Live	API requests, newest first

Live: built, and covered by passing tests. Coming: not open yet; the API answers it with a 404 that says so.

04, Rules

The rules of the road.

Five things every client of the API should know. Each links to the details.

Authentication
Send Authorization: Bearer <key> on every request. No key is a 401 missing_api_key; a wrong, revoked or expired one is a 403 invalid_api_key.
Error names
Errors
Every error is JSON with statusCode, name and message. Switch on name, which stays stable when the wording changes.
The error table
Rate limits
Counted per team, per second. Every response carries ratelimit-limit, ratelimit-remaining and ratelimit-reset; a 429 adds retry-after.
Limits
Idempotency
Send Idempotency-Key on POST /emails and /emails/batch. Keys are 1–256 characters and kept 24 hours; the same key with a different body is a 409.
How retries stay safe
Pagination
Lists take limit (1–100, default 20) with after or before, never both, and return { object: "list", has_more, data }, newest first.
Limits

05, Beyond REST

The same key does more.

SMTP, inbound mail and webhooks use the same API keys, domains and event model as the REST API.

SMTP relay
For apps that only speak SMTP. The username is refiremail and the password is an API key.
Inbound email
Receive mail at your own domain as parsed JSON, with a webhook when it lands.
Webhooks
Signed events for every send, checked with a few lines of standard-library code.

Your first email is one HTTP call away.

Request early access. Once your account is on, create a key, verify your domain and send.

Request early access See the Email API

Send your first email with one HTTP call.

From a new account to a delivered email.

Switching is a config change, not a rewrite.

Every endpoint.

The rules of the road.

Authentication

Errors

Rate limits

Idempotency

Pagination

The same key does more.

SMTP relay

Inbound email

Webhooks

Your first email is one HTTP call away.