API Reference

Send transactional emails programmatically. API endpoints, authentication, request/response formats, and code examples.

Send transactional emails programmatically with Transmit's REST API.

Authentication

Generate an API key from Settings → API Keys in your dashboard.

Click Create API Key
Copy your key (starts with pm_live_ for production)

Never expose API keys in client-side code or public repositories.

Send Email

POST https://api.xmit.sh/email/send
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`to`	string or array	Yes	Recipient email(s)
`subject`	string	Yes	Email subject line
`from`	string	*	Sender email address
`senderId`	string	*	Pre-configured sender ID
`html`	string	**	HTML body content
`templateId`	string	**	Use a saved template
`text`	string	No	Plain text fallback
`fromName`	string	No	Display name for sender
`replyTo`	string	No	Reply-to address
`cc`	string or array	No	Carbon copy recipients
`bcc`	string or array	No	Blind carbon copy recipients
`variables`	object	No	Template variables
`attachments`	array	No	File attachments (base64-encoded, see below)
`metadata`	object	No	Custom data returned in webhooks
`headers`	object	No	Custom email headers
`inReplyTo`	string	No	Message-ID for threading
`references`	string	No	Message-ID chain for threading

* Either from or senderId is required ** Either html or templateId is required

Example Request

curl -X POST https://api.xmit.sh/email/send \
  -H "Authorization: Bearer pm_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "hello@yourapp.com",
    "subject": "Welcome to YourApp",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
  }'

Using a Template

curl -X POST https://api.xmit.sh/email/send \
  -H "Authorization: Bearer pm_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "senderId": "snd_xxxxx",
    "subject": "Your order has shipped",
    "templateId": "tmpl_xxxxx",
    "variables": {
      "firstName": "John",
      "orderId": "ORD-12345"
    }
  }'

With Attachments

Each attachment object has three fields:

Field	Type	Required	Description
`filename`	string	Yes	File name shown to recipient
`content`	string	Yes	File contents, base64-encoded
`contentType`	string	No	MIME type (e.g., `application/pdf`, `image/png`)

curl -X POST https://api.xmit.sh/email/send \
  -H "Authorization: Bearer pm_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "hello@yourapp.com",
    "subject": "Your invoice",
    "html": "<p>Please find your invoice attached.</p>",
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjQKMS...",
        "contentType": "application/pdf"
      }
    ]
  }'

To base64-encode a file:

# macOS / Linux
base64 -i invoice.pdf | tr -d '\n'

# Node.js
fs.readFileSync("invoice.pdf").toString("base64")

# Python
import base64; base64.b64encode(open("invoice.pdf", "rb").read()).decode()

Response

Success (200):

{
  "success": true,
  "messageId": "msg_1a2b3c4d5e6f"
}

Error (4xx):

{
  "error": "Recipient (to) is required"
}

Limits

Limit	Value
Recipients per request	50 (to + cc + bcc combined)
Per attachment	5 MB (decoded size)
Total attachments	7 MB (decoded size)

Error Codes

Status	Meaning
200	Success
400	Validation error (missing/invalid fields)
401	Invalid or missing API key
403	Limit exceeded or feature not available
404	Resource not found (sender, template)

Templates — Create reusable email templates
Webhooks — Track delivery and engagement
Senders — Manage sender identities

API Reference

On this page