Mailofly Docs

REST API

Compose (one-off send)

Send transactional or ad-hoc messages without creating a campaign — same merge rules as the in-app Compose screen. Uses your connected account and respects its daily send limit. Up to 100 recipients per request.

POST /api/v1/compose

Authentication: Authorization: Bearer mf_live_…

Request body

  • account_key (required) — Public sending-account key (shown in the app as acc_…), not the account UUID.
  • Content — choose one:
    • template_id — load subject and HTML body from that template (must belong to your user). Do not send subject or body in the same request.
    • subject + body — both required when template_id is omitted. Body is HTML.
  • recipients (optional) — defaults to manual addresses.
    • Manual (default): { "type": "manual", "emails": "a@b.com, c@d.com" } or emails as a string array. Shorthand: top-level to or emails (same formats).
    • Contacts: { "type": "contacts", "contact_ids": ["uuid", …] }. Aliases: contactIds.
  • variables (optional) — object of merge values. Keys are normalized to lowercase with underscores. Aliases: merge_variables, variable_values.

JSON field names also accept camelCase where noted (e.g. accountKey, templateId).

Merge tags and variables

If the resolved subject or body still contains placeholders that need values (for example {{ first_name }}, {{ custom.company }}, or free-form {{ promo_code }}), you must supply every required key in variables with a non-empty string. If anything is missing, the API returns 400 with missing_variables: an array of keys.

Built-in date tags ({{ iso_date }}, etc.) do not need entries in variables.

Responses

200 — { "ok": true, "sent": n, "failed": [ … ] }. Each failed item has email and error.

400 — validation or send error; may include missing_variables.

404 — account_key does not match any of your sending accounts.

Examples

Send with a saved template and manual recipients
POST https://your-deployment.example/api/v1/compose
Authorization: Bearer mf_live_…
Content-Type: application/json

{
  "account_key": "acc_YOUR_ACCOUNT_KEY",
  "template_id": "YOUR_TEMPLATE_UUID",
  "recipients": { "emails": ["friend@example.com"] },
  "variables": {
    "first_name": "Alex",
    "promo_code": "SAVE20"
  }
}
Inline subject and body (HTML)
POST https://your-deployment.example/api/v1/compose
Authorization: Bearer mf_live_…
Content-Type: application/json

{
  "account_key": "acc_YOUR_ACCOUNT_KEY",
  "subject": "Hello {{ name }}",
  "body": "<p>Hi {{ name }}, thanks for joining.</p>",
  "to": "a@example.com, b@example.com",
  "variables": { "name": "Pat" }
}
Contacts as recipients
POST https://your-deployment.example/api/v1/compose
Authorization: Bearer mf_live_…
Content-Type: application/json

{
  "account_key": "acc_YOUR_ACCOUNT_KEY",
  "template_id": "YOUR_TEMPLATE_UUID",
  "recipients": {
    "type": "contacts",
    "contact_ids": ["uuid-1", "uuid-2"]
  }
}

Related