Documentation

API Documentation

Authenticate with API keys and send transactional email through POST /api/v1/message.

Quick start

  1. Verify your sending domain in the control panel.
  2. Create an API key scoped to that domain.
  3. Call POST /api/v1/message with a Bearer token.

Authentication

Include your API key in the Authorization header on every request.

Authorization: Bearer ms_live_…

POST /api/v1/message

Send JSON with a sender, recipients, and either HTML or text content. Requests must include application/json.

curl -X POST https://mailsurge.dev/api/v1/message \
  -H "Authorization: Bearer ms_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <noreply@yourdomain.com>",
    "to": "user@example.com",
    "subject": "Welcome",
    "html": "<p>Hello!</p>"
  }'

Request body

  • from (string, required): Sender address, e.g. Sender Name <no-reply@yourdomain.com>.
  • to (string|array, required): Recipient email or array of emails.
  • subject (string, required): Message subject line.
  • html (string, optional): HTML body.
  • text (string, optional): Plain text body.
  • cc (string|array, optional)
  • bcc (string|array, optional)
  • reply_to (string|array, optional)
  • headers (object, optional): Custom headers, e.g. {"X-Campaign": "welcome"}.
  • attachments (array, optional): filename, content (base64 or raw text), content_type, disposition, content_id.

Responses

  • 201 Created on success with an empty body (message is queued for delivery).
  • 401 Unauthorized with {"reason": "Invalid key"}.
  • 403 Forbidden when the account is blocked or pending approval.
  • 400 Bad Request when the from domain is invalid or not verified.
  • 413 Payload Too Large when attachments exceed 20MB or the queue payload exceeds 1MB.
  • 422 Unprocessable Entity with validation errors for invalid input.
  • 429 Too Many Requests when the request rate exceeds 10/s per API key or 60/min per IP, or when new account sending limits are reached.

Notes

  • Recipient fields accept a single email string or an array of emails.
  • Provide at least one of html or text.
  • Verify your sender domain before sending production traffic.
  • Rate limits: 10 requests per second per API key and 60 requests per minute per IP.
  • For inline images, set disposition to inline, provide a content_id, and reference it as <img src="cid:your-content-id">.