Developers

Send mail API

Send transactional email from your backend with API keys. Step-by-step setup, request format, and response codes.

Before your first request

Create an account and subscribe to Cloud Starter or above.
Add your domain, verify DNS, and create a mailbox to send from.
Sign in and open Workspace → API keys. Create a key — the token is shown once.
Use the token as a Bearer credential on every send request.

Send mail from the mailbox linked to your API key. Authenticate with Authorization: Bearer xmc_live_…. Keys are created in your workspace.

Send a message

POST /api/v1/messages

curl -X POST https://xmailcloud.com/api/v1/messages \
  -H "Authorization: Bearer xmc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome to your account",
    "text": "Thanks for signing up.",
    "html": "<p>Thanks for signing up.</p>"
  }'

// 202 Accepted
{
  "ok": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "smtpMessageId": "<xmc.550e8400@xmailcloud.local>",
  "postfixQueueId": "4bWnHY1QHZz5Q"
}

Required: to, subject, and either text or html. Optional: cc, bcc, replyTo.

Response codes

202 — message accepted for delivery
400 — invalid recipient or missing fields
401 — missing or invalid API key
403 — subscription not active
429 — rate limit exceeded

Track delivery

Save the messageId from the response. It matches the X-XMailCloud-Message-Id header on the outgoing message and appears in webhook payloads on Business+ plans.

Delivery webhook documentation

Prefer SMTP?

Any plan with mailboxes can send via SMTP using credentials from Workspace → Mail setup. Host: mail.xmailcloud.com, port 587.