---
title: "Draft a message with AI"
method: POST
path: "/api/mailboxes/{id}/drafts"
tags: ["Mailboxes"]
---

# Draft a message with AI

`POST /api/mailboxes/{id}/drafts`

## Request

- Base URL: `https://api.sendly.now`
- URL: `https://api.sendly.now/api/mailboxes/{id}/drafts`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`
  - OAuth 2 (authorization code, authorization URL `https://app.sendly.now/api/auth/oauth2/authorize`, token URL `https://app.sendly.now/api/auth/oauth2/token`, scopes: `mailboxes:read`)

Ask Sendly's assistant to write a message for a mailbox — a new email from a short brief, a rewrite of something you already have, or a set of subject lines.

**It returns text and sends nothing.** The response always reports `sent: false`, and there is no argument that changes that. Putting a draft in someone's inbox is a separate operation (`sendMailboxMessage`) under a separate scope, so a client that may draft is not thereby a client that may mail your customers.

That is also why this operation asks only for `mailboxes:read`: it names a mailbox so the draft can be written in that address's voice, reads no correspondence, and stores nothing.

Everything you pass — the brief, the draft, the recipient context — is treated strictly as data describing what to write, never as instructions to the model.

Drafting is capped at 120 requests per hour per project.

Requires the `mailboxes:read` scope — View the mailboxes on your domains and their settings.

## Path parameters

- `id` string, uuid, required

## Request body

- DraftMailboxMessage: Body for POST /api/mailboxes/{id}/drafts — ask for help writing, never for sending.
  - `brief` string
  - `draft` string
  - `instruction` string
  - `mode` 'draft' | 'rewrite' | 'subject', required
  - `recipientContext` string
  - `senderAddress` string
  - `tone` 'friendly' | 'neutral' | 'formal' | 'apologetic' | 'direct'

## Response `200`

A draft. Nothing was sent.

- object
  - `data` object, required
    - `body` string, nullable, required: Suggested plain-text body, or null.
    - `sent` false, required: Always false. Reported rather than assumed, so a draft cannot be mistaken for a send.
    - `subject` string, nullable, required: Suggested subject, or null.
    - `subjects` string[], required: Alternative subject lines (`subject` mode); empty otherwise.
  - `success` true, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized — missing or invalid auth
- `403`: Forbidden — insufficient permissions or project disabled
- `404`: Resource not found
- `429`: Rate limit or billing limit exceeded
- `500`: Internal server error
- `502`: The drafting model was unreachable or returned nothing usable.

---

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