attachment_id. Inline base64 attachments remain supported for small generated content and older integrations, but uploaded refs are the preferred path for normal files. Direct and delegated binary uploads require the exact Content-Length; Sendmux SDK and CLI file helpers calculate it from the local file.
Limits
Base64 content counts towards the request body size and increases payload size. Upload refs avoid that overhead, but the final encoded email must still fit within the 25 MB message limit.
Mailbox attachment uploads are available for mailbox send workflows that need to upload a file first and then reference the returned blob ID when sending. Direct mailbox uploads and presigned mailbox uploads use the same per-attachment cap.
Upload before sending with the Sending API
Upload bytes directly when your client has the API key:POST /emails/send or POST /emails/send/batch:
Delegated uploads
Use a delegated upload when a browser, hosted agent, or another remote client needs to upload bytes without seeing your API key.upload_url, max_size_bytes, and every required header. The upload response supplies the attachment_id. The pipeline feeds the capability URL and headers to curl through standard input, so they do not enter child-process arguments.
The upload token can write only that attachment, expires quickly, and does not grant send access.
Agent and MCP workflows
For real Sending files in hosted or local MCP, callsending_create_attachment_upload with filename, content_type, and exact size_bytes. Upload bytes outside model context using the returned method and headers, honour the returned max_size_bytes, then pass the returned attachment_id to sending_send_email or sending_send_email_batch.
For real Mailbox files in hosted or local MCP, call mailbox_upload_attachment with presign_upload_url=true, filename, content_type, and exact size_bytes. Upload bytes outside model context using the returned method and headers, then send with the returned blob_id. The presigned request cap is 7,500,000 bytes.
Use MCP content_base64 only for tiny agent-authored content. Decoded content is capped at 32 KiB: it is not the normal path for real files. SDK and CLI file helpers can accept local paths because they run outside MCP model context. For inbound Mailbox attachments, call mailbox_read_attachment first when you need text-like content.
Mailbox upload before sending
Mailbox send workflows can also upload a file first and reference the returned blob ID when sending. Direct mailbox uploads and presigned mailbox uploads use the same per-attachment cap. SDK and CLI helpers can read a local path. MCP clients instead request a short-lived presigned upload URL, then upload the bytes outside model context with the exact returned method, headers, content type, and content length.Allowed files
Sendmux accepts common image, document, spreadsheet, presentation, text, calendar, and contact formats. Executables and archives are rejected. Binary files are checked against their claimed file type. Text-based files are checked by extension.Inline base64 compatibility
attachment_id.
Attachment fields
An uploaded reference contains only the temporary
attachment_id returned by
an upload endpoint. Inline attachments include a filename with an allowed
extension and base64-encoded content. If supplied, encoding must be base64.
What happens next
If an attachment is too large, unsupported, or does not match its file type, the request fails withvalidation_error or payload_too_large. Fix the file and retry.
Download mailbox attachments
Mailbox messages include attachment metadata when attachments are present:idfilenamecontent_typesize_bytescontent_iddispositiondownload_url
download_url is short-lived and grants access only to that attachment. Fetch it promptly with any HTTP client; no Authorization header is needed for the URL itself.
If the URL expires, re-read the message with GET /mailbox/messages/{message_id}, list or search messages again, or call the MCP mailbox_get_attachment tool to get a fresh download_url. MCP clients that need attachment text should call mailbox_read_attachment first; it returns inline text for text-like attachments and returns a resource link for binary or oversized files. The authenticated attachment download endpoint continues to work for clients that send bearer credentials.
Realtime received-message events can include the same attachment metadata when it is available. Handle older events where attachments is omitted, then re-read message metadata before downloading.
Range requests are still supported on attachment downloads, including short-lived URLs.
Agent workflow
- Wait for or list messages.
- Read the message metadata and find the attachment.
- For MCP, call
mailbox_read_attachmentwith the message ID and attachment ID. - Use returned inline text directly, or fetch the returned link promptly for binary or oversized files.
- If the URL expired, re-read the message or attachment metadata and fetch the new URL.
Related guides
Send by HTTP
Send uploaded attachment refs in single or batch requests.
Mailbox push delivery
Receive live mailbox events and then download attachments from message metadata.
Sending errors
Handle validation and payload size errors.