Getting Started

Maillayer is a transactional email API built for developers. Send emails with a single REST API call — no SMTP configuration, no complex SDKs.

Base URL

All API requests are made to:

https://maillayer.com

How it works

1. Add and verify your domain — configure DKIM records so your emails are properly authenticated.
2. Create an API key — generate a key from the dashboard to authenticate your requests.
3. Send emails — POST to /api/v1/emails with your payload. Maillayer queues, sends, and tracks delivery.

Authentication

All API requests require a Bearer token in the Authorization header. API keys are created from the Maillayer dashboard.

Header format

Authorization: Bearer ml_live_your_api_key

API key types

Example request

curl https://maillayer.com/api/v1/emails \
  -H "Authorization: Bearer ml_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"from":"[email protected]","to":"[email protected]","subject":"Test","text":"Hello"}'

Send Email

Send a transactional email by making a POST request. Emails are queued and sent asynchronously with automatic retries.

Request body

Example request

curl -X POST https://maillayer.com/api/v1/emails \
  -H "Authorization: Bearer ml_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Order Confirmed",
    "html": "<h1>Thanks for your order!</h1><p>We\'ll ship it soon.</p>",
    "replyTo": "[email protected]",
    "tags": ["order", "transactional"]
  }'

Example with Node.js

const response = await fetch('https://maillayer.com/api/v1/emails', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ml_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Welcome to Acme',
    html: '<p>Thanks for signing up!</p>',
  }),
});

const data = await response.json();
console.log(data.id); // "665f1a2b3c4d5e6f7a8b9c0d"

Response

Returns 202 Accepted when the email is queued for delivery.

{
  "id": "665f1a2b3c4d5e6f7a8b9c0d",
  "status": "queued",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Order Confirmed",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Domains

Before sending emails, you must add and verify at least one domain. Verification configures DKIM signing to authenticate your emails and improve deliverability.

Adding a domain

1. Go to Domains in the Maillayer dashboard.
2. Enter your domain name (e.g. yourdomain.com) and click Add Domain.
3. Maillayer generates 3 CNAME records for DKIM verification.

DNS configuration

Add the provided CNAME records to your domain's DNS settings. The records look like this:

Verification

After adding the DNS records, click Verify in the dashboard. DNS propagation typically takes a few minutes but can take up to 72 hours. Once verified, the domain status changes to verified and you can start sending.

API Keys

API keys authenticate your requests to the Maillayer API. Each key is scoped to your account and can be revoked at any time.

Creating a key

1. Go to API Keys in the dashboard.
2. Click Create API Key.
3. Give the key a name (e.g. "Production" or "Staging").
4. Copy the key immediately — it is only shown once.

Revoking a key

To revoke a key, go to API Keys in the dashboard and click Revoke next to the key. Revoked keys immediately stop working and cannot be restored.

Best practices

• Use separate keys for production and development.
• Store keys in environment variables, never in source code.
• Rotate keys periodically.
• Revoke unused keys immediately.

Webhooks

Maillayer sends webhook events to notify your application about email delivery status changes. Configure a webhook URL in the dashboard to start receiving events.

Event types

Webhook payload

{
  "event": "email.delivered",
  "emailId": "665f1a2b3c4d5e6f7a8b9c0d",
  "to": "[email protected]",
  "from": "[email protected]",
  "subject": "Order Confirmed",
  "timestamp": "2025-01-15T10:30:05.000Z"
}

Bounce event payload

{
  "event": "email.bounced",
  "emailId": "665f1a2b3c4d5e6f7a8b9c0d",
  "to": "[email protected]",
  "bounceType": "Permanent",
  "bounceSubType": "General",
  "timestamp": "2025-01-15T10:30:05.000Z"
}

Error Codes

The API returns standard HTTP status codes. Error responses include a JSON body with a message field describing the issue.

Error response format

{
  "error": "Validation failed",
  "message": "The 'to' field is required."
}

Status codes

Rate Limits

API requests are rate-limited per account based on your plan. Limits are applied per calendar month.

Rate limit headers

Every response includes rate limit information in the headers: