Templates and aliases

Instead of html and text, an email can be sent from a saved template — by its id (templateId) or by its alias (templateAlias). An alias is a string name of a template, for example order-confirmation, that you assign yourself. Assign the same alias to templates in your test and production accounts, or to a new template replacing an old one — and you won't need to change your sending code.

Before you start

To send — a token with the email.send scope.
To set an alias — a token with the templates.write scope.
An HTML template in the account: created in the dashboard or with POST /api/v1/public/templates.

Sending from a template

{
  "data": {
    "from": { "email": "noreply@shop.com", "name": "Shop" },
    "to": { "email": "client@example.com", "name": "John" },
    "subject": "Order #{{orderId}} received",
    "templateAlias": "order-confirmation",
    "variables": { "name": "John", "orderId": "1234" }
  }
}

Here is the full request:

curl -X POST https://api.emailmassivo.com/api/v1/public/emails \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-confirmation" \
  -d '{"data": {"from": {"email": "noreply@shop.com", "name": "Shop"}, "to": {"email": "client@example.com", "name": "John"}, "subject": "Order #{{orderId}} received", "templateAlias": "order-confirmation", "variables": {"name": "John", "orderId": "1234"}}}'

Pass one of templateId and templateAlias. They can't be combined with html or text — 400 BAD_REQUEST with reason: MUTUALLY_EXCLUSIVE.
subject is required when sending from a template too.
variables are substituted into the template, subject, and previewText in place of {{name}} placeholders — the same rules as for variables in html.
A change to the template or alias takes effect from the next send.
No template with this id or alias — 404 TEMPLATE_NOT_FOUND. The template doesn't compile — 422 TEMPLATE_SYNTAX_ERROR.
In GET /api/v1/public/emails/{emailId} the templateId field holds the id of the template found by the alias.

Template alias

Format

Lowercase Latin letters, digits, _, and -; starts with a letter; up to 64 characters. For example: order-confirmation, password_reset, welcome2.
Unique within the account among non-deleted templates. Deleting a template frees its alias.
Optional: without an alias, the template is sent by templateId.
A copy of a template is created without an alias.

Set, change, reset

The alias is the template's alias field in the public API. It's set when creating a template (POST /api/v1/public/templates) or later (PATCH /api/v1/public/templates/{templateId}) and is returned when reading a template and in template lists.

curl -X PATCH https://api.emailmassivo.com/api/v1/public/templates/17 \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"alias": "order-confirmation"}}'

To reset the alias, pass null:

{ "data": { "alias": null } }

API and MCP only

The dashboard has no alias field: aliases are set through the public API or the MCP template tools (public_templates_create, public_templates_update).

Alias errors

HTTP	`error.code`	Cause	Action
400	`BAD_REQUEST`	The alias doesn't match the format	Fix the alias
409	`TEMPLATE_ALIAS_ALREADY_EXISTS`	The alias is already used by another template in the account	Choose another alias or reset it on the other template

Before you start​

Sending from a template​

Template alias​

Format​

Set, change, reset​

Alias errors​

See also​