Skip to main content

Attachments

Three ways to attach a file, and the right one depends on where the bytes are.

Inline​

Base64 in the request. Simplest, and right for small files generated at send time.

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Your invoice",
  "html": "<p>Attached.</p>",
  "attachments": [
    {"filename": "invoice.pdf", "content_type": "application/pdf", "content": "JVBERi0xLjQK..."}
  ]
}

Base64 adds about a third to the size, so a 6MB file becomes an 8MB request body.

Pre-uploaded​

Upload once, reference by id. Right for a file sent to several recipients, or when you want the upload and the send to be separate steps.

curl https://api.epostix.com/v1/attachments \
  -H "Authorization: Bearer $EPOSTIX_API_KEY" \
  -F file=@invoice.pdf
{"attachments": [{"attachment_id": "att_01H..."}]}

Pre-uploads are kept for 24 hours. After that the send fails with attachment_expired. The window is meant for the gap between preparing a message and dispatching it, not for storage.

By URL​

We fetch it when the message is sent.

{"attachments": [{"filename": "report.csv", "content_url": "https://example.com/report.csv"}]}

Two things follow from "when the message is sent" and both surprise people:

  • A signed URL that expires before a scheduled send fails at send time, not at submission. Give such links a lifetime longer than your scheduling window.
  • The URL must be publicly reachable. Private, loopback and link-local addresses are refused, and the check runs again at fetch time, so a hostname that later resolves inside a network is still refused.

Failures surface as attachment_fetch_failed.

Limits​

40MB total per message, across all attachments, before base64 encoding. Exceeding it is attachment_too_large.

That is our limit, not the recipient's. Many mail providers reject well below it, so a message near 40MB is unlikely to be delivered even though we accept it. For anything substantial, link to the file instead: it delivers reliably and you can see whether it was opened.

Inline images​

Set content_disposition to inline with a content_id, then reference it from the HTML:

{"filename": "logo.png", "content_type": "image/png", "content_disposition": "inline", "content_id": "logo", "content": "..."}
<img src="cid:logo" alt="">

Support for cid: references varies by mail client. A hosted image is more predictable, at the cost of being blocked until the recipient loads remote content.