import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.drafts.attachments.add(
"dft_01JZX8K3M9Q4P7VN2YB6RTDC0E",
{
filename: "order-10473.pdf",
content_type: "application/pdf",
size: 184320,
},
);
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.add_draft_attachment(
"dft_01JZX8K3M9Q4P7VN2YB6RTDC0E",
filename="order-10473.pdf",
content_type="application/pdf",
size=184320,
)
print(result)curl -X POST 'https://api.mails.ai/v1/drafts/dft_01JZX8K3M9Q4P7VN2YB6RTDC0E/attachments' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"filename": "order-10473.pdf",
"content_type": "application/pdf",
"size": 184320
}'{
"id": "dfa_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"filename": "<filename>",
"content_type": "<content_type>",
"size": 0,
"status": "uploading",
"chunk_bytes": 0,
"chunk_count": 0,
"from_message_id": "<from_message_id>",
"created_at": "2026-10-04T12:00:00.000Z",
"storage": { "used_bytes": 0, "limit_bytes": 0 }
}201 The file, uploading until its last chunk arrives.
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
402 Payment required: a plan limit
(plan_limit_exceeded) or a feature the current plan
does not include (feature_not_enabled). The error
object carries upgrade_url, the dashboard page
where the plan can be changed.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
404 Resource not found in this workspace, or the agent
a send names is archived (agent_archived).
409 Conflict — duplicate resource, an in-progress
idempotent request, a draft or scheduled message
that started sending while it was being changed, or
a thread deleted for good while one of its messages
is being sent (duplicate_resource); or an agent
name more than one agent has (agent_name_conflict:
use the agent's id); or a status change on an
archived agent, since archiving cannot be undone
(agent_archived).
500 Internal server error.Add a file to a draft
import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.drafts.attachments.add(
"dft_01JZX8K3M9Q4P7VN2YB6RTDC0E",
{
filename: "order-10473.pdf",
content_type: "application/pdf",
size: 184320,
},
);
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.add_draft_attachment(
"dft_01JZX8K3M9Q4P7VN2YB6RTDC0E",
filename="order-10473.pdf",
content_type="application/pdf",
size=184320,
)
print(result)curl -X POST 'https://api.mails.ai/v1/drafts/dft_01JZX8K3M9Q4P7VN2YB6RTDC0E/attachments' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"filename": "order-10473.pdf",
"content_type": "application/pdf",
"size": 184320
}'{
"id": "dfa_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"filename": "<filename>",
"content_type": "<content_type>",
"size": 0,
"status": "uploading",
"chunk_bytes": 0,
"chunk_count": 0,
"from_message_id": "<from_message_id>",
"created_at": "2026-10-04T12:00:00.000Z",
"storage": { "used_bytes": 0, "limit_bytes": 0 }
}201 The file, uploading until its last chunk arrives.
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
402 Payment required: a plan limit
(plan_limit_exceeded) or a feature the current plan
does not include (feature_not_enabled). The error
object carries upgrade_url, the dashboard page
where the plan can be changed.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
404 Resource not found in this workspace, or the agent
a send names is archived (agent_archived).
409 Conflict — duplicate resource, an in-progress
idempotent request, a draft or scheduled message
that started sending while it was being changed, or
a thread deleted for good while one of its messages
is being sent (duplicate_resource); or an agent
name more than one agent has (agent_name_conflict:
use the agent's id); or a status change on an
archived agent, since archiving cannot be undone
(agent_archived).
500 Internal server error.Path Parameters
Draft id.
Body Parameters
The file's name, as the recipient sees it.
The file's MIME type, such as application/pdf. Left out, application/octet-stream.
The file's size in bytes, at least 1. A draft's files can come to 25 MB together, and 10 files at most.
A draft can carry 10 files, 25 MB together (400 invalid_field), and a workspace's drafts can hold 200 MB of files on Free, 2 GB on Pro and 10 GB on Scale (402 resource_cap_exceeded), counted from when a file is added until its draft is sent or deleted. A file whose upload does not finish is deleted after an hour. The answer's storage says how much of that room is used. Scheduled drafts need the send scope; a test key cannot change a draft a live key made (403 live_mode_required).
Response
File id (dfa_…).
The file's name, as the recipient sees it.
The file's MIME type.
The file's size in bytes.
uploading: some chunks have not arrived, and the draft cannot be sent or scheduled. ready: every chunk is in.
How long each chunk is, except the last, in bytes: 3 MiB.
How many chunks the file is sent in, numbered from 0. 0 on a forward's file, which is read from the email.
On a forward's file: the received message it is read from when the draft is sent. Absent on a file that was uploaded.
When the file was added.
On the answer to adding a file: how much room the workspace's drafts have left for files. Absent otherwise.
Was this page helpful?