Send an email
Sends an outbound email scoped to your company. Two usage patterns:
From an existing draft — provide discussionId and uuid returned by
POST /api/email/create-draft. The draft’s stored recipients, subject, and body are
used.
On-the-fly — omit uuid and provide userId, channelId, recipients, subject,
and body. A draft is created automatically before sending. Supplying discussionId
(without uuid) sends the message as a reply into that existing thread — the
thread’s subject is kept; omitting both discussionId and uuid starts a new thread.
Adding attachments
Attachments apply to the on-the-fly pattern (for an existing draft, attach files
when you call POST /api/email/create-draft). Upload each file with the three-step
direct upload flow first — you cannot post file bytes to this endpoint:
- Get an upload URL —
POST /api/files/upload-urlwithattachEntityType: "channel",attachEntityIdset to the samechannelIdyou’re sending from, and the file’sname,extension,size, andcontentType. Returns{ fileId, url, fields }. - Upload to S3 —
multipart/form-dataPOSTtourl, allfieldsfirst then the file bytes last as afilefield. S3 returns204. - Mark complete —
POST /api/files/upload-completewith thefileId.
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/...). Auto-detected and registered; do not also list it inattachmentIds.
Each fileId must reference a finished upload.
Authorizations
Body
Stream ID from POST /api/email/create-draft (required if uuid is set).
When supplied without uuid, the on-the-fly draft is appended as a reply
into this existing thread (same company + channel) instead of starting a
new discussion; the thread's subject is kept.
Draft UUID from POST /api/email/create-draft. Required if discussionId is set.
If true (default), the send fails when the email would create a new
discussion thread rather than reply to an existing one.
Required when sending on-the-fly (no discussionId/uuid).
Required when sending on-the-fly.
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. Applies when the draft
is created on-the-fly (no discussionId/uuid).
File ids to include as regular attachments (applies when the draft is
created on-the-fly). 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. Logs the email as an activity on the card and tags the discussion. Works whether the draft was pre-created or is created on-the-fly.
Response
Email sent successfully.
The response is of type object.