How do I send an email from a template?

Send an email from a template in three calls. POST /templates creates a draft with a name, a subject, its content and the variables it expects. POST /templates/{id}/publish freezes that draft; the summary is "Snapshot the draft as an immutable published version." Then call POST /emails with template_id and template_values in place of html or text, and the body is rendered on the server from the current published version. subject can be left out, because the field description says it is "Required unless template or template_id names a published template that has a subject."

Creating and publishing

content is one of three modes: markdown or html with a source string, or block with a list of blocks, each text with a body or raw with html. A markdown template is sent as HTML with a plain-text part made from the same source. variables is a list, each with name, type (string, number or boolean), required and an optional default. Declaring them is what lets a render refuse a missing required value instead of producing an empty greeting; Templates explains that rule.

PATCH /templates/{id} edits the draft, and its summary says "Published templates are immutable." Publishing again creates the next version, GET /templates/{id}/versions lists them oldest first, and POST /templates/{id}/rollback starts a new draft from an older one without rewriting history.

Sending

Pass template_id and a template_values map. The shape template: { "id": …, "variables": … } is accepted too; with that shape, html or text alongside it is refused with "A template cannot be sent with html or text. Provide one or the other." What is rendered is the published version, never the draft, so an edit in progress cannot go out by accident. A required variable that is missing is refused with invalid_parameter rather than sent blank, and a template_id that does not exist on the account is not_found. When neither the request nor the published template has a subject, the refusal is "Add a subject, or publish the template with one."

GET /emails/{id} records template_id and template_version, the version that rendered this message, so a copy a customer forwards weeks later can be reproduced. GET /emails?template_id=… lists every message from one template; the parameter description is "Only mail rendered from this template." A template can be an item in POST /emails/batch, each item with its own template_values.

curl -sS -X POST https://api.agentisend.com/templates/9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42/render \
  -H "Authorization: Bearer $AGENTISEND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

201
{
  "missing_variables": [],
  "rendered": "string",
  "subject": "Your receipt",
  "text": "Thanks — the details are attached."
}

Previewing before you send

POST /templates/{id}/render renders without sending. Its summary is "Render a version with variables (defaults to the current published one; pass "draft" for the working copy). Returns the HTML, the subject and, for markdown, the plain-text part. Unknown variables fail with the names listed; a missing required one fails too unless preview is true, which shows its placeholder (such as {{first_name}}) and lists it in missing_variables." The body takes variables (or values), preview and version_number; the reply is rendered, subject, text and missing_variables. Run it in your test suite with the values your code will send, and a template that stops rendering fails there rather than in production.

Next

• How do I tag emails and find them later?
• How do I send many emails in one request?
• Email for AI agents
• Templates