Thanks for your order, {{name|there}}!
", text: "Thanks for your order!", // optional plain-text alternative replyTo: "support@yourdomain.com", // optional unsubscribeTemplate: "minimal", // "none" | "minimal" | "branded" | "card" attachments: [ // optional { filename: "receipt.pdf", content: "Hi {{name|there}}
", }), }); const json = await res.json(); if (!res.ok) throw new Error(json.error?.message); // { error: { message, code } } console.log(json.id); ``` ### Example — create a contact ```ts await fetch("https://mailer123.com/api/v1/contacts", { method: "POST", headers: { Authorization: `Bearer ${process.env.MAILER123_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ email: "jane@example.com", name: "Jane", custom_fields: { company: "Acme", plan: "pro" }, }), }); ``` --- ## 4. Framework patterns (copy‑paste) ### Next.js (App Router) — route handler ```ts // app/api/send/route.ts — runs on the SERVER only import { Mailer123 } from "mailer123"; const mailer = new Mailer123(); // reads MAILER123_API_KEY export async function POST(request: Request) { const { to, subject, html } = await request.json(); const { data, error } = await mailer.emails.send({ from: "you@yourdomain.com", to, subject, html, }); if (error) { return Response.json({ error: error.message }, { status: error.status || 502 }); } return Response.json({ id: data.id }, { status: 202 }); } ``` ### Next.js — server action ```ts "use server"; import { Mailer123 } from "mailer123"; const mailer = new Mailer123(); export async function sendWelcome(email: string) { const { error } = await mailer.emails.send({ from: "you@yourdomain.com", to: email, subject: "Welcome!", html: "Glad you're here, {{name|there}}.
", }); if (error) throw new Error(error.message); } ``` ### Express / Node backend ```ts import express from "express"; import { Mailer123 } from "mailer123"; const mailer = new Mailer123(); const app = express(); app.use(express.json()); app.post("/api/send", async (req, res) => { const { data, error } = await mailer.emails.send({ from: "you@yourdomain.com", to: req.body.to, subject: req.body.subject, html: req.body.html, }); if (error) return res.status(error.status || 502).json({ error: error.message }); res.status(202).json({ id: data.id }); }); ``` ### React (frontend) — call your backend, NOT mailer123 ```tsx // The browser never sees the API key. It calls YOUR endpoint (above). async function handleSubmit(email: string) { const res = await fetch("/api/send", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ to: email, subject: "Hi", html: "Hello
" }), }); if (!res.ok) { const { error } = await res.json(); // show error to the user } } ``` > If you ever feel tempted to call `mailer123` directly from a React component or > put the key in `NEXT_PUBLIC_*`, **stop** — that leaks the key to every visitor. > Always proxy through a server route. --- ## 5. Personalization (merge variables) Subjects and HTML bodies support `{{...}}` tokens, filled per recipient at send time: - `{{name}}` — the contact's name (resolved from the matching contact) - `{{email}}` — the recipient address - `{{unsubscribe_url}}` — a working one‑click unsubscribe link - `{{your_custom_field}}` — any custom field key on the contact - `{{name|fallback}}` — supply a default after `|` for when the value is empty Unknown tokens render empty. To make `{{name}}`/custom fields resolve, the recipient should exist as a contact (create them via `/v1/contacts`). --- ## 6. Errors, limits & reliability ### Result / error shape SDK calls resolve to `{ data, error }`; the REST API returns `{ "error": { "message", "code" } }` with an HTTP status. Branch on `code`: | `code` | Meaning | What to do | | --- | --- | --- | | `unauthorized` | Missing/invalid/revoked key | check `MAILER123_API_KEY` | | `insufficient_scope` | `sending` key on a `full` endpoint | use a full‑scope key | | `forbidden` | Sender not verified / domain send‑blocked | use a verified `from` | | `validation_error` | Bad request body | fix the field named in `message` | | `quota_exceeded` | Daily/monthly send cap hit | back off; raise plan | | `rate_limit_exceeded` | >~10 req/s for the key | retry after `Retry-After` | | `conflict` | Recipient suppressed / duplicate | don't re‑send; remove from list | | `not_found` | Unknown id | re‑list to get a valid id | | `send_failed` / `internal_error` | Provider/server error | retry with backoff | | `network_error` *(SDK only)* | Request never reached the API | retry with backoff | ### Limits - **Rate limit:** ~10 requests/second per key. On `429`, honor the `Retry-After` header and retry with exponential backoff. Don't fan out unbounded loops. - **Send quota:** each plan has daily and monthly caps, counted **per recipient**. A `quota_exceeded` error means you've hit it. - **Suppression:** addresses that bounced, complained, or unsubscribed are rejected automatically. Never try to work around it. - **Verified senders:** `from` must be on a verified domain, or omit it for the project default. ### Reliability tips - Sends are **synchronous** and return a message id — log it for support. - The same email sent twice = two emails; if you need idempotency, dedupe on your side (e.g. a per‑event key before calling send). - Put bulk sends behind your own job/queue, and respect the rate limit. --- ## 7. MCP — let an AI operate the product If the goal isn't app code but having an AI assistant **drive** mailer123 (send mail, manage contacts/campaigns/templates, read analytics in natural language), connect it to the **MCP server** instead: - Endpoint: `https://mailer123.com/api/mcp` (streamable HTTP). - Auth: the same `Bearer m123_…` key. `sending` keys get the email tools; `full` keys get everything. - Tools (by area): **projects** (`list_projects`), **domains** (`list_domains`, `get_domain` — read-only), **email** (`send_email`, `send_test_email`), **contacts**, **groups**, **templates**, **campaigns** (create/send/schedule/…), **analytics** (`get_metrics`), and `read_docs`. - Projects: every tool (except `list_projects`/`read_docs`) takes an optional `project_id`. Omit it when the key covers a single project; when it covers several, call `list_projects` and pass the chosen `id`. - Setup per client and the full tool reference: see the MCP docs at `https://mailer123.com/docs/mcp`. A connected assistant can also call `read_docs` for live guidance. --- ## 8. Checklist for the agent When wiring mailer123 into a user's app, make sure you: - [ ] Put the key in a **server‑side env var**; never expose it to the client. - [ ] Call the SDK/REST from a **backend route/action**, not the browser. - [ ] Use a **verified `from`** (or omit it). - [ ] **Check `error`** on every call and surface a useful message. - [ ] Add **retry/backoff** for `rate_limit_exceeded` / `network_error`. - [ ] Include an `{{unsubscribe_url}}` (or an unsubscribe footer) in marketing mail. - [ ] Use the narrowest **scope** (`sending` vs `full`) the app needs. --- Full docs: `https://mailer123.com/docs` · API reference: `https://mailer123.com/api-reference` · MCP: `https://mailer123.com/docs/mcp`