Transactional emails

On this page:

Send a transactional email

Use POST /api/transactional-mails/send to send a transactional email. Set MAILCOACH_API_URL and MAILCOACH_TOKEN as shown in Authentication.

Both from and to are required. Choose either a saved template with mail_name, or inline content with subject and at least one of html or text.

This example uses inline content and fake: true: Mailcoach logs the email without sending it to the recipient. Remove fake or set it to false when you are ready to send.

curl -X POST "$MAILCOACH_API_URL/transactional-mails/send" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"from":"Your app <hello@example.com>","to":"jane@example.com","subject":"Welcome","html":"<p>Welcome to our app.</p>","fake":true}'

For a saved template, set mail_name to its name or UUID and provide replacements for placeholders such as ::first_name:::

{
    "from": "Your app <hello@example.com>",
    "to": "jane@example.com",
    "mail_name": "welcome",
    "replacements": {
        "first_name": "Jane"
    },
    "fake": true
}

The saved template must exist. Use a sender address configured for your account.

Supported options include:

  • cc, bcc: additional recipients. Multiple recipients can be comma-delimited.
  • reply_to: reply-to addresses.
  • store: defaults to true. Set it to false to omit the email from the transactional email log.
  • mailer: the mailer name. If omitted, Mailcoach uses your account’s default.
  • replacements: a key-value object for placeholders in a saved template.
  • attachments: an array of attachments with name, base64-encoded content, and content_type. An optional content_id identifies an inline attachment. See the API reference for the schema.
  • fake: log without sending when true.

Addresses support the Name <email@example.com> format. Always include Accept: application/json; some send failures can still return a plain-text body, so check the HTTP status before parsing it.

With storage enabled, a successful send returns 200 and the send UUID at the top level:

{
    "uuid": "2ca0e737-b907-468f-819f-5d16e6bd6852"
}

With store: false, success returns an empty 204 response instead. Acceptance does not prove delivery; check the email log and delivery events.

Get all transactional email templates

GET /api/transactional-mails/templates lists saved transactional email templates, not sent email log entries.

curl "$MAILCOACH_API_URL/transactional-mails/templates" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Use ?filter[name]=welcome to search by name and ?sort=-created_at to sort newest first. Results are paginated.

Get a specific transactional email

Use a saved template’s UUID, not its mail_name, in this URL:

curl "$MAILCOACH_API_URL/transactional-mails/templates/11ce123b-57c4-429b-9840-c79f8047d8aa" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

The template is returned under data, including uuid, name, subject, html and store_mail. See the API reference for the complete schema.

Error handling

See common errors and retry guidance. Do not retry a send automatically after a timeout: it may already have been accepted.