─── documentation v1.0

Mail-Reacher API documentation

Send transactional emails through one stable API, route them through the right provider, render MJML templates, track opens and clicks, and audit deliverability with Mail-Check.

Quickstart

Use an environment-scoped API key, call POST /api/emails/send, and let Mail-Reacher route the message through the provider configured for that environment.

curl https://mail-reacher.com/api/emails/send \
  -H "Authorization: Bearer mr_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "email": "user@example.com", "name": "Marie" }],
    "from_email": "noreply@your-domain.com",
    "from_name": "Your App",
    "reply_to": "support@your-domain.com",
    "subject": "Welcome to the app",
    "html": "<p>Hello Marie</p>",
    "text": "Hello Marie",
    "metadata": { "source": "website" }
  }'

Concepts

Projects

Group domains, environments, senders, templates and logs around a product or workspace.

Environments

Test keys simulate sends inside the internal inbox. Live keys deliver through the configured provider.

Senders

A sender stores provider credentials, default From identity and deliverability settings.

Authentication

Every API request uses a Bearer token. Keys are scoped by environment and permissions, so a staging key cannot accidentally send real email.

Authorization: Bearer YOUR_API_KEY

Send an email

The send endpoint accepts either a template ID or inline HTML. Template defaults can provide the subject and sender when appropriate.

Field	Type	Required	Description
to	string\|Recipient[]	yes	recipient(s) — email string or array of { email, name? }
from_email	string	yes*	sender email — default can come from the configured sender
from_name	string	no	sender display name
subject	string	yes*	subject — default can come from the template
template_id	integer	no	template ID to render
html	string	no	inline HTML when no template is used
text	string	no	plain-text body
cc / bcc	string[]\|Recipient[]	no	copy and blind-copy recipients
variables	object	no	variables injected into the template
reply_to	string	no	reply-to address
metadata	object	no	arbitrary data returned in webhooks
tags	string[]	no	tags used by unsubscribe rules

MJML templates

Create responsive MJML templates, preview them in the dashboard, and inject variables at send time.

<mj-text>
  Hello {{ first_name }},
  your account is ready to <a href="{{ activation_link }}">activate</a>.
</mj-text>

Tracking & events

Mail-Reacher injects its own open pixel and rewrites links so opens and clicks remain consistent even when you switch providers.

{
  "event": "opened",
  "message_id": "msg_01HX9Z...",
  "provider": "aws-ses",
  "to": "user@example.com",
  "from": "noreply@your-domain.com",
  "occurred_at": "2026-05-02T10:14:32Z",
  "metadata": {
    "campaign": "onboarding",
    "user_id": 1234
  }
}

Mail-Check

Mail-Check audits SPF, DKIM, DMARC, reverse DNS, blacklists, headers, content, TLS, MX and IP signals, then returns a readable score out of 10.

Supported providers

AWS SES

Recommended for high volume. Low cost, Amazon infrastructure, shared or dedicated IP pools.

Postmark

Excellent transactional deliverability, strict stream separation, high-quality dashboard.

Mailgun

Mature API, email validation options, solid EU/US coverage.

SendGrid

Widely used in SaaS, marketing + transactional use cases, rich stats.

Custom SMTP

Any SMTP server — your own infrastructure, an unlisted provider, or a local service.

SDKs & packages

Use the official packages when you want typed helpers instead of calling the REST API directly. Keep MAILREACHER_API_KEY server-side only: it selects the Mail Reacher environment and therefore the configured provider or simulation mode.

JavaScript / TypeScript

Install the core SDK, or add a framework adapter for existing Next.js, Nodemailer or TanStack Start code.

yarn add @mail-reacher/sdk
yarn add @mail-reacher/next
yarn add @mail-reacher/nodemailer
yarn add @mail-reacher/tanstack-start

PHP / Laravel

Use the framework-agnostic PHP SDK, or the Laravel transport when existing Mail::to(), notifications and mailables should keep working without rewrites.

composer require codiblenet/mail-reacher-php
composer require codiblenet/laravel-mail-reacher

Laravel configuration stays intentionally small: set MAIL_MAILER=mailreacher and MAILREACHER_API_KEY=YOUR_API_KEY. The API endpoint is fixed to mail-reacher.com.

Error codes

400Validation — a required field is missing or malformed

401API key missing, expired, or invalid

403The key does not have the required scope

404Resource not found (template, contact…)

422Logical conflict (for example an inactive template)

429Rate limit exceeded

500Mail-Reacher server error — retry later

502Provider-side error — Mail-Reacher retries automatically

Rate limits

Rate limits are plan- and usage-dependent. Provider errors are normalized and retried when safe. If you need higher throughput, open an in-app support ticket.

Ready to wire your first send?

Create a project, configure a sender, then test safely with a test key before switching to live.

Start free →