Documentation

Send your first email, then read the reference.

The Irisend API is a REST API over HTTPS with JSON request and response bodies. All requests are made against https://api.irisend.com.

Set up with AI

Quickstart

Sign up, create an API key, verify a sending domain, then send your first email. Every step below is a real request against the live API.

1. Create an account and an API key

Sign up, then open Configuration → API keys in the dashboard to create your first key — or mint one from the API using a key you already have. Every example on this page reads the key from the IRISEND_API_KEY environment variable, and your language choice sticks across the whole page.

curl -X POST https://api.irisend.com/api-keys \
  -H "Authorization: Bearer $IRISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Local dev" }'
ResponseJSON
{ "id": "3f9c2b1a-...", "object": "api_key", "token": "ir_8fK3mQ1z_9pR2vT6yB4wL0nC7xE1sH5dJ40NlGQ" }

token is only ever returned here — store it now, it can't be retrieved again.

2. Add and verify a sending domain

Creating a domain returns the DKIM, SPF, and (optional) DMARC DNS records to publish. Add them at your DNS provider, then call verify once they've propagated — DNS changes can take a few minutes to a few hours.

curl -X POST https://api.irisend.com/domains \
  -H "Authorization: Bearer $IRISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "yourdomain.com" }'
ResponseJSON
{
  "object": "domain",
  "id": "dom_4kP1qR9zL7vT2yB6wC0nS3x",
  "name": "yourdomain.com",
  "status": "not_started",
  "created_at": "2026-09-25T09:00:12.481Z",
  "region": "eu-west-1",
  "capabilities": { "sending": "enabled", "receiving": "disabled" },
  "records": [
    { "record": "DKIM", "type": "TXT", "name": "irisend._domainkey", "value": "p=MIGfMA0GCSq...", "ttl": "Auto", "status": "not_started", "required": true },
    { "record": "SPF", "type": "MX", "name": "send", "value": "feedback-smtp.eu-west-1.amazonses.com", "priority": 10, "ttl": "Auto", "status": "not_started", "required": true },
    { "record": "SPF", "type": "TXT", "name": "send", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "not_started", "required": true },
    { "record": "DMARC", "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "not_started", "required": false }
  ],
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "reputation_status": "ok",
  "bimi_logo_url": null,
  "bimi_vmc_url": null
}
curl -X POST https://api.irisend.com/domains/dom_4kP1qR9zL7vT2yB6wC0nS3x/verify \
  -H "Authorization: Bearer $IRISEND_API_KEY"

You can also just poll GET /domains/:id — SES resolves records on its own schedule, and calling verify re-checks them immediately. Once a domain is verified, its health score tells you if bounce/complaint reputation or DNS drift later put it at risk.

3. Send your first email

curl -X POST https://api.irisend.com/emails \
  -H "Authorization: Bearer $IRISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Hello from Irisend",
    "html": "<strong>It just works.</strong>"
  }'
ResponseJSON
{ "id": "em_9f2K3mQ1zPr7vT6yB4wL0nC" }

4. Check its status any time

curl https://api.irisend.com/emails/em_9f2K3mQ1zPr7vT6yB4wL0nC \
  -H "Authorization: Bearer $IRISEND_API_KEY"

Prefer a typed client? @irisend/sdk (Node.js) is on npm today; Python and PHP SDKs exist and work, just not published to a registry yet. The examples on this page use each language's standard HTTP client so they work with zero extra packages — see SDKs & tools for the typed clients.

Explore the docs

Every endpoint, SDK, and integration guide, one topic per page.

Get started

API reference

Emails

Send, schedule, cancel, patch, batch-send, and list transactional emails with the Irisend REST API. Reference for every /emails endpoint with request/response.

Templates

Create reusable HTML/text email templates with named variables and Resend-style triple-brace substitution. Every create or update appends an immutable version.

Broadcasts

Send one-off or scheduled broadcasts to every contact in an audience, optionally filtered to a topic's subscribers. /broadcasts API reference with examples.

SMTP

Already sending through SMTP? Point your existing Nodemailer, Postfix, or mail library config at smtp.irisend.com instead of rewriting it for the REST API.

Domains

Add, verify, and monitor sending domains: DKIM/SPF/DMARC records, domain health scoring, and DMARC aggregate-report summaries. Full /domains API reference.

Receiving

Receive inbound email on a verified domain: add one MX record, enable receiving, and fetch HTML, attachments, and raw downloads via the Receiving API.

Audiences & contacts

An audience is a list of contacts you send broadcasts to, with contacts nested under the audience that owns them. Full /audiences and /contacts API reference.

Topics

A topic is an opt-in/opt-out category a broadcast can target, so contacts unsubscribe from one topic without losing every other subscription. /topics reference.

Consents

An append-only evidence ledger for marketing consent: record what a contact agreed to, when, and under what legal basis, so you can prove it later on.

Sub-accounts

Irisend-only: a parent team can create isolated sub-accounts with their own domains, quotas, and suspension state, one level deep. Full /accounts API reference.

Suppressions

Manage the list of addresses Irisend will never send to again — every suppressed address is dropped from to/cc/bcc automatically. /suppressions API reference.

Logs

Every authenticated Irisend API request your team makes is recorded for the dashboard's Logs page and readable from the API, with secrets always redacted.

API keys

Create, list, and revoke Irisend API keys scoped to full access, sending-only access, or a single domain. /api-keys endpoint reference with request examples.

API key security

Protect Irisend API keys: the checksummed key format, automatic revocation of keys leaked on GitHub, a per-key IP allowlist, daily send caps and new-network alerts.

Webhooks

Subscribe to delivery, bounce, complaint, and other email lifecycle events over HTTP with signed, Standard Webhooks-compatible payloads. API reference.

MCP server

Irisend's REST API is also exposed as a remote MCP server at /mcp, so a coding agent can send mail, check on it, and diagnose a bounce without glue code.