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-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 }.
Upload to S3 — send a multipart/form-dataPOST to url, appending every
entry from fields first and the file bytes last as a file field. S3 returns 204.
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.
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.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Aptly API","colors":{"primary":"#0066FF"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"aptly-10a57313","hasAudioNarration":false,"actualSubdomain":"aptly-10a57313","customDomains":["docs.getaptly.com"],"gitSource":{"type":"github","owner":"workturbo","repo":"core-api-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ae4dfc987cb31e1fa2cb0ab","collectionId":"1788173d-2862-4418-873a-da2b64e83176","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ae4dfc987cb31e1fa2cb0ab"},"feedback":{"agentFeedback":true},"entitlements":{},"buildId":"6ae4dfc987cb31e1fa2cb0ab","clientVersion":"0.0.4045","searchFilterCounts":[{"language":"default","tag":"API Reference","count":192},{"language":"default","tag":"Board","count":28},{"language":"default","tag":"Documentation","count":17},{"language":"default","tag":"Aptly Portal","count":14},{"language":"default","tag":"Contacts","count":10},{"language":"default","tag":"Cards","count":9},{"language":"default","tag":"Knowledge","count":8},{"language":"default","tag":"Getting Started","count":7},{"language":"default","tag":"Inboxes","count":7},{"language":"default","tag":"Context \u0026 Locations","count":6}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/email/create-an-email-draft","slug":"/api-reference/email/create-an-email-draft","pageMetadata":{"title":"Create an email draft","description":"Creates a new outbound email discussion (stream) with a single draft entry, scoped to\nyour company. Returns the `streamId` and `draftUuid` needed to send via\n`POST /api/email/send`.\n\nRecipient fields (`to`, `cc`, `bcc`) accept an array of `{ value, label? }` objects\nwhere `value` is the email address.\n\n### Adding attachments\n\nAttachments must be uploaded to storage **before** you reference them here — you\ncannot post file bytes to this endpoint. Upload each file with the three-step direct\nupload flow, then attach it:\n\n1. **Get an upload URL** — `POST /api/files/upload-url` with `attachEntityType: \"channel\"`,\n `attachEntityId` set to the same `channelId` you're emailing from, and the file's\n `name`, `extension`, `size`, and `contentType`. It returns `{ fileId, url, fields }`.\n2. **Upload to S3** — send a `multipart/form-data` `POST` to `url`, appending every\n entry from `fields` first and the file bytes last as a `file` field. S3 returns `204`.\n3. **Mark complete** — `POST /api/files/upload-complete` with the `fileId` from step 1.\n\nThen, on this request:\n- **Regular attachment** — add the `fileId`(s) to `attachmentIds`.\n- **Inline image** — embed an `\u003cimg>` in the HTML `body` whose `src` is the file's\n download URL (`.../cdn/storage/AptlyFiles/\u003cfileId>/original/...`, returned by step 3).\n It is auto-detected and registered; do **not** also list it in `attachmentIds`.\n\nRepeat steps 1–3 per file. Each `fileId` must reference a finished upload or the\nrequest is rejected.\n","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/email/create-draft","href":"/api-reference/email/create-an-email-draft","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h3: \"h3\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n strong: \"strong\",\n ul: \"ul\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Creates a new outbound email discussion (stream) with a single draft entry, scoped to\\nyour company. Returns the \", _jsx(_components.code, {\n children: \"streamId\"\n }), \" and \", _jsx(_components.code, {\n children: \"draftUuid\"\n }), \" needed to send via\\n\", _jsx(_components.code, {\n children: \"POST /api/email/send\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Recipient fields (\", _jsx(_components.code, {\n children: \"to\"\n }), \", \", _jsx(_components.code, {\n children: \"cc\"\n }), \", \", _jsx(_components.code, {\n children: \"bcc\"\n }), \") accept an array of \", _jsx(_components.code, {\n children: \"{ value, label? }\"\n }), \" objects\\nwhere \", _jsx(_components.code, {\n children: \"value\"\n }), \" is the email address.\"]\n }), \"\\n\", _jsx(_components.h3, {\n children: \"Adding attachments\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Attachments must be uploaded to storage \", _jsx(_components.strong, {\n children: \"before\"\n }), \" you reference them here — you\\ncannot post file bytes to this endpoint. Upload each file with the three-step direct\\nupload flow, then attach it:\"]\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Get an upload URL\"\n }), \" — \", _jsx(_components.code, {\n children: \"POST /api/files/upload-url\"\n }), \" with \", _jsx(_components.code, {\n children: \"attachEntityType: \\\"channel\\\"\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"attachEntityId\"\n }), \" set to the same \", _jsx(_components.code, {\n children: \"channelId\"\n }), \" you’re emailing from, and the file’s\\n\", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"extension\"\n }), \", \", _jsx(_components.code, {\n children: \"size\"\n }), \", and \", _jsx(_components.code, {\n children: \"contentType\"\n }), \". It returns \", _jsx(_components.code, {\n children: \"{ fileId, url, fields }\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Upload to S3\"\n }), \" — send a \", _jsx(_components.code, {\n children: \"multipart/form-data\"\n }), \" \", _jsx(_components.code, {\n children: \"POST\"\n }), \" to \", _jsx(_components.code, {\n children: \"url\"\n }), \", appending every\\nentry from \", _jsx(_components.code, {\n children: \"fields\"\n }), \" first and the file bytes last as a \", _jsx(_components.code, {\n children: \"file\"\n }), \" field. S3 returns \", _jsx(_components.code, {\n children: \"204\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Mark complete\"\n }), \" — \", _jsx(_components.code, {\n children: \"POST /api/files/upload-complete\"\n }), \" with the \", _jsx(_components.code, {\n children: \"fileId\"\n }), \" from step 1.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Then, on this request:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Regular attachment\"\n }), \" — add the \", _jsx(_components.code, {\n children: \"fileId\"\n }), \"(s) to \", _jsx(_components.code, {\n children: \"attachmentIds\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Inline image\"\n }), \" — embed an \", _jsx(_components.code, {\n children: \"\u003cimg>\"\n }), \" in the HTML \", _jsx(_components.code, {\n children: \"body\"\n }), \" whose \", _jsx(_components.code, {\n children: \"src\"\n }), \" is the file’s\\ndownload URL (\", _jsx(_components.code, {\n children: \".../cdn/storage/AptlyFiles/\u003cfileId>/original/...\"\n }), \", returned by step 3).\\nIt is auto-detected and registered; do \", _jsx(_components.strong, {\n children: \"not\"\n }), \" also list it in \", _jsx(_components.code, {\n children: \"attachmentIds\"\n }), \".\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Repeat steps 1–3 per file. Each \", _jsx(_components.code, {\n children: \"fileId\"\n }), \" must reference a finished upload or the\\nrequest is rejected.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Create an email draft","description":"Creates a new outbound email discussion (stream) with a single draft entry, scoped to\nyour company. Returns the `streamId` and `draftUuid` needed to send via\n`POST /api/email/send`.\n\nRecipient fields (`to`, `cc`, `bcc`) accept an array of `{ value, label? }` objects\nwhere `value` is the email address.\n\n### Adding attachments\n\nAttachments must be uploaded to storage **before** you reference them here — you\ncannot post file bytes to this endpoint. Upload each file with the three-step direct\nupload flow, then attach it:\n\n1. **Get an upload URL** — `POST /api/files/upload-url` with `attachEntityType: \"channel\"`,\n `attachEntityId` set to the same `channelId` you're emailing from, and the file's\n `name`, `extension`, `size`, and `contentType`. It returns `{ fileId, url, fields }`.\n2. **Upload to S3** — send a `multipart/form-data` `POST` to `url`, appending every\n entry from `fields` first and the file bytes last as a `file` field. S3 returns `204`.\n3. **Mark complete** — `POST /api/files/upload-complete` with the `fileId` from step 1.\n\nThen, on this request:\n- **Regular attachment** — add the `fileId`(s) to `attachmentIds`.\n- **Inline image** — embed an `\u003cimg>` in the HTML `body` whose `src` is the file's\n download URL (`.../cdn/storage/AptlyFiles/\u003cfileId>/original/...`, returned by step 3).\n It is auto-detected and registered; do **not** also list it in `attachmentIds`.\n\nRepeat steps 1–3 per file. Each `fileId` must reference a finished upload or the\nrequest is rejected.\n","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/email/create-draft","href":"/api-reference/email/create-an-email-draft","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"summary":"Create an email draft","description":"Creates a new outbound email discussion (stream) with a single draft entry, scoped to\nyour company. Returns the `streamId` and `draftUuid` needed to send via\n`POST /api/email/send`.\n\nRecipient fields (`to`, `cc`, `bcc`) accept an array of `{ value, label? }` objects\nwhere `value` is the email address.\n\n### Adding attachments\n\nAttachments must be uploaded to storage **before** you reference them here — you\ncannot post file bytes to this endpoint. Upload each file with the three-step direct\nupload flow, then attach it:\n\n1. **Get an upload URL** — `POST /api/files/upload-url` with `attachEntityType: \"channel\"`,\n `attachEntityId` set to the same `channelId` you're emailing from, and the file's\n `name`, `extension`, `size`, and `contentType`. It returns `{ fileId, url, fields }`.\n2. **Upload to S3** — send a `multipart/form-data` `POST` to `url`, appending every\n entry from `fields` first and the file bytes last as a `file` field. S3 returns `204`.\n3. **Mark complete** — `POST /api/files/upload-complete` with the `fileId` from step 1.\n\nThen, on this request:\n- **Regular attachment** — add the `fileId`(s) to `attachmentIds`.\n- **Inline image** — embed an `\u003cimg>` in the HTML `body` whose `src` is the file's\n download URL (`.../cdn/storage/AptlyFiles/\u003cfileId>/original/...`, returned by step 3).\n It is auto-detected and registered; do **not** also list it in `attachmentIds`.\n\nRepeat steps 1–3 per file. Each `fileId` must reference a finished upload or the\nrequest is rejected.\n","operationId":"createEmailDraft","tags":["Email"],"security":["df7259fd-4baa-47f9-a369-d114d064e461","b567cf45-2a46-4cef-84a0-d3afc69d33ae","b80cf9d1-94cf-47c7-a474-3359834075a8"],"requestBody":"39be2f07-5b05-4bda-8404-1c242625d425","responses":{"200":"cd3d1d60-e967-4ad7-81ac-351657aa647e","401":"52407631-940d-4c68-a19b-47b6535116d7"},"method":"post","type":"path","servers":["07b42306-8584-4b68-93b8-f52adbaae2fe"],"path":"/api/email/create-draft","baseUrlOptions":["https://core-api.getaptly.com"],"title":"Create an email draft","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId","channelId"],"properties":{"userId":{"type":"string","description":"User to record as the draft creator/sender.","isRequired":true,"uniqueKey":"userId","typeLabel":"string"},"channelId":{"type":"string","description":"`channel.meta.id` of the outbound email channel.","isRequired":true,"uniqueKey":"channelId","typeLabel":"string"},"companyId":{"type":"string","description":"Company ID. Required only when authenticating with a partner token; resolved automatically for API key and delegate token auth.","uniqueKey":"companyId","typeLabel":"string"},"discussionId":{"type":"string","description":"When set, append the draft as a reply to this existing thread (stream\nID) instead of starting a new discussion. The thread must belong to the\nsame company and channel. The thread's subject is kept and the draft is\nthreaded onto the thread's last message.\n","uniqueKey":"discussionId","typeLabel":"string"},"to":{"type":"array","items":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"Email address.","isRequired":true,"uniqueKey":"to.items.[INDEX].value","typeLabel":"string"},"label":{"type":"string","description":"Optional display name for the recipient.","uniqueKey":"to.items.[INDEX].label","typeLabel":"string"}},"uniqueKey":"to.items.[INDEX]","typeLabel":"object"},"uniqueKey":"to","typeLabel":"object[]"},"cc":{"type":"array","items":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"Email address.","isRequired":true,"uniqueKey":"cc.items.[INDEX].value","typeLabel":"string"},"label":{"type":"string","description":"Optional display name for the recipient.","uniqueKey":"cc.items.[INDEX].label","typeLabel":"string"}},"uniqueKey":"cc.items.[INDEX]","typeLabel":"object"},"uniqueKey":"cc","typeLabel":"object[]"},"bcc":{"type":"array","items":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"Email address.","isRequired":true,"uniqueKey":"bcc.items.[INDEX].value","typeLabel":"string"},"label":{"type":"string","description":"Optional display name for the recipient.","uniqueKey":"bcc.items.[INDEX].label","typeLabel":"string"}},"uniqueKey":"bcc.items.[INDEX]","typeLabel":"object"},"uniqueKey":"bcc","typeLabel":"object[]"},"subject":{"type":"string","uniqueKey":"subject","typeLabel":"string"},"body":{"type":"string","description":"Email body (plain text or HTML). To embed an uploaded image inline, add\nan `\u003cimg>` whose `src` is the file's download URL from\n`POST /api/files/upload-complete`\n(`.../cdn/storage/AptlyFiles/\u003cfileId>/original/...`). Inline images are\nauto-detected, tagged with `data-inline-image-id`, and registered on the\ndraft — do not also list them in `attachmentIds`.\n","uniqueKey":"body","typeLabel":"string"},"attachmentIds":{"type":"array","items":{"type":"string","uniqueKey":"attachmentIds.items.[INDEX]","typeLabel":"string"},"description":"File ids to include as regular attachments. Upload each file first\n(`POST /api/files/upload-url` with attachEntityType `channel` and the same\nchannelId → upload to S3 → `POST /api/files/upload-complete`), then pass the\nresulting `fileId`s here. Each must reference a finished upload.\n","uniqueKey":"attachmentIds","typeLabel":"string[]"},"aptletInstanceId":{"type":"string","description":"Card to link the outbound to. When set, sending the draft logs the\nemail as an activity on the card and tags the discussion with it.\n","uniqueKey":"aptletInstanceId","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"userId":"user_abc","channelId":"channel_abc","to":[{"value":"[email protected]","label":"Jane Tenant"}],"subject":"Your lease renewal","body":"Please review the attached renewal terms.","aptletInstanceId":"card_abc"},"examples":{"Example":{"title":"Example","value":{"userId":"user_abc","channelId":"channel_abc","to":[{"value":"[email protected]","label":"Jane Tenant"}],"subject":"Your lease renewal","body":"Please review the attached renewal terms.","aptletInstanceId":"card_abc"}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"cd3d1d60-e967-4ad7-81ac-351657aa647e":{"description":"Draft stream created.","content":{"application/json":{"schema":{"type":"object","properties":{"streamId":{"type":"string","description":"Discussion/stream ID to pass to `POST /api/email/send`.","uniqueKey":"streamId","typeLabel":"string"},"draftUuid":{"type":"string","description":"Draft UUID to pass to `POST /api/email/send`.","uniqueKey":"draftUuid","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"streamId":"\u003cstring>","draftUuid":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"52407631-940d-4c68-a19b-47b6535116d7":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","uniqueKey":"error","typeLabel":"string"},"message":{"type":"string","uniqueKey":"message","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":"\u003cstring>","message":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"df7259fd-4baa-47f9-a369-d114d064e461":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-token","scopes":[],"schemeName":"ApiKeyHeader"}},"b567cf45-2a46-4cef-84a0-d3afc69d33ae":{"DelegateToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Delegate token issued by the platform. Format: `DelegateToken \u003ctoken>`","scopes":[],"schemeName":"DelegateToken"}},"b80cf9d1-94cf-47c7-a474-3359834075a8":{"PartnerBearer":{"type":"http","scheme":"bearer","description":"Partner token. Format: `Authorization: Bearer \u003ctoken>`","scopes":[],"schemeName":"PartnerBearer"}}},"servers":{"07b42306-8584-4b68-93b8-f52adbaae2fe":{"url":"https://core-api.getaptly.com","description":"Production"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"x-token","scopes":[],"schemeName":"ApiKeyHeader"},"schema":{"title":"x-token","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ApiKeyHeader","name":"x-token"}],"title":"ApiKeyHeader"},{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"Authorization","description":"Delegate token issued by the platform. Format: `DelegateToken \u003ctoken>`","scopes":[],"schemeName":"DelegateToken"},"schema":{"title":"Authorization","type":"string","description":"Delegate token issued by the platform. Format: `DelegateToken \u003ctoken>`","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"DelegateToken","name":"Authorization"}],"title":"DelegateToken"},{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"Partner token. Format: `Authorization: Bearer \u003ctoken>`","scopes":[],"schemeName":"PartnerBearer"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Partner token. Format: `Authorization: Bearer \u003ctoken>`","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"PartnerBearer","name":"Authorization"}],"title":"PartnerBearer"}]},"originalFileLocation":"openapi.yaml"},"subdomain":"aptly-10a57313","siteName":"Aptly API","title":"Create an email draft - Aptly API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-30T18:20:14.496Z","originalFileLocation":"api-reference/email/create-an-email-draft.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"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: \u0026quot;channel\u0026quot;, attachEntityId set to the same channelId you\u0026#x27;re emailing from, and the file\u0026#x27;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 in the HTML body whose src is the file\u0026#x27;s download URL (.../cdn/storage/AptlyFiles//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.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Aptly API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/aptly-10a57313/_generated/favicon/apple-touch-icon.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/aptly-10a57313/_generated/favicon/favicon-32x32.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/aptly-10a57313/_generated/favicon/favicon-16x16.png?v=3\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/aptly-10a57313/_generated/favicon/favicon.ico?v=3\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create an email draft - Aptly API\">\u003cmeta data-mint-head property=\"og:description\" content=\"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: \u0026quot;channel\u0026quot;, attachEntityId set to the same channelId you\u0026#x27;re emailing from, and the file\u0026#x27;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 in the HTML body whose src is the file\u0026#x27;s download URL (.../cdn/storage/AptlyFiles//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.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Aptly API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.getaptly.com/api-reference/email/create-an-email-draft\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://aptly-10a57313.mintlify.app/_mintlify/api/og/v2?division=Email\u0026amp;title=Create+an+email+draft\u0026amp;description=Creates+a+new+outbound+email+discussion+%28stream%29+with+a+single+draft+entry%2C+scoped+to%0Ayour+company.+Returns+the+%60streamId%60+and+%60draftUuid%60+needed+to+send+via%0A%60P\u0026amp;theme=2df7969a14dd47f616338bb6\u0026amp;signature=01b0c29f416df4aca271005a64712083b50edb32dab48bb322b1543f90b0121c\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create an email draft - Aptly API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"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: \u0026quot;channel\u0026quot;, attachEntityId set to the same channelId you\u0026#x27;re emailing from, and the file\u0026#x27;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 in the HTML body whose src is the file\u0026#x27;s download URL (.../cdn/storage/AptlyFiles//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.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://aptly-10a57313.mintlify.app/_mintlify/api/og/v2?division=Email\u0026amp;title=Create+an+email+draft\u0026amp;description=Creates+a+new+outbound+email+discussion+%28stream%29+with+a+single+draft+entry%2C+scoped+to%0Ayour+company.+Returns+the+%60streamId%60+and+%60draftUuid%60+needed+to+send+via%0A%60P\u0026amp;theme=2df7969a14dd47f616338bb6\u0026amp;signature=01b0c29f416df4aca271005a64712083b50edb32dab48bb322b1543f90b0121c\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"https://mintlify.s3.us-west-1.amazonaws.com/aptly-10a57313/_generated/favicon/browserconfig.xml?v=3\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Aptly API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0066FF\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.getaptly.com/api-reference/email/create-an-email-draft\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/email/create-an-email-draft.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.getaptly.com/#organization\",\"name\":\"Aptly API\",\"url\":\"https://docs.getaptly.com\"},{\"@type\":\"WebSite\",\"@id\":\"https://docs.getaptly.com#website\",\"name\":\"Aptly API\",\"url\":\"https://docs.getaptly.com\",\"publisher\":{\"@id\":\"https://docs.getaptly.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.getaptly.com/api-reference/email/create-an-email-draft#webpage\",\"url\":\"https://docs.getaptly.com/api-reference/email/create-an-email-draft\",\"name\":\"Create an email draft\",\"description\":\"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 in the HTML body whose src is the file's download URL (.../cdn/storage/AptlyFiles//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.\",\"dateModified\":\"2026-10-30T18:20:14.496Z\",\"isPartOf\":{\"@id\":\"https://docs.getaptly.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.getaptly.com/api-reference/email/create-an-email-draft#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.getaptly.com/api-reference/email/create-an-email-draft#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"API Reference\",\"item\":\"https://docs.getaptly.com/api-reference/users/list-users\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create an email draft\",\"item\":\"https://docs.getaptly.com/api-reference/email/create-an-email-draft\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.getaptly.com/api-reference/email/create-an-email-draft#apireference\",\"headline\":\"Create an email draft\",\"name\":\"Create an email draft\",\"description\":\"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 in the HTML body whose src is the file's download URL (.../cdn/storage/AptlyFiles//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.\",\"url\":\"https://docs.getaptly.com/api-reference/email/create-an-email-draft\",\"mainEntityOfPage\":{\"@id\":\"https://docs.getaptly.com/api-reference/email/create-an-email-draft#webpage\"},\"dateModified\":\"2026-10-30T18:20:14.496Z\",\"publisher\":{\"@id\":\"https://docs.getaptly.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.getaptly.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Aptly API\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Aptly API","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/introduction"}]},{"tab":"API Reference","groups":[{"group":"API Reference","pages":[{"group":"Users","pages":[{"title":"List users","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/users","href":"/api-reference/users/list-users"},{"title":"List a user's email inboxes","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/users/{userId}/inboxes","href":"/api-reference/users/list-a-users-email-inboxes"}]},{"group":"Inboxes","pages":[{"title":"List inboxes you can query","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/inboxes","href":"/api-reference/inboxes/list-inboxes-you-can-query"},{"title":"List threads and messages on an inbox","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/inboxes/{channelId}/messages","href":"/api-reference/inboxes/list-threads-and-messages-on-an-inbox"},{"title":"Conversation analytics for an inbox","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/inboxes/{channelId}/analytics","href":"/api-reference/inboxes/conversation-analytics-for-an-inbox"},{"title":"Activity history for an inbox","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/inboxes/{channelId}/history","href":"/api-reference/inboxes/activity-history-for-an-inbox"},{"title":"Volume and response-time trends for an inbox","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/inboxes/{channelId}/trends","href":"/api-reference/inboxes/volume-and-response-time-trends-for-an-inbox"},{"title":"Volume health for an inbox against its own baseline","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/inboxes/{channelId}/health","href":"/api-reference/inboxes/volume-health-for-an-inbox-against-its-own-baseline"},{"title":"List unsent drafts on an inbox","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/inboxes/{channelId}/drafts","href":"/api-reference/inboxes/list-unsent-drafts-on-an-inbox"}]},{"group":"Schema","pages":[{"title":"Get board schema","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/schema/{boardId}","href":"/api-reference/schema/get-board-schema"}]},{"group":"Boards","pages":[{"title":"List boards","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/boards","href":"/api-reference/boards/list-boards"},{"title":"Create a board","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/boards","href":"/api-reference/boards/create-a-board"}]},{"group":"Cards","pages":[{"title":"List cards","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/list","href":"/api-reference/cards/list-cards"},{"title":"List cards (deprecated)","deprecated":true,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}","href":"/api-reference/cards/list-cards-deprecated"},{"title":"Create or update a card","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}","href":"/api-reference/cards/create-or-update-a-card"},{"title":"Get a card","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/{cardId}","href":"/api-reference/cards/get-a-card"},{"title":"Archive a card","deprecated":null,"version":null,"openapi":"/openapi.yaml delete /api/board/{boardId}/{cardId}","href":"/api-reference/cards/archive-a-card"},{"title":"List comments on a card","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/{cardId}/comments","href":"/api-reference/cards/list-comments-on-a-card"},{"title":"List contacts linked to a card","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/{cardId}/contacts","href":"/api-reference/cards/list-contacts-linked-to-a-card"},{"title":"Add or update a comment","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/{cardId}/comment","href":"/api-reference/cards/add-or-update-a-comment"},{"title":"Upload a file to a card","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/{cardId}/file","href":"/api-reference/cards/upload-a-file-to-a-card"}]},{"group":"Board","pages":[{"title":"Archive a board","deprecated":null,"version":null,"openapi":"/openapi.yaml delete /api/board/{boardId}","href":"/api-reference/board/archive-a-board"},{"title":"List merge fields for a board","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/merge-fields","href":"/api-reference/board/list-merge-fields-for-a-board"},{"title":"List users who can open a board","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/users","href":"/api-reference/board/list-users-who-can-open-a-board"},{"title":"Add a tab view","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/configuration/tabViews","href":"/api-reference/board/add-a-tab-view"},{"title":"Add a tab view (legacy)","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/tabView","href":"/api-reference/board/add-a-tab-view-legacy"},{"title":"Verify a delegate token","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/verify-user","href":"/api-reference/board/verify-a-delegate-token"},{"title":"Set or update the board's webhook","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/webhook","href":"/api-reference/board/set-or-update-the-boards-webhook"},{"title":"Remove the board's webhook","deprecated":null,"version":null,"openapi":"/openapi.yaml delete /api/board/{boardId}/webhook","href":"/api-reference/board/remove-the-boards-webhook"},{"title":"Get full board configuration","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration","href":"/api-reference/board/get-full-board-configuration"},{"title":"List board automations","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration/automations","href":"/api-reference/board/list-board-automations"},{"title":"Create an automation","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/configuration/automations","href":"/api-reference/board/create-an-automation"},{"title":"List create-card rules","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration/card-rules","href":"/api-reference/board/list-create-card-rules"},{"title":"Get board options","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration/options","href":"/api-reference/board/get-board-options"},{"title":"List board fields","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration/fields","href":"/api-reference/board/list-board-fields"},{"title":"Add a field","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/configuration/fields","href":"/api-reference/board/add-a-field"},{"title":"Add a mirror field","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/configuration/mirror-fields","href":"/api-reference/board/add-a-mirror-field"},{"title":"Update a field","deprecated":null,"version":null,"openapi":"/openapi.yaml put /api/board/{boardId}/configuration/fields/{fieldUuid}","href":"/api-reference/board/update-a-field"},{"title":"Delete a field","deprecated":null,"version":null,"openapi":"/openapi.yaml delete /api/board/{boardId}/configuration/fields/{fieldUuid}","href":"/api-reference/board/delete-a-field"},{"title":"Reorder fields","deprecated":null,"version":null,"openapi":"/openapi.yaml put /api/board/{boardId}/configuration/field-order","href":"/api-reference/board/reorder-fields"},{"title":"List board field groups","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration/groups","href":"/api-reference/board/list-board-field-groups"},{"title":"Create a field group","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/board/{boardId}/configuration/groups","href":"/api-reference/board/create-a-field-group"},{"title":"Update a field group","deprecated":null,"version":null,"openapi":"/openapi.yaml put /api/board/{boardId}/configuration/groups/{groupUuid}","href":"/api-reference/board/update-a-field-group"},{"title":"Get the create-card form order","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration/start-card-order","href":"/api-reference/board/get-the-create-card-form-order"},{"title":"Set the create-card form order","deprecated":null,"version":null,"openapi":"/openapi.yaml put /api/board/{boardId}/configuration/start-card-order","href":"/api-reference/board/set-the-create-card-form-order"},{"title":"Get board access settings","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration/shares","href":"/api-reference/board/get-board-access-settings"},{"title":"Get board identity fields","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration/theme","href":"/api-reference/board/get-board-identity-fields"},{"title":"Update board identity fields","deprecated":null,"version":null,"openapi":"/openapi.yaml patch /api/board/{boardId}/configuration/theme","href":"/api-reference/board/update-board-identity-fields"},{"title":"List board filters","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/board/{boardId}/configuration/filters","href":"/api-reference/board/list-board-filters"}]},{"group":"Company","pages":[{"title":"Get company info","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/company/info","href":"/api-reference/company/get-company-info"}]},{"group":"Contacts","pages":[{"title":"Get conversations for contacts","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/contacts/conversations","href":"/api-reference/contacts/get-conversations-for-contacts"},{"title":"Get contact conversations","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/contacts/{contactId}/conversations","href":"/api-reference/contacts/get-contact-conversations"},{"title":"List contacts","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/contacts","href":"/api-reference/contacts/list-contacts"},{"title":"Create or update a contact","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/contacts","href":"/api-reference/contacts/create-or-update-a-contact"},{"title":"Look up contacts by email","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/contacts/by-email","href":"/api-reference/contacts/look-up-contacts-by-email"},{"title":"Initiate contact email verification","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/contacts/verify-email","href":"/api-reference/contacts/initiate-contact-email-verification"},{"title":"Confirm contact email verification","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/contacts/verify-email/{requestId}/confirm","href":"/api-reference/contacts/confirm-contact-email-verification"},{"title":"Get a contact","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/contacts/{contactId}","href":"/api-reference/contacts/get-a-contact"},{"title":"Update a contact","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/contacts/{contactId}","href":"/api-reference/contacts/update-a-contact"},{"title":"Get a contact's sentiment history","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/contacts/{contactId}/sentiment","href":"/api-reference/contacts/get-a-contacts-sentiment-history"}]},{"group":"Knowledge","pages":[{"title":"Create a knowledge document","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/knowledge/create","href":"/api-reference/knowledge/create-a-knowledge-document"},{"title":"List knowledge documents","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/knowledge/list","href":"/api-reference/knowledge/list-knowledge-documents"},{"title":"Get the knowledge document tree","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/knowledge/tree","href":"/api-reference/knowledge/get-the-knowledge-document-tree"},{"title":"List a knowledge document's direct children","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/knowledge/{id}/children","href":"/api-reference/knowledge/list-a-knowledge-documents-direct-children"},{"title":"List saved knowledge document versions","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/knowledge/{id}/history","href":"/api-reference/knowledge/list-saved-knowledge-document-versions"},{"title":"Read a saved knowledge document version","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/knowledge/{id}/history/{versionId}","href":"/api-reference/knowledge/read-a-saved-knowledge-document-version"},{"title":"Get a knowledge document","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/knowledge/{id}","href":"/api-reference/knowledge/get-a-knowledge-document"},{"title":"Update a knowledge document","description":"Updates a knowledge document's content and/or metadata. Only fields provided in the\nrequest body are updated — omitted fields are left unchanged. Provide either `html`\nor `markdown`, not both.\n\n## HTML format\n\nStandard HTML (paragraphs, headings, lists, check lists, tables, quotes, code blocks,\nimages, links, bold/italic/underline/strike) is converted to the editor's built-in\nblocks. Aptly's custom blocks and inline items are written as elements carrying a\ntype attribute plus one `data-*` attribute per property. Property names are the\ncamelCase names below written in kebab-case (`cardId` → `data-card-id`). Omitted\nproperties take their default (empty string unless noted). Text inside a block\nelement is ignored, except for the `ai` block. `GET /api/knowledge/{id}` returns\nthese elements in the same format, so its `html` can be edited and sent back.\n\n**Blocks** — `\u003cdiv data-content-type=\"TYPE\" ...>\u003c/div>`, placed between paragraphs:\n\n| Type | Properties | Example |\n| --- | --- | --- |\n| `card` | `cardId` | `\u003cdiv data-content-type=\"card\" data-card-id=\"CARD_ID\">\u003c/div>` |\n| `task` | `taskId` | `\u003cdiv data-content-type=\"task\" data-task-id=\"TASK_ID\">\u003c/div>` |\n| `contact` | `contactId` | `\u003cdiv data-content-type=\"contact\" data-contact-id=\"CONTACT_ID\">\u003c/div>` |\n| `pageLink` | `documentId` (another knowledge document) | `\u003cdiv data-content-type=\"pageLink\" data-document-id=\"DOC_ID\">\u003c/div>` |\n| `aptlyObject` | `objectId`, `objectType`, `aptletUuid` | `\u003cdiv data-content-type=\"aptlyObject\" data-object-id=\"ID\" data-object-type=\"card\" data-aptlet-uuid=\"BOARD_UUID\">\u003c/div>` |\n| `embed` | `url`, `width` (number, default 500), `height` (number, default 400) | `\u003cdiv data-content-type=\"embed\" data-url=\"https://example.com\" data-width=\"600\" data-height=\"400\">\u003c/div>` |\n| `mermaid` | `code` (Mermaid diagram source) | `\u003cdiv data-content-type=\"mermaid\" data-code=\"graph TD; A--\u0026gt;B\">\u003c/div>` |\n| `formField` | `boardUuid`, `fieldUuid`, `fieldType`, `label`, `required` (boolean, default false), `cardId`, `boardName`, `boardIcon`, `boardColor` | `\u003cdiv data-content-type=\"formField\" data-board-uuid=\"BOARD_UUID\" data-field-uuid=\"FIELD_UUID\" data-label=\"Move-in date\" data-required=\"true\">\u003c/div>` |\n| `mergeFieldBlock` | `key`, `boardUuid`, `fieldUuid`, `cardId`, `label`, `boardName` | `\u003cdiv data-content-type=\"mergeFieldBlock\" data-key=\"KEY\" data-label=\"Unit\">\u003c/div>` |\n| `ai` | `prompt`; the element's text is the generated content | `\u003cdiv data-content-type=\"ai\" data-prompt=\"Summarize the lease\">\u003cp>Generated text\u003c/p>\u003c/div>` |\n\n**Inline items** — `\u003cspan data-inline-content-type=\"TYPE\" ...>\u003c/span>`, inside a\nparagraph, heading, list item or table cell:\n\n| Type | Properties | Example |\n| --- | --- | --- |\n| `userMention` | `id`, `entityId`, `fullName` (default `Unknown`), `type` (default `user`), `mentionedBy` | `\u003cspan data-inline-content-type=\"userMention\" data-id=\"USER_ID\" data-full-name=\"Jane Doe\">\u003c/span>` |\n| `cardMention` | `cardId` | `\u003cspan data-inline-content-type=\"cardMention\" data-card-id=\"CARD_ID\">\u003c/span>` |\n| `taskMention` | `taskId` | `\u003cspan data-inline-content-type=\"taskMention\" data-task-id=\"TASK_ID\">\u003c/span>` |\n| `mergeField` | `key`, `boardUuid`, `fieldUuid`, `cardId`, `label`, `boardName`, `fallback` (omit for no fallback) | `\u003cspan data-inline-content-type=\"mergeField\" data-key=\"KEY\" data-label=\"Rent\">\u003c/span>` |\n\nNotes:\n- Escape attribute values as HTML (`\u0026quot;`, `\u0026amp;`, `\u0026lt;`, `\u0026gt;`).\n- `true`/`false` and numbers in attributes are read as booleans and numbers.\n- An element without its `data-content-type` / `data-inline-content-type`\n attribute is treated as plain HTML, not as the custom item.\n- The `ai` block keeps only the text of its first `\u003cp>`.\n- Multi-column layouts are not supported.\n- Markdown cannot express custom blocks; use `html` for them.\n","deprecated":null,"version":null,"openapi":"/openapi.yaml put /api/knowledge/{id}","href":"/api-reference/knowledge/update-a-knowledge-document"}]},{"group":"Email","pages":[{"title":"Create an email draft","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/email/create-draft","href":"/api-reference/email/create-an-email-draft"},{"title":"Send an email","description":"Sends an outbound email scoped to your company. Two usage patterns:\n\n`userId` and `channelId` are required on every call.\n\n**From an existing draft** — also provide `discussionId` and `uuid` returned by\n`POST /api/email/create-draft`. The draft's stored recipients, subject, and body are\nused.\n\n**On-the-fly** — omit `uuid` and provide `userId`, `channelId`, recipients, subject,\nand body. A draft is created automatically before sending. Supplying `discussionId`\n(without `uuid`) sends the message as a reply into that existing thread — the\nthread's subject is kept; omitting both `discussionId` and `uuid` starts a new thread.\n\n### Adding attachments\n\nAttachments apply to the **on-the-fly** pattern (for an existing draft, attach files\nwhen you call `POST /api/email/create-draft`). Upload each file with the three-step\ndirect upload flow first — you cannot post file bytes to this endpoint:\n\n1. **Get an upload URL** — `POST /api/files/upload-url` with `attachEntityType: \"channel\"`,\n `attachEntityId` set to the same `channelId` you're sending from, and the file's\n `name`, `extension`, `size`, and `contentType`. Returns `{ fileId, url, fields }`.\n2. **Upload to S3** — `multipart/form-data` `POST` to `url`, all `fields` first then the\n file bytes last as a `file` field. S3 returns `204`.\n3. **Mark complete** — `POST /api/files/upload-complete` with the `fileId`.\n\nThen, on this request:\n- **Regular attachment** — add the `fileId`(s) to `attachmentIds`.\n- **Inline image** — embed an `\u003cimg>` in the HTML `body` whose `src` is the file's\n download URL (`.../cdn/storage/AptlyFiles/\u003cfileId>/original/...`). Auto-detected and\n registered; do **not** also list it in `attachmentIds`.\n\nEach `fileId` must reference a finished upload.\n","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/email/send","href":"/api-reference/email/send-an-email"}]},{"group":"App","pages":[{"title":"Verify a delegate token (keyless)","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/app/verify","href":"/api-reference/app/verify-a-delegate-token-keyless"},{"title":"Get credential info","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/app/me","href":"/api-reference/app/get-credential-info"}]},{"group":"Templates","pages":[{"title":"List templates","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/templates","href":"/api-reference/templates/list-templates"},{"title":"Create a template","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/templates","href":"/api-reference/templates/create-a-template"},{"title":"Get a template","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/templates/{id}","href":"/api-reference/templates/get-a-template"},{"title":"Update a template","deprecated":null,"version":null,"openapi":"/openapi.yaml put /api/templates/{id}","href":"/api-reference/templates/update-a-template"}]},{"group":"Tasks","pages":[{"title":"Search tasks","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/tasks/search","href":"/api-reference/tasks/search-tasks"},{"title":"Create a task","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/tasks","href":"/api-reference/tasks/create-a-task"},{"title":"Update many tasks","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/tasks/bulk-update","href":"/api-reference/tasks/update-many-tasks"},{"title":"Get a task by ID","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/tasks/{taskId}","href":"/api-reference/tasks/get-a-task-by-id"},{"title":"Update a task","deprecated":null,"version":null,"openapi":"/openapi.yaml put /api/tasks/{taskId}","href":"/api-reference/tasks/update-a-task"}]},{"group":"RoutingGroups","pages":[{"title":"List routing groups","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/routing-groups","href":"/api-reference/routinggroups/list-routing-groups"},{"title":"Create a routing group","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/routing-groups/create","href":"/api-reference/routinggroups/create-a-routing-group"},{"title":"Update a routing group","deprecated":null,"version":null,"openapi":"/openapi.yaml put /api/routing-groups/{id}","href":"/api-reference/routinggroups/update-a-routing-group"},{"title":"Archive a routing group","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/routing-groups/{id}/archive","href":"/api-reference/routinggroups/archive-a-routing-group"}]},{"group":"Files","pages":[{"title":"Get a presigned URL for a direct file upload","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/files/upload-url","href":"/api-reference/files/get-a-presigned-url-for-a-direct-file-upload"},{"title":"Finalize a direct file upload","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/files/upload-complete","href":"/api-reference/files/finalize-a-direct-file-upload"}]},{"group":"WebForms","pages":[{"title":"Submit a web form","deprecated":null,"version":null,"openapi":"/openapi.yaml post /api/web-forms/{formId}","href":"/api-reference/webforms/submit-a-web-form"}]},{"group":"Tours","pages":[{"title":"List tour feedback","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/tours/feedback","href":"/api-reference/tours/list-tour-feedback"},{"title":"Get one showing's tour feedback","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/tours/{showingId}/feedback","href":"/api-reference/tours/get-one-showings-tour-feedback"}]},{"group":"Docs","pages":[{"title":"Fetch this OpenAPI spec","deprecated":null,"version":null,"openapi":"/openapi.yaml get /api/docs/openapi","href":"/api-reference/docs/fetch-this-openapi-spec"}]}]}]},{"tab":"Aptly Portal","icon":"door-closed","pages":[{"title":"Aptly Portal","href":"/portal/introduction"}]}]},"basePath":"","title":"Create an email draft - Aptly API","buildId":"dpl_36EDyZCDfRuoUD9af5CH4M1bqY2h","deploymentId":"dpl_36EDyZCDfRuoUD9af5CH4M1bqY2h","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-DCDCdBVX.js","utils-ME8dDnLe.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-0e84ACsd.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-wgRBj-ia.js","snippetPresets-C11Sgb-o.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-C0lapOpP.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-ZeRQV8fF.js","shallow-BupWh095.js","getApiPlaygroundDisplay-BnYQO2Ss.js","CodeSnippet-RKKOc8c_.js","CodeSnippets-Drf_m8wS.js","Page-Bevw23-4.js","getPastedJson-u6QiPzNZ.js","icon-Bb-CBSxO.js","MethodPill-F7l5AI7V.js","DuplicateIcon-IiAXkdSg.js","createIcon-FliI8EBc.js","DynamicMarkdown-B62XqCSI.js","SectionHeading-Dj31pT03.js","axios-vUo_bRtp.js","Markdown-BOgQCTwD.js","clsx-BIWXJmsZ.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-DKZWslLH.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-UDqbR6xh.js"]}