Please find your invoice attached.
", "attachments": [{ "attachment_id": "att_tz4a98xxat96iws9zmbrgj3a" }] } ``` ## Delegated uploads Use a delegated upload when a browser, hosted agent, or another remote client needs to upload bytes without seeing your API key. ```bash theme={null} SIZE_BYTES="$(wc -c < invoice.pdf | tr -d ' ')" SHA256="$(shasum -a 256 invoice.pdf | awk '{print $1}')" curl -X POST https://smtp.sendmux.ai/api/v1/emails/attachment-uploads \ -H "Authorization: Bearer smx_mbx_your_key_here" \ -H "Content-Type: application/json" \ -d "{ \"filename\": \"invoice.pdf\", \"content_type\": \"application/pdf\", \"size_bytes\": $SIZE_BYTES, \"sha256\": \"$SHA256\" }" ``` The response includes an `upload_url` and required `headers`, including `Content-Type` and exact `Content-Length`. Send a `PUT` request to that URL with the exact file bytes and returned headers. The upload token can write only that attachment, expires quickly, and does not grant send access. ## Agent and MCP workflows For local MCP clients, use `sending_upload_attachment` with `file_path` before `sending_send_email` or `sending_send_email_batch`. The tool reads the local file from a client-approved root and returns an `attachment_id`. For hosted MCP clients or shell-capable agents, use `sending_create_attachment_upload`, upload the file bytes to the returned `upload_url` with the returned headers, then pass the resulting `attachment_id` in `sending_send_email` or `sending_send_email_batch`. Do not place file bytes or large base64 strings in the prompt. For mailbox sends, use `mailbox_upload_attachment` first and send with the returned `blob_id`. For inbound mailbox attachments, use `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. For local tools and SDK helpers, send the file path and let the tool read the bytes locally. For shell-capable or hosted agents, mint a short-lived presigned upload URL, then upload the file bytes 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 ```json theme={null} { "from": { "email": "hello@example.com" }, "to": { "email": "user@example.com" }, "subject": "Invoice attached", "html_body": "Please find your invoice attached.
", "attachments": [ { "filename": "invoice-2026-03.pdf", "content": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...", "type": "application/pdf" } ] } ``` 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 | Form | Required fields | Optional fields | | ------------------ | --------------------- | ------------------ | | Uploaded reference | `attachment_id` | None | | Inline base64 | `filename`, `content` | `type`, `encoding` | 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. ## Related guides