---
title: "Send an email"
method: POST
path: "/v1/emails"
tags: ["Emails"]
---

# Send an email

`POST /v1/emails`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/emails`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Requires `emails:w`.

## Request body

- object: One email: a subject with html, text or both, or a template.
  - `from` string: Sender, optionally with a name. Its domain must be a verified sending domain on your account. Optional when the template sets one.
  - `to` union, required: A string or an array; at most 50 recipients across to, cc and bcc.
    - string, email
    - string[]
  - `cc` union: A string or an array.
    - string, email
    - string[]
  - `bcc` union: A string or an array.
    - string, email
    - string[]
  - `reply_to` union: A string or an array.
    - string, email
    - string[]
  - `subject` string: Up to 998 characters. Leave out subject, html and text when you send a template.
  - `html` string: The HTML body: at most 2 MB, before and after variables are substituted. Give html, text or both, unless you send a template.
  - `text` string: The plain text body: at most 2 MB, before and after variables are substituted. Give html, text or both, unless you send a template.
  - `template` object: Send a stored template instead of subject, html and text: its id or alias, and values for its variables.
    - `id` string, required: The template's id or alias. A live key sends its published version; a test key sends its draft.
    - `variables` object: Values for the template's variables, by key.
  - `variables` object: Values to substitute into placeholders in subject, html and text. Ignored when template is set; a template's own variables go in template.variables instead.
  - `headers` object: Extra email headers, sent as given. Headers HonkIO sets itself (To, From, Subject, Content-Type, List-Unsubscribe and the like) and any name starting with ARC- or X-SES- are refused with EMAIL_HEADER_INVALID.
  - `attachments` object[]: Up to 10 files and 25 MB in total. The first 2 MB per recipient are included; each started MB above that is charged per recipient (GET /v1/pricing). Executable and script types are refused.
    - `filename` string, required: The file name the recipient sees.
    - `content` string: The file, base64 encoded. Give exactly one of content, content_base64 or path.
    - `content_base64` string: The file, base64 encoded (the same as content).
    - `path` string, uri: An HTTPS URL HonkIO fetches the file from.
    - `content_type` string: The MIME type, such as application/pdf. Inferred when left out.
    - `content_id` string: Embeds the file inline: reference it from html as cid: followed by this id.
  - `tags` object[]: Up to 10 name and value pairs, each part 1 to 256 letters, digits, underscores or hyphens. Names starting with honkio_ are reserved. Tags are kept after the subject and body are purged, so keep personal information out of them.
    - `name` string, required
    - `value` string, required
  - `is_commercial` boolean: False by default. True marks a commercial message under CASL: it goes to exactly one recipient, needs consent on file for that address, and carries an unsubscribe footer and header.
  - `scheduled_at` string, date-time, nullable: Send later: an ISO 8601 date-time with an offset, 1 minute to 30 days ahead.
  - `tracking` object: Open and click tracking for this email, overriding the sending domain's setting.
    - `opens` boolean: Track opens with a pixel.
    - `clicks` boolean: Track clicks by rewriting links.
  - `disable_unsubscribe_footer` boolean: Leave out the unsubscribe footer HonkIO adds to a commercial email. The one click unsubscribe header is still sent: put your own unsubscribe link in the body.

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: FORBIDDEN (the key lacks emails:w), EMAIL_DOMAIN_NOT_ALLOWED (this key may not send from that domain) or SENDING_PAUSED (live email is paused for this account after a high bounce or complaint rate; details carry paused_until, reason and channel: "email"). Test keys are never paused.
- `429`: TEST_EMAIL_QUOTA_EXCEEDED: the account's test keys have created 200 emails in the last 24 hours (details carry limit, used, requested and window_hours); live keys have no such quota. Or RATE_LIMITED at 100 requests per second.
- `500`: Unexpected server error.

---

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