---
title: "Create an email draft"
method: POST
path: "/api/email/create-draft"
tags: ["Email"]
---

# Create an email draft

`POST /api/email/create-draft`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/email/create-draft`
- Auth: one of:
  - API key in header `x-token`
  - API key in header `Authorization`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/email/create-draft/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new outbound email discussion (stream) with a single draft entry, scoped to
your company. Returns the `streamId` and `draftUuid` needed to send via
`POST /api/email/send`.

Recipient fields (`to`, `cc`, `bcc`) accept an array of `{ value, label? }` objects
where `value` is the email address.

### Adding attachments

Attachments must be uploaded to storage **before** you reference them here — you
cannot post file bytes to this endpoint. Upload each file with the three-step direct
upload flow, then attach it:

1. **Get an upload URL** — `POST /api/files/upload-url` with `attachEntityType: "channel"`,
   `attachEntityId` set to the same `channelId` you're emailing from, and the file's
   `name`, `extension`, `size`, and `contentType`. It returns `{ fileId, url, fields }`.
2. **Upload to S3** — send a `multipart/form-data` `POST` to `url`, appending every
   entry from `fields` first and the file bytes last as a `file` field. S3 returns `204`.
3. **Mark complete** — `POST /api/files/upload-complete` with the `fileId` from step 1.

Then, on this request:
- **Regular attachment** — add the `fileId`(s) to `attachmentIds`.
- **Inline image** — embed an `<img>` in the HTML `body` whose `src` is the file's
  download URL (`.../cdn/storage/AptlyFiles/<fileId>/original/...`, returned by step 3).
  It is auto-detected and registered; do **not** also list it in `attachmentIds`.

Repeat steps 1–3 per file. Each `fileId` must reference a finished upload or the
request is rejected.

## Request body

- object
  - `userId` string, required: User to record as the draft creator/sender.
  - `channelId` string, required: `channel.meta.id` of the outbound email channel.
  - `companyId` string: Company ID. Required only when authenticating with a partner token; resolved automatically for API key and delegate token auth.
  - `discussionId` string: When set, append the draft as a reply to this existing thread (stream ID) instead of starting a new discussion. The thread must belong to the same company and channel. The thread's subject is kept and the draft is threaded onto the thread's last message.
  - `to` EmailRecipient[]
    - `value` string, required: Email address.
    - `label` string: Optional display name for the recipient.
  - `cc` EmailRecipient[]
    - `value` string, required: Email address.
    - `label` string: Optional display name for the recipient.
  - `bcc` EmailRecipient[]
    - `value` string, required: Email address.
    - `label` string: Optional display name for the recipient.
  - `subject` string
  - `body` string: Email body (plain text or HTML). To embed an uploaded image inline, add an `<img>` whose `src` is the file's download URL from `POST /api/files/upload-complete` (`.../cdn/storage/AptlyFiles/<fileId>/original/...`). Inline images are auto-detected, tagged with `data-inline-image-id`, and registered on the draft — do not also list them in `attachmentIds`.
  - `attachmentIds` string[]: File ids to include as regular attachments. Upload each file first (`POST /api/files/upload-url` with attachEntityType `channel` and the same channelId → upload to S3 → `POST /api/files/upload-complete`), then pass the resulting `fileId`s here. Each must reference a finished upload.
  - `aptletInstanceId` string: Card to link the outbound to. When set, sending the draft logs the email as an activity on the card and tags the discussion with it.

## Response `200`

Draft stream created.

- object
  - `streamId` string: Discussion/stream ID to pass to `POST /api/email/send`.
  - `draftUuid` string: Draft UUID to pass to `POST /api/email/send`.

## Other responses

- `401`: Invalid or missing API key.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)