---
title: "Sending a message: the fields that matter"
description: "POST /v1/messages — the required fields, idempotency, HTML and text, tags, and what comes back."
url: https://help.mails.ai/en/articles/5-sending-a-message-the-fields-that-matter
collection: "Sending mail"
updated: 2026-10-10
language: en
---

# Sending a message: the fields that matter

POST /v1/messages — the required fields, idempotency, HTML and text, tags, and what comes back.

![Mails.ai — Sending a message: the fields that matter](https://staticfiles.gleap.io/p6a77ce6bbe980ea9dbca1955/OhevRDa3gMKKQnZ5U2YpXJqdyITA8dGJAJsZVx2XoIxzCIdNOJ6QIX2LJlqLBHR9Y0k3SDy3PLZ.png)

A send is one `POST` to `https://api.mails.ai/v1/messages` with a bearer key. `to` and `subject` are required, plus at least one of `body_text` or `body_html`. `from` names the agent that sends it; you can leave it out while your workspace has a single agent.

![The Messages page, Sending tab: each send's recipient, delivery status, subject, agent and time](https://staticfiles.gleap.io/p6a77ce6bbe980ea9dbca1955/IAlRVuAuylPJZcy4UFlJK6KPZqpBzsTyCeSLaa6V3bX1nmkkiAOmUjqmDWoiUoC4tHBCAOrmwvM.png)

## Idempotency

Send an `Idempotency-Key` header on every send. If the same key and body arrive twice within 24 hours — a retry, a crashed worker, a duplicated queue message — the second request returns the original message instead of mailing the recipient twice. The same key with a different body is refused with `400`. It costs you one header and removes a whole class of incident.

## What comes back

`201` and the message's key fields: its `id` (`msg_...`), `from` (the agent that sent it), its classifier score and `status`. Status moves from `sent` to `delivered` on its own as the receiving side confirms, or to `bounced` or `complained` when that is reported. `GET /v1/messages/{id}` returns the full message.

## Useful optional fields

-   `reply_to` — where replies should land if not the sending agent.
    
-   `cc` / `bcc` — arrays of addresses.
    
-   `tags` — your own name/value labels, up to 10. They come back on the message and on its `message.sent` event; later events carry the `message_id` to match on.
    
-   `scheduled_at` — hold the send until a timestamp (see drafts and scheduling). A future time cannot carry attachments yet: that combination is refused with `400 invalid_field`, because the files would not be kept until then.
    

Every endpoint and a live Try-it console are in the [interactive API reference](https://api.mails.ai/reference).

[Open the API reference](https://api.mails.ai/reference)
