Send Email

Send an email. Provide text and/or html, or a template_id created with Create Template.

When template_id is set, it wins: the compiled template HTML is rendered with data, and any text or html on the request is ignored. from, to, and subject fall back to the template defaults when omitted. subject is rendered with the template language as plain text (no HTML escaping).

template_id may be the generated TypeID or the template user_id. Test keys (test_…) send the test template if one exists for that user_id, otherwise the production template. Recipients on the same organizational domain as the token domain are delivered as requested. Other recipients are rewritten at the envelope to the token redirect_email (required when the key is created). MIME To/Cc are not changed. Idempotency keys used with a test key do not collide with production.

A production key only sends production templates. A test-only template is treated as not found.

POST /emails

Example: /emails

Body Parameters

from string

The From address. Must match the API token domain. Required unless the template has a default.

to array

Recipients. Required unless the template has a default.

subject string

Subject line. Required unless the template has a default. When template_id is set, placeholders such as {{name}} are filled from data.

text string

Plain-text body. Ignored when template_id is set. Required unless html or template_id is provided.

html string

HTML body. Ignored when template_id is set. Required unless text or template_id is provided.

template_id string

A template TypeID or user_id. When set, the template body is used and text / html are ignored. Use with data for variable substitution.

data object

Values substituted into the template language in the template. Interpolated values are HTML-escaped and newlines become <br>.

substitute array

Data keys to render as templates before the outer template runs. Use this when a value such as message_body contains {{name}}, {{#if}}, or {{#each}}. Unlisted values are inserted as-is. Listed fields are Handlebars only, not MJML.

markdown array

Data keys to render as [CommonMark](https://commonmark.org/) before interpolation. Use for a message body with **bold**, *italic*, or [text](url). Raw HTML is escaped. Runs after substitute when a key is in both lists.

Example

curl -X POST https://api.mailcast.io/v1/emails \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d $'{
  "template_id": "template_01k3tgwp77f2fr435yydhf0tns",
  "from": "hello@example.com",
  "to": ["user@example.com"],
  "subject": "Welcome",
  "data": {
    "name": "Andrew"
  }
}'

Response 200

{
  "email_id": "email_01k3tgwp77e4pa8pn4d0h1svx5",
  "status": "pending"
}

Example with a templated field

The template contains {{message_body}}. Listing message_body in substitute expands {{name}} inside that value before the template runs.

curl -X POST https://api.mailcast.io/v1/emails \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d $'{
  "template_id": "template_01k3tgwp77fy3a0npj92emp67g",
  "from": "hello@example.com",
  "to": ["user@example.com"],
  "subject": "Welcome",
  "data": {
    "name": "Andrew",
    "message_body": "Hi {{name}}"
  },
  "substitute": ["message_body"]
}'

Response 200

{
  "email_id": "email_01k3tgwp77fjs8fxrwm0sv1myh",
  "status": "pending"
}