Create Template

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

Templates created with a test key are test-only (test_only: true). Templates created with a production key are production templates. user_id and name are unique per domain and mode — a test template and a production template may share the same user_id.

POST /templates

Example: /templates

Body Parameters

name string required

A name for the template. Unique per domain and mode.

user_id string

A stable identifier you supply (1–64 characters: lowercase letters, numbers, hyphens, or underscores). Unique per domain and mode. Defaults to a slug of name.

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. Placeholders such as {{name}} are filled from data at send time.

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",
  "user_id": "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_01k3tgwp77fh5t4kwx2nn046eq",
  "user_id": "welcome",
  "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"
}