Skip to main content
For the Sending API, upload file bytes first and send by 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:
Then reference it from 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.
The intent supplies the upload method, short-lived 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, call sending_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

Use this form only for small content that is already in memory. For files on disk, upload bytes first and use 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 with validation_error or payload_too_large. Fix the file and retry.

Download mailbox attachments

Mailbox messages include attachment metadata when attachments are present:
  • id
  • filename
  • content_type
  • size_bytes
  • content_id
  • disposition
  • download_url
The 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

  1. Wait for or list messages.
  2. Read the message metadata and find the attachment.
  3. For MCP, call mailbox_read_attachment with the message ID and attachment ID.
  4. Use returned inline text directly, or fetch the returned link promptly for binary or oversized files.
  5. If the URL expired, re-read the message or attachment metadata and fetch the new URL.
Do not construct attachment URLs manually.

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.