Create an email draft
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:
- Get an upload URL —
POST /api/files/upload-urlwithattachEntityType: "channel",attachEntityIdset to the samechannelIdyou’re emailing from, and the file’sname,extension,size, andcontentType. It returns{ fileId, url, fields }. - Upload to S3 — send a
multipart/form-dataPOSTtourl, appending every entry fromfieldsfirst and the file bytes last as afilefield. S3 returns204. - Mark complete —
POST /api/files/upload-completewith thefileIdfrom step 1.
Then, on this request:
- Regular attachment — add the
fileId(s) toattachmentIds. - Inline image — embed an
<img>in the HTMLbodywhosesrcis 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 inattachmentIds.
Repeat steps 1–3 per file. Each fileId must reference a finished upload or the
request is rejected.
Authorizations
Body
User to record as the draft creator/sender.
channel.meta.id of the outbound email channel.
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.
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.
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 fileIds here. Each must reference a finished upload.
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.