GEgetaptly
Email

Send an email

Sends an outbound email scoped to your company. Two usage patterns:

userId and channelId are required on every call.

From an existing draft — also 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:

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

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/...). Auto-detected and registered; do not also list it in attachmentIds.

Each fileId must reference a finished upload.

post/api/email/send

Request

Request body

discussionIdstring

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.

uuidstring

Draft UUID from POST /api/email/create-draft. Required if discussionId is set.

failOnCreateNewThreadboolean

If true (default), the send fails when the email would create a new discussion thread rather than reply to an existing one.

userIdstring required

Required when sending on-the-fly (no discussionId/uuid).

channelIdstring required

Required when sending on-the-fly.

companyIdstring

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

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. Applies when the draft is created on-the-fly (no discussionId/uuid).

attachmentIdsstring[]

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.

aptletInstanceIdstring

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.

object required

Changes

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