API ReferenceTransactional EmailUpload Attachments

Upload Transactional Attachments

Get temporary upload URLs for files, upload them, then send one transactional email with the returned attachmentSubmissionId.

When to use this endpoint: For an approved transactional email over the standard 2 MB limit. Request Transactional Email Size Increase under Account → Approvals and wait for your workspace limit to be updated first.

The final email can be at most 40 MB (40,000,000 bytes), including the body, headers, MIME overhead, and Base64-expanded files. The body and other non-attachment data must stay within 2 MB. Attachments can be sent to one to recipient only, without cc or bcc.

POSThttps://tapi.simplysend.email/attachments

Parameters

X-Api-KeyRequired

header string

Your transactional API key. Required to authenticate this request.

X-IdRequired

header string

Your account ID. Use the same account when calling POST /send.

Content-TypeRequired

header string

Set to application/json for this authorization request.

attachmentsRequired

array

A non-empty array of up to 10 file manifests. Send file details only, not Base64 content or email fields.

Each item requires name (filename), contentType (MIME type), sizeBytes (raw file size in bytes), and sha256 (64-character hex SHA-256 digest of the raw file).

Idempotency-Key

header string

Optional unique key for this email. If provided, it must be identical on POST /attachments and POST /send; an independent key on the send request is rejected. Reuse that key when retrying the same email. If you do not use a key, omit it from both requests.

RequestPOST

Response

Complete example: request URLs, upload, and send

The POST /attachments response contains attachmentSubmissionId, expiresAt (Unix milliseconds), and attachmentUploads. Each upload has an uploadUrl and requiredHeaders. PUT the raw bytes to each URL before it expires, then call POST /send with the email fields and attachmentSubmissionId. The returned maximumFinalMimeBytes is the platform ceiling, not your workspace approval; the complete email is checked against both limits at send time.

A successful POST /send returns the normal transactional send response with recipient status and message ID. If you use Idempotency-Key, use the same value for both API calls and any retry; a different key on POST /send is rejected. For emails within the standard 2 MB limit, you can instead send Base64 attachments directly in POST /send without this endpoint.

Validation and retry behavior

POST /attachments accepts only the attachments field. A missing or malformed manifest, unsupported file type, or too many files is rejected before upload.
POST /attachments checks that the files can fit within your approved limit using a minimum email size. The full email is checked again when you call POST /send; approval does not guarantee that every combination of body and files will fit.
Use the returned requiredHeaders on each PUT. A missing upload, or a file whose size or SHA-256 checksum differs from its manifest, causes the send request to fail.
If the upload URLs expire before the files are uploaded, repeat POST /attachments with the same idempotency key to refresh the URLs for the same file manifest.
Common failures include EMAIL_SIZE_EXCEEDED (files or complete email over the workspace limit), ATTACHMENT_UPLOAD_INCOMPLETE, SUBMISSION_NOT_FOUND, and DUPLICATE_REQUEST_IN_PROGRESS. Invalid request bodies are also rejected.