---
search:
  tags:
    - Emails
    - POST
seo:
  description: >-
    Send an email. Reference for the POST /emails endpoint in the BillionSend
    API.
sidebar:
  label: Send an email
  badge: POST
title: Send an email
type: openapi-operation
---
`POST /emails`

**Request body** (`application/json`, required)

- `from` (string, required) — Sender, "Name \<user@domain\>" or bare address; the domain must be verified for the team
- `to` (string | string[], required) — Recipient address or list of up to 50
- `subject` (string, required) — Subject line
- `html` (string) — HTML body; at least one of html/text is required
- `text` (string) — Plain-text body; at least one of html/text is required
- `cc` (string | string[]) — Cc address or list
- `bcc` (string | string[]) — Bcc address or list
- `reply_to` (string | string[]) — Reply-To address or list
- `scheduled_at` (string) — Deliver later: ISO 8601 with offset, or relative like "in 2 hours" (an ISO 8601 datetime with offset (e.g. "2026-09-01T12:00:00Z") or a relative time like "in 5 mins", "in 2 hours", or "in 1 day"); max 30 days ahead
- `tags` (object[]) — Key/value labels attached to the email for filtering; names starting with billionsend\_, in any letter case, are reserved
- `topic_id` (string<uuid> | null) — Topic id: recipients opted out of the topic are skipped; a send to one address that is a contact also gets that contact's unsubscribe link. A topic bound to a domain (domain\_id) can be sent only from that domain (422 otherwise)
- `attachments` (object[]) — Attachments with base64 content (no remote paths)
- `headers` (object) — Extra message headers (transport headers are rejected)
- `template` (any) — Not supported: any value is a 422; an email takes html and/or text

Request body example:

```json
{
  "from": "Acme <onboarding@acme.dev>",
  "to": [
    "success@simulator.amazonses.com"
  ],
  "subject": "string",
  "html": "string",
  "text": "string",
  "cc": "string",
  "bcc": "string",
  "reply_to": "string",
  "scheduled_at": "string",
  "tags": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5",
  "attachments": [
    {
      "filename": "string",
      "content": "string",
      "content_type": "string",
      "content_id": "string",
      "path": "string"
    }
  ],
  "headers": {
    "property1": "string",
    "property2": "string"
  },
  "template": null
}
```

**Responses**

- `200` — Email accepted
- `400` — Idempotency-Key is not 1 to 256 characters
- `401` — Missing, malformed, unknown or revoked API key
- `403` — Restricted API key
- `404` — Not found
- `409` — Idempotency conflict
- `422` — Validation error
- `429` — Sending quota exceeded, or the rate limit (rate\_limit\_exceeded, with Retry-After)

Response example, 200:

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
```
