curl --request POST \
  --url https://core-api.getaptly.com/api/email/send \
  --header 'Content-Type: application/json' \
  --header 'x-token: <api-key>' \
  --data '
{
  "userId": "user_abc",
  "channelId": "channel_abc",
  "discussionId": "stream_abc",
  "uuid": "draft_xyz"
}
'

{}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields are invalid",
    "meta": {
      "issues": [
        {
          "field": "to.0.value",
          "code": "invalid_format",
          "message": "must be a valid email address"
        }
      ]
    }
  },
  "requestId": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

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:

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 }.
Upload to S3 — multipart/form-data POST to url, all fields first then the file bytes last as a file field. S3 returns 204.
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

send

curl --request POST \
  --url https://core-api.getaptly.com/api/email/send \
  --header 'Content-Type: application/json' \
  --header 'x-token: <api-key>' \
  --data '
{
  "userId": "user_abc",
  "channelId": "channel_abc",
  "discussionId": "stream_abc",
  "uuid": "draft_xyz"
}
'

{}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields are invalid",
    "meta": {
      "issues": [
        {
          "field": "to.0.value",
          "code": "invalid_format",
          "message": "must be a valid email address"
        }
      ]
    }
  },
  "requestId": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

Authorizations

x-token

string

header

required

Body

application/json

userId

string

required

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

channelId

string

required

Required when sending on-the-fly.

discussionId

string

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.

uuid

string

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

failOnCreateNewThread

boolean

default:true

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

companyId

string

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

object[]

Show child attributes

object[]

Show child attributes

bcc

object[]

Show child attributes

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

attachmentIds

string[]

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.

aptletInstanceId

string

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.