GEgetaptly
Email

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:

  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.

post/api/email/create-draft

Request

Request body

userIdstring required

User to record as the draft creator/sender.

channelIdstring required

channel.meta.id of the outbound email channel.

companyIdstring

Company ID. Required only when authenticating with a partner token; resolved automatically for API key and delegate token auth.

discussionIdstring

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.

subjectstring
bodystring

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.

attachmentIdsstring[]

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.

aptletInstanceIdstring

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

Draft stream created.

streamIdstring

Discussion/stream ID to pass to POST /api/email/send.

draftUuidstring

Draft UUID to pass to POST /api/email/send.

Changes

No recorded changes to this operation across all 1 revision of this API.