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. If the send request omits from, to, or subject, the template defaults are used.

Test keys (test_…) may send to test and production templates. 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 cannot send a test-only template (403).

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.

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 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.

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_01k3tgwp77fc68kf6qyehx5s21",
  "from": "hello@example.com",
  "to": ["user@example.com"],
  "subject": "Welcome",
  "data": {
    "name": "Andrew"
  }
}'

Response 200

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