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.
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" }'{ "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" }'{
"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>"
}'{ "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
Authentication
Authenticate every Irisend API request with a Bearer API key in the Authorization header. Learn the ir_<prefix>_<secret> key format and how keys are hashed.
Idempotency
Send an Idempotency-Key header on POST /emails or /emails/batch to make retries safe. Learn how Irisend deduplicates repeated requests for up to 24 hours.
Pagination
List endpoints that can grow large are cursor-paginated with a limit and an id-based cursor instead of page numbers. Learn how to page Irisend API results.
Errors
Irisend API errors return a JSON body shaped { statusCode, name, message } so you can branch on the error name. See every error name and when it occurs.
Rate limits
Irisend API requests are limited per team in a fixed one-second window shared across every key. Learn the rate-limit headers and how to handle a 429 response.
Trust tiers & sandbox
New Irisend accounts start in a sandbox and earn higher limits from their delivery record. See the four tiers, sandbox rules, and how to move up a tier.
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.
SDKs & tools
Node.js SDK
@irisend/sdk is published on npm with zero runtime dependencies, for Node 22+. Same { data, error } response shape and batch.send alias as Resend's own SDK.
Python SDK
The irisend Python SDK has zero dependencies and supports Python 3.9+. Not yet on PyPI — install straight from the repo until the first tagged release ships.
PHP SDK
irisend/irisend-php requires PHP 8.1+ with ext-curl and ext-json, zero third-party dependencies. Not yet on Packagist — require it as a path repository for now.
CLI
@irisend/cli is a local dev inbox and hot-reloading template preview for the sandbox email provider. Nothing it sends reaches AWS SES. Usage reference.