Skip to main content
POST
/
send
/
email
curl --request POST \
  --url https://api.bettermail.com/v2/send/email \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaign": "WELCOME_EMAIL",
  "to": "emily.carter@cbroasters.com"
}
'
{
  "request_id": "01996409-bb35-7e20-b81a-090e59792f68",
  "messages": [
    {
      "message_id": "HPPHRx2JceswMGobIv",
      "contact_key": {
        "email": "emily.carter@cbroasters.com"
      }
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Provide your BetterMail API key as a Bearer token: Authorization: Bearer YOUR_API_KEY. You can generate and manage API keys in the Developer Centre [https://bettermail.app/developer-centre/api] in your BetterMail account.

Body

​
campaign
required

User-defined, human-friendly key that uniquely identifies a campaign within an account. You can create this key when launching a transactional campaign.

Pattern: ^[A-Za-z0-9-_]{3,40}$
Example:

"WELCOME_EMAIL"

​
to
required

Single recipient object, an RFC 5322 email address string, or an array containing both.

​
profile_data
object

Arbitrary key-value pairs to upsert/merge into the recipient's profile and to use for template personalization.

Example:
{
  "first_name": "Emily",
  "loyalty": { "level": "gold", "points": 1200 },
  "marketing_opt_in": true
}
​
message
object

Unified per-message override for email, layered on top of your transactional campaign's defaults. Use this object to override corresponding campaign parts (e.g., from/reply-to/subject/bodies) without changing the campaign itself.

Precedence & merge rules

  • Request level applies to all recipients.
  • Recipient level, when provided, overrides request level.
  • Unset fields fall back to the campaign template values.
  • Arrays (cc, bcc) replace (no merge).
  • headers are merged, with recipient-level keys winning on conflict.
  • Restricted/system headers (From/To/Cc/Bcc/Subject/Reply-To/In-Reply-To, Content-Type, MIME-Version) must not be set here; they will be ignored.

Bodies & formats

  • text is the plain-text email body.
  • html is rich content and supports BML.
​
attachments
object[]

Attachments applied to all recipients. Recipient-level attachments (if any) are additive.

Size limit: The sum of all attachments for each message (request-level + recipient-level + any unreferenced multipart binaries auto-attached) must not exceed 10 MB. For base64 data, the decoded byte size is used; for multipart files, the uploaded part size is used; for URLs, the fetched content size is used.

In multipart/form-data requests, streamed files can be referenced via file_ref. Any unreferenced binary parts are auto-attached to each email message using their filename and content type.

Required array length: 1 - 10 elements

Union of supported attachment types. In multipart/form-data requests, any unreferenced binary parts are auto-attached to each email message using their filename and content type.

Response

Request accepted; message(s) queued for delivery

​
request_id
string<uuid>
required

A system-generated UUID v7 identifier for the send request.

Example:

"018e2c68-81c2-7c5f-bf5e-8f26b8a0d2a4"

​
messages
object[]
required

An array of objects describing each message enqueued.