MailAnvil Docs

Everything you need to integrate MailAnvil — send transactional emails, manage domains, create templates, and hook in your AI agent via MCP.

On this page

Quickstart (EN) Panduan Cepat (ID) API Reference MCP Setup Domain Verification
1

Quickstart

EN

Send your first email with MailAnvil in under 5 minutes. You'll need a domain you control and access to its DNS settings.

  1. Sign up for MailAnvil

    Go to mailanvil.com and create an account. You'll start on the Free plan — 500 emails/month, no credit card required.

  2. Add and verify a domain

    Navigate to Domains in your dashboard and add a domain you own (e.g. yourdomain.com). MailAnvil will give you 3 DKIM CNAME records to add to your DNS provider. Once added, click Verify. Domain verification is required before you can send — MailAnvil never sends from unverified domains.

    ℹ

    Using Cloudflare for DNS? We can auto-create your DKIM, SPF, and DMARC records — no manual DNS wrangling needed.

    See the Domain Verification section below for the full list of DNS records you'll need.

  3. Create an API key

    In your dashboard, go to API Keys and generate a new key. Save it somewhere secure — you won't be able to see it again. MailAnvil stores only a SHA-256 hash of your key.

  4. Send your first email

    Use curl to send a test email:

    # Replace with your API key and verified domain curl -X POST https://api.mailanvil.com/v1/send \ -H "Authorization: Bearer re_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "from": "hello@yourdomain.com", "to": ["you@example.com"], "subject": "Hello from MailAnvil!", "text": "This is my first email via MailAnvil 🎉" }'

    If everything is set up correctly, you'll receive a 202 Accepted response with an email ID you can use to track delivery.

2

Panduan Cepat

ID

Kirim email pertama Anda dengan MailAnvil dalam waktu kurang dari 5 menit. Anda memerlukan domain yang Anda kuasai dan akses ke pengaturan DNS-nya.

  1. Daftar akun MailAnvil

    Kunjungi mailanvil.com dan buat akun. Anda akan memulai dengan paket Free — 500 email/bulan, tanpa perlu kartu kredit.

  2. Tambahkan dan verifikasi domain

    Buka menu Domains di dashboard dan tambahkan domain yang Anda miliki (contoh: domainanda.com). MailAnvil akan memberikan 3 catatan CNAME DKIM untuk ditambahkan ke penyedia DNS Anda. Setelah ditambahkan, klik Verify. Verifikasi domain wajib dilakukan sebelum Anda dapat mengirim — MailAnvil tidak pernah mengirim dari domain yang belum diverifikasi.

    ℹ

    Menggunakan Cloudflare untuk DNS? Kami dapat membuat catatan DKIM, SPF, dan DMARC secara otomatis — tidak perlu repot mengatur DNS manual.

    Lihat bagian Domain Verification di bawah untuk daftar lengkap catatan DNS yang diperlukan.

  3. Buat API key

    Di dashboard, buka API Keys dan buat kunci baru. Simpan di tempat yang aman — Anda tidak akan bisa melihatnya lagi. MailAnvil hanya menyimpan hash SHA-256 dari kunci Anda.

  4. Kirim email pertama Anda

    Gunakan curl untuk mengirim email uji coba:

    # Ganti dengan API key dan domain terverifikasi Anda curl -X POST https://api.mailanvil.com/v1/send \ -H "Authorization: Bearer re_api_key_anda" \ -H "Content-Type: application/json" \ -d '{ "from": "halo@domainanda.com", "to": ["anda@example.com"], "subject": "Halo dari MailAnvil!", "text": "Ini email pertama saya melalui MailAnvil 🎉" }'

    Jika semuanya sudah diatur dengan benar, Anda akan menerima respons 202 Accepted dengan ID email yang dapat digunakan untuk melacak pengiriman.

3

API Reference

REST

Base URL: https://api.mailanvil.com. All requests require authentication via Bearer token in the Authorization header. Responses are JSON.

⚠

Idempotency: Send a unique Idempotency-Key header with POST requests to prevent duplicate sends on retry.

Endpoints

Method Path Description
POST /v1/send Send an email. Returns 202 with { "id", "state" }.
GET /v1/emails/:id Get email status and delivery details.
POST /v1/domains Register a new sending domain.
GET /v1/domains List all domains for your account.
GET /v1/domains/:id Get a single domain's verification status and DNS records.
POST /v1/domains/:id/verify Trigger DNS verification check for a domain.
POST /v1/templates Create an email template.
GET /v1/templates List templates.
GET /v1/templates/:id Get template by ID.
PUT /v1/templates/:id Update a template.
DELETE /v1/templates/:id Delete a template.
POST /v1/webhooks Create a webhook endpoint.
GET /v1/webhooks List webhooks.
GET /v1/webhooks/:id Get webhook by ID.
PUT /v1/webhooks/:id Update a webhook.
DELETE /v1/webhooks/:id Delete a webhook.
GET /v1/account Get account details and usage stats.

Send Request Format

// POST /v1/send — request body { "from": "sender@verified.domain", // Required: verified sending domain "to": ["user@example.com"], // Required: array of recipients "subject": "Your Booking Confirmed!", // Required "text": "Plain text body", // Optional (required if html absent) "html": "<h1>HTML body</h1>", // Optional (required if text absent) "reply_to": "support@verified.domain", // Optional "headers": { "X-Custom": "value" }, // Optional: custom headers "template_id": "tpl_...", // Optional: render from template "template_data": { "name": "Budi" } // Optional: template variables }
// Response — 202 Accepted { "id": "em_01J...", "state": "queued" } // Response — 200 OK (GET /v1/emails/:id) { "id": "em_01J...", "state": "delivered", // queued | delivered | bounced | suppressed | failed "from": "sender@verified.domain", "to": ["user@example.com"], "subject": "Your Booking Confirmed!", "created_at": "2026-07-07T12:00:00Z", "sent_at": "2026-07-07T12:00:01Z" }

Error Format

All errors follow a consistent JSON structure:

{ "error": { "code": "validation_error", "message": "Human-readable description" } }

Error codes returned by the API:

Code HTTP Status Description
invalid_api_key 401 The API key is missing, malformed, or invalid.
domain_not_verified 403 The sender domain hasn't been verified via DNS.
sending_paused 403 Sending is paused for your account (check dashboard).
recipient_suppressed 403 The recipient is on the global suppression list.
rate_limited 429 Too many requests. Retry after the indicated delay.
validation_error 422 Request body failed schema validation.
not_found 404 The requested resource doesn't exist.

Common Headers

Header Required Description
Authorization Yes Bearer re_... — your API key
Content-Type Yes application/json
Idempotency-Key Recommended Unique string — prevents duplicate sends on network retry
4

MCP Setup

AI

MailAnvil ships a full Model Context Protocol (MCP) server with Streamable HTTP transport. Your AI agent discovers the tools automatically — no SDK install needed.

Configuration

Add the following entry to your mcp.json (Claude Code, Cursor, or any MCP-compatible client):

{ "mcpServers": { "mailanvil": { "url": "https://mcp.mailanvil.com/mcp", "headers": { "Authorization": "Bearer re_..." } } } }

That's it. Restart your MCP client and the tools will be available immediately.

Available Tools

Tool Description Arguments
send_email Send a transactional email from, to[], subject, html/text
get_email_logs Retrieve recent email logs and delivery status limit, offset
list_domains List all verified and pending domains none
list_templates List email templates none
get_usage_stats Get current billing period usage none

Example: Send a booking confirmation from Claude Code

Once MCP is configured, just ask Claude Code in natural language:

💬

"Send a booking confirmation email to budi@example.com for his Dieng Volcano trip tomorrow morning."

Claude Code calls send_email with the right parameters automatically, using your verified domain and MailAnvil's API:

// What Claude Code sends under the hood send_email({ from: "booking@yourdomain.com", to: ["budi@example.com"], subject: "Booking Confirmed — Dieng Volcano Trip", html: "<h1>Terima kasih, Budi!</h1><p>Your trip departs tomorrow at 6 AM.</p>" })
5

Domain Verification

DNS

Before you can send email through MailAnvil, you must verify ownership of your sending domain by adding specific DNS records. This protects your sender reputation and ensures deliverability.

⚠

MailAnvil never sends from unverified domains. If you attempt to send from an unverified domain, the API returns a domain_not_verified error.

After adding your domain in the MailAnvil dashboard, you'll receive the following DNS records to configure. The exact values (especially DKIM tokens) are generated per-domain and shown in your dashboard.

DKIM Record 1 CNAME

ses1._domainkey.yourdomain.com CNAME dkim1.mailanvil.com
Primary DKIM signing key. MailAnvil generates unique selector tokens per domain.

DKIM Record 2 CNAME

ses2._domainkey.yourdomain.com CNAME dkim2.mailanvil.com
Secondary DKIM key for key rotation without interruption.

DKIM Record 3 CNAME

ses3._domainkey.yourdomain.com CNAME dkim3.mailanvil.com
Tertiary DKIM key (used by AWS SES for automatic signing).

SPF Record TXT

yourdomain.com TXT "v=spf1 include:amazonses.com ~all"
Authorizes AWS SES to send on behalf of your domain. The ~all soft-fail is recommended — hard-fail (-all) may cause legitimate email to bounce.

DMARC Record TXT

_dmarc.yourdomain.com TXT "v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc@yourdomain.com"
DMARC policy tells receiving mail servers what to do if DKIM/SPF checks fail. Start with p=none to monitor, then move to p=quarantine once deliverability is proven.

Verification Steps

  1. Add your domain

    In the MailAnvil dashboard, navigate to Domains and click Add Domain. Enter your domain name (e.g. yourdomain.com).

  2. Copy DNS records

    MailAnvil generates the 3 DKIM CNAME records specific to your domain. Copy each one along with the SPF and DMARC records shown above.

  3. Add records to your DNS provider

    Log into your DNS provider (Cloudflare, Namecheap, AWS Route53, etc.) and add each record. CNAME records go in the DNS zone for your domain. Some providers require the hostname without the domain suffix — check their docs.

  4. Wait for propagation

    DNS changes can take a few minutes to several hours to propagate. Most providers update within 5–10 minutes.

  5. Click Verify

    Back in the MailAnvil dashboard, click Verify. MailAnvil checks that all records resolve correctly. If everything checks out, your domain status changes to Verified and you can start sending immediately.

💡

Using Cloudflare? MailAnvil can auto-create all required DNS records via the Cloudflare API. Just connect your Cloudflare account and we'll handle the rest.