Create Template

Create an email template from MJML or HTML. Provide mjml or content, not both. Use the returned template_id with Send Email.

Templates created with a test key are test-only (test_only: true) and cannot be sent with a production key until a production key updates (promotes) them. Templates created with a production key are production templates. The name is unique per domain — you cannot have both a test and production template with the same name.

POST /templates

Example: /templates

Body Parameters

name string required

A unique name for the template on this domain.

mjml string

MJML source. Compiled to HTML in the email. Required unless content is provided.

content string

HTML (or plain text). Required unless mjml is provided. Do not send with mjml.

from string

Default From address used when sending if the send request omits from.

to array

Default recipients used when sending if the send request omits to.

subject string

Default subject used when sending if the send request omits subject.

Note
mjml, content, and subject can have dynamic content using our template language

Example

curl -X POST https://api.mailcast.io/v1/templates \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d $'{
  "name": "welcome",
  "mjml": "<mjml><mj-body><mj-section><mj-column><mj-text>Hello {{name}}</mj-text></mj-column></mj-section></mj-body></mjml>",
  "from": "hello@example.com",
  "subject": "Welcome {{name}}"
}'

Response 201

{
  "template_id": "template_01k3tgwp77eyy9e3kwfmg30svh",
  "name": "welcome",
  "mjml": "<mjml><mj-body><mj-section><mj-column><mj-text>Hello {{name}}</mj-text></mj-column></mj-section></mj-body></mjml>",
  "from": "hello@example.com",
  "to": null,
  "subject": "Welcome {{name}}",
  "test_only": false,
  "created_at": "2025-08-29T12:00:00Z",
  "updated_at": "2025-08-29T12:00:00Z"
}