Templates

A template is a complete HTML document plus a default subject. Rendering is the only call here that never sends anything — use it as often as you like.

What a template is, over HTTP

A template is an HTML file. There is no layout around it: whatever you send is what recipients receive, which also means the unsubscribe link has to be in your own markup — see Merge Tags Cheat Sheet.

The template gallery

Writing 150 lines of email HTML by hand, correctly, is a bad use of anyone's time — yours or an agent's. The gallery is a small set of models we maintain: they carry their unsubscribe link, their editable regions, and they have been checked against the clients that matter. You read one, you copy it, you edit your copy. Read only. There is no endpoint to add, change or delete a model: the gallery belongs to the product, not to an organization. It is the same for every key. Only published models are visible. A draft answers 404, exactly like an id that does not exist — you cannot tell the two apart, and that is deliberate. An API key is still required, as on every /api/v1 route. It is not used to filter anything here: the gallery is common to all organizations, so there is nothing to scope.

Starting a template from a model

POST /api/v1/templates takes galleryTemplateId instead of content. The server reads the published model and copies its HTML, so you never move 150 lines through your own process.
FieldInRequiredDescription
namebodyyes1 to 100 characters
galleryTemplateIdbodyyes*The model to copy. Replaces content
defaultSubjectbodynoFalls back to the model's subject when you leave it out
* Either galleryTemplateId or content — see below.
bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"name": "August newsletter", "galleryTemplateId": "'"$GALLERY_TEMPLATE_ID"'"}' \
  "https://www.agentsmail.io/api/v1/templates"
This is a copy, not an inheritance. Your template holds its own HTML from the moment it is created. Improve the model tomorrow, and nothing of yours changes; edit your template, and the gallery is untouched. Nothing links the two afterwards — there is no "update from the model" endpoint, and there is no way for us to change what you already have.
ConditionAnswer
galleryTemplateId alone201 — the model's HTML is copied
content alone201 — your HTML, merge tags converted
both together400 — two different documents, pick one
neither400 — a template needs a document
galleryTemplateId unknown, or not published400 — the message names the parameter
Sending both is refused on purpose. A silent precedence would ship HTML you did not choose, and you would find out when the email lands in an inbox. The template created this way is yours like any other: same organization as the key, same validations, same limits. The model's HTML is copied byte for byte — no conversion runs on it, so what we published is exactly what you get. Because nothing is converted, any Mailchimp merge tag still in that HTML comes back in unsupportedTags, including ones we would otherwise translate: they stayed raw in your document and will not be interpreted when the email is rendered. Gallery models are normally written in our own {{...}} vocabulary, so this list is usually empty — but you are told when it is not, rather than finding out in an inbox.