---
title: "Send email (transactional or marketing)"
method: POST
path: "/send-email"
tags: ["sending"]
---

# Send email (transactional or marketing)

`POST /send-email`

## Request

- Base URL: `https://api.mailly.site` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mailly.site/send-email`
- Auth: HTTP bearer

Applies governance, then passes through to the queue service; supports single, batch, audience, campaign, scheduled, and template-variable sends. Billed per recipient.

## Request body

- object
  - `to` union: Recipients: an email, an array of emails, or an array of {email, externalId} objects; use exactly one of this, audience, or campaignKey
    - string
    - union[]
      - union
        - string
        - object
          - `email` string, required
          - `externalId` string: Business-side contact ID; overrides the external_id of an existing contact
  - `audience` object: Audience filter {include, exclude}
  - `campaignKey` string: Campaign key that uses a frozen audience
  - `campaignName` string
  - `subject` string: Email subject
  - `html` string: HTML body
  - `text` string: Plain-text body
  - `fromEmail` string: From address (must be on a verified sending domain)
  - `fromName` string
  - `replyTo` string
  - `cc` string
  - `bcc` string
  - `topic` string: Unsubscribe and frequency-cap topic
  - `emailType` 'transactional' | 'lifecycle' | 'marketing'
  - `dryRun` boolean: Validate only, do not deliver
  - `testSend` boolean
  - `scheduledAt` number: Scheduled send time in Unix seconds
  - `frequencyCapDays` number
  - `frequencyCapMax` number
  - `topicExclusionDays` number
  - `recipientReason` string
  - `templateKey` string
  - `templateVersion` number
  - `sourceApp` string
  - `businessGoal` string
  - `utm` object
  - `messageId` string
  - `inReplyTo` string
  - `references` string[]
  - `attachments` unknown[]
    - unknown
  - `variables` object: Inline {{var}} template variables

## Response `200`

Send result (passed through from the Queue service, JSON)

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `500`: Missing authentication context or server error
- `502`: Upstream sending service error

---

[API](https://skmtc.dev/mailly/apis/mailly-api.md) · [All operations](https://skmtc.dev/mailly/apis/mailly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailly/apis/mailly-api/revisions/1ceb29637301?raw)