REST API

Send transactional emails via POST /v1/transactional/send. This is the primary way to send email through MailLand.

AuthenticationCopy Anchor Link

Include your API key in the X-API-Key header:

X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...

The credential must have the Api channel enabled and be a Sending product credential.

Send a Single EmailCopy Anchor Link

POST https://api.mail.land/v1/transactional/send

curl -X POST https://api.mail.land/v1/transactional/send \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]"},
    "to": [{"email": "[email protected]"}],
    "subject": "Hello from MailLand",
    "htmlContent": "<p>Your email content here</p>"
  }'

Request BodyCopy Anchor Link

{
  "from": {
    "email": "[email protected]",
    "name": "Your App"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Jane Doe",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345"
      }
    }
  ],
  "subject": "Your order #{{orderNumber}} has shipped",
  "htmlContent": "<h1>Hi {{firstName}},</h1><p>Your order #{{orderNumber}} is on its way.</p>",
  "textContent": "Hi {{firstName}}, Your order #{{orderNumber}} is on its way.",
  "replyTo": "[email protected]",
  "tags": ["order-shipped", "transactional"],
  "customHeaders": {
    "X-Entity-Ref-ID": "order-12345"
  },
  "tracking": {
    "opens": true,
    "clicks": true
  },
  "priority": "High",
  "idempotencyKey": "order-12345-shipped-v1"
}

Field ReferenceCopy Anchor Link

AttachmentsCopy Anchor Link

Each attachment requires three fields:

{
  "attachments": [
    {
      "fileName": "invoice.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJ...",
      "inline": false
    },
    {
      "fileName": "logo.png",
      "contentType": "image/png",
      "content": "iVBORw0KGgoAAAA...",
      "contentId": "company-logo",
      "inline": true
    }
  ]
}

ResponseCopy Anchor Link

Status: 202 Accepted

{
  "success": true,
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "isSandboxed": false
}

Rejected RecipientsCopy Anchor Link

Recipients can be rejected for several reasons:

{
  "success": true,
  "jobId": "...",
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [
    {
      "email": "[email protected]",
      "reason": "Suppressed"
    },
    {
      "email": "[email protected]",
      "reason": "domain_typo",
      "suggestion": "[email protected]"
    }
  ]
}

Common rejection reasons:

• Suppressed: address is on the suppression list (previous bounces/complaints)
• disposable_domain: disposable email provider detected
• domain_typo: likely typo in domain (includes suggestion field)

Pre-flight CheckCopy Anchor Link

Verify your ability to send before making the actual request:

GET https://api.mail.land/v1/transactional/send/check?recipientCount=1

curl https://api.mail.land/v1/transactional/send/check?recipientCount=1 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

{
  "canSend": true,
  "rateLimitStatus": {
    "currentSecond": 2,
    "limitPerSecond": 50,
    "currentHour": 450,
    "limitPerHour": 5000,
    "currentDay": 8200,
    "limitPerDay": 50000
  },
  "monthlyUsed": 125000,
  "monthlyLimit": 500000
}

If canSend is false, the reason field explains why (rate limit, quota, account status, etc).

IdempotencyCopy Anchor Link

Retrying a send after a network timeout must not deliver the email twice. Supply an idempotency key and a retry replays the original response instead of sending again.

Send the key as a header (recommended):

X-Idempotency-Key: order-12345-shipped-v1

Or use the idempotencyKey body field. Both are accepted, and you may send both only if the values are identical.

RulesCopy Anchor Link

• Scope. X-Idempotency-Key is accepted on POST /v1/transactional/send and POST /v1/transactional/send-batch only. No other endpoint reads it.
• Format. 1–255 characters, letters, digits, _ and -. Keys are compared exactly: no trimming, no case folding.
• Window. A key stays replayable for 24 hours. After that the same key is treated as a fresh request.
• Replay. A retry within the window returns the original response verbatim (same IDs, same status) and sends nothing.
• Uniqueness. Keys are unique per account. Reusing one key for a different endpoint is rejected with 409; use a distinct key per operation.

Correlation IDCopy Anchor Link

Track requests across systems by including a correlation ID:

X-Correlation-ID: my-app-order-12345

or

X-Request-ID: my-app-order-12345

The correlation ID appears in logs and the activity stream.

Rate Limit HeadersCopy Anchor Link

Successful responses include per-IP rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295

When rate limited (429) by the send policy engine, a Retry-After header indicates seconds to wait:

Retry-After: 30

A transactional request may name up to 5 recipients, and each one counts against your rate limits. If that is more than your per-second allowance (for example 1 per second on a plan of 60 per minute), the request is accepted when no other request was accepted in the same second; otherwise it gets 429 with Retry-After: 1 and succeeds when retried in the next second, within your per-minute limit. See Rate Limits.

An IP-level 429 also includes X-RateLimit-Reset as an ISO-8601 UTC time.

Error ResponsesCopy Anchor Link

All errors return a JSON body:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "timestamp": "2026-02-17T10:30:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Error CodesCopy Anchor Link

The 429 platform-capacity rows are not caused by your own usage. Nothing was queued, Retry-After says when to retry, and no action is needed on your side; see Error Codes for the exact messages. Marketing-only refusals (MARKETING_NOT_YET_ALLOWED, MARKETING_SUSPENDED, both 403) are listed there too.

Transactional Recipient LimitCopy Anchor Link

Transactional credentials enforce a maximum of 5 recipients per send request. This prevents misuse of transactional streams for bulk sending. If you need more recipients, use a Marketing credential with batch sending.

Using TemplatesCopy Anchor Link

Instead of inline HTML, reference a stored template:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "resetLink": "https://app.example.com/reset?token=abc123"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr",
  "variables": {
    "companyName": "Acme Inc"
  }
}

The subject comes from the template. On a key overlap, the recipient's own to[].variables overrides the global variables: the same rule as inline content. See Templates for creating and managing templates.

Next StepsCopy Anchor Link

• Batch Sending: send to multiple recipients at once
• SMTP Relay: send via SMTP instead of REST
• Templates: create reusable email templates
• Scheduled Emails: schedule emails for future delivery