Send API

Every snippet above is the official client library — same shape in Node, Python, PHP, Java, Go, and Ruby — or raw curl.

Templates

A message body can come from three places, all interchangeable with plain html/text. Only the first is part of the API — the other two are conveniences the client libraries resolve before the request goes out, so the wire always carries html/text.

A saved template, by id

Pass templateId — a template you saved (tpl_…) or one of the base templates (base_…). It seeds the subject, HTML and text; an explicit subject/html/text on the request overrides it. {{merge_tags}} are substituted server-side from templateData, with HTML values auto-escaped.

{
  "from": "hello@myapp.ai",
  "to": "ada@example.com",
  "templateId": "tpl_a878c1",
  "templateData": { "name": "Ada", "invoice": "1042" }
}

A React component

The Node library takes a react element and renders it to HTML in your process, exactly like a html string you built yourself. It needs the optional peer dependency @react-email/render (or @react-email/components) — install it to use this; the SDK itself stays dependency-free.

import { MailKite } from "mailkite";
import { Welcome } from "./emails/welcome";

const mk = new MailKite(process.env.MAILKITE_API_KEY);

await mk.send({
  from: "hello@myapp.ai",
  to: "ada@example.com",
  subject: "Welcome aboard",
  react: <Welcome name="Ada" />,
});

The plaintext part is derived from the same component automatically, so a React email still goes out as a proper multipart message — no second copy of the body to keep in sync. Pass text yourself to override it.

createTemplate({ react: <Welcome /> }) stores the rendered result as a MailKite template, turning a component into a tpl_… id the dashboard, sequences, broadcasts and every other MailKite library can send.

A local file

Keep templates next to your code: templateFile reads a local .html, .htm or .txt file. A welcome.txt sitting beside welcome.html becomes the plaintext part. Available in Node, Python and PHP.

await mk.send({
  from: "hello@myapp.ai",
  to: "ada@example.com",
  subject: "Welcome aboard",
  templateFile: "./emails/welcome.html",  // welcome.txt beside it → the text part
  templateData: { name: "Ada" },
});

{{merge_tags}} left in a rendered component or a file are still filled from templateData by the API, exactly as they are in a saved template — so per-recipient values keep working however the body was authored. Because react and templateFile produce the body locally, neither can be combined with templateId.

Batch send

POST /v1/send/batch sends one personalized message per recipient (up to 50) in a single call. Shared fields form the base message; each recipients[] entry gets its own message to exactly one address, with its templateData and headers merged over the shared ones (per-recipient wins). Recipients never see each other.

{
  "from": "billing@myapp.ai",
  "subject": "Your {{plan}} invoice",
  "html": "<p>Hi {{name}}, your {{plan}} invoice is ready.</p>",
  "templateData": { "plan": "Pro" },
  "recipients": [
    { "to": "Ada Lovelace <ada@example.com>", "templateData": { "name": "Ada" } },
    { "to": "grace@example.com", "templateData": { "name": "Grace", "plan": "Team" } }
  ]
}

← 200 OK
{
  "results": [
    { "to": "Ada Lovelace <ada@example.com>", "id": "msg_2Hk9…", "status": "sent" },
    { "to": "grace@example.com", "id": "msg_8Rw2…", "status": "sent" }
  ],
  "sent": 2, "scheduled": 0, "failed": 0
}

Every message passes the same gates as a single send and gets its own id, so a batch can partially succeed — check each result's status (sent · scheduled · failed). Results come back in request order. Pass scheduledAt to park the whole batch: each recipient gets its own cancelable ssnd_… scheduled send.

Batch request fields

{
  "from": "support@myapp.ai",
  "to": "ada@example.com",
  "subject": "Re: invoice #1042",
  "text": "Approved — thanks!",
  "inReplyTo": "<a1b2c3@mail.example.com>"
}