Documentation

Send an email

POST /api/v1/emails/send — queues a message to one or more recipients. The from address must be one of your verified senders.

Several recipients normally share one message, so they can see each other in the To: header. If your body carries an unsubscribe link, we send one message per recipient instead — each with its own working opt-out link and List-Unsubscribe header — and recipients no longer see each other. A link that identifies one person cannot live in a body several people share, which is the whole reason the two differ.

curl -X POST https://api.mailtr.co/api/v1/emails/send \
  -H "Authorization: Bearer mailtr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Jane <jane@yourdomain.com>",
    "to": ["recipient@example.com"],
    "subject": "Welcome to Mailtr",
    "html": "<h1>Hello!</h1><p>Thanks for signing up.</p>",
    "trackOpens": true
  }'

A successful call returns 202 with the queued message id:

{
  "success": true,
  "data": { "id": "0f8a…c21", "status": "queued" },
  "message": "Email queued successfully"
}

Sending with a template

Pass a published templateId instead of html. Any {{variables}} in the template are filled from the variables object. The template's subject is used unless you override it.

Write {{orderId}} anywhere in the template's content or subject, then declare it in the editor's Variables panel — that declaration is what decides how a send behaves when a value is missing:

Links, images, lists and conditions

A variable works in a button's label and link, and in an image's source, alt text and link — use the { } button beside each field. A variable that starts a link is the whole link ({{ctaUrl}}); one inside it is URL-encoded (https://shop.example/o/{{orderId}}). A filled-in link must be http, https, mailto or tel, and an image http or https; anything else is removed. Links stay click-tracked.

Declare a List variable and choose it under a block's Show & repeat settings to repeat that block once per item, up to 100 — inside it, write {{item.name}}. Any block can also be shown only when a value has one, equals something, or is over or under a number. Send a list as a JSON array and an Object as a JSON object; values can be formatted with {{ total | currency: 'USD' }}, {{ name | default: 'there' }} or {{ sentAt | date: '%b %d' }}. Templates use Liquid syntax, and plain {{name}} variables work exactly as before.

{
  "firstName": "Priya",
  "ctaUrl": "https://shop.example/orders/A-1042",
  "order": { "id": "A-1042", "total": 36 },
  "items": [
    { "name": "Mug", "price": 12, "image": "https://cdn.example/mug.png" },
    { "name": "Tea tin", "price": 24, "image": "https://cdn.example/tin.png" }
  ]
}

Editing a published template does not change what your sends use. Your changes are held in a working draft, and the live version keeps going out until you press Publish on the template's card.

curl -X POST https://api.mailtr.co/api/v1/emails/send \
  -H "Authorization: Bearer mailtr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Jane <jane@yourdomain.com>",
    "to": ["recipient@example.com"],
    "templateId": "tpl_aB3xK9mZ",
    "variables": { "firstName": "Sam", "orderId": "1234" }
  }'

SMTP relay

Prefer SMTP? Generate SMTP credentials from Dashboard → SMTP & API and point any mail library at our relay. The exact host and port are shown on that page. SMTP sends share the same quota, logs, and stats as the HTTP API.

import nodemailer from "nodemailer";

const transporter = nodemailer.createTransport({
  host: "send.mailtr.co",
  port: 587,
  secure: false, // STARTTLS on 587; set true for 465
  auth: {
    user: process.env.MAILTR_SMTP_USER,
    pass: process.env.MAILTR_SMTP_PASS,
  },
});

await transporter.sendMail({
  from: '"Jane" <jane@yourdomain.com>',
  to: "recipient@example.com",
  subject: "Welcome to Mailtr",
  html: "<h1>Hello!</h1>",
});

Templates & variables over SMTP

SMTP has no request body to put a templateId in, so both travel as headers. They are the exact counterparts of the API's templateId and variables fields, and the rules in the table above apply identically.

Your mail library may MIME-encode the variables header, since JSON is full of characters headers don't normally carry. That is fine — we decode it either way, so just pass the JSON as-is.

await transporter.sendMail({
  from: '"Jane" <jane@yourdomain.com>',
  to: "recipient@example.com",
  // No html/subject needed — the template supplies both.
  headers: {
    "X-Mailtr-Template-Id": "tpl_aB3xK9mZ",
    "X-Mailtr-Variables": JSON.stringify({
      firstName: "Sam",
      orderId: "1234",
    }),
  },
});

Tracking & bounces

Open and click tracking are opt-in per send (trackOpens / trackClicks), default off. When enabled we modify the sent HTML — a 1×1 pixel for opens, link rewriting for clicks — and surface the results in your Transactional logs and stats.

• Tracking respects recipient consent: if any recipient of a send has opted out of tracking, both trackOpens and trackClicks are disabled for that entire send, even if you set them true.
• Every send is recorded in Transactional → Logs with its delivery status (queued → sent → delivered → opened).
• Hard bounces automatically add the recipient to your suppression list; soft bounces are recorded only.
• Sends to a suppressed address are dropped, and a request whose recipients are all suppressed is rejected with 400.

Errors & limits

Errors return a non-2xx status with a JSON body describing the problem.