Transactional emails
On this page:
- Send a transactional email
- Get all transactional email templates
- Get a specific transactional email
- Error handling
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 totrue. Set it tofalseto 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 withname, base64-encodedcontent, andcontent_type. An optionalcontent_ididentifies an inline attachment. See the API reference for the schema.fake: log without sending whentrue.
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.