Attachments

Include files in a transactional email by adding an attachments array to your send request. Files are base64-encoded inline — there is no separate upload step, and attachments are never stored by Brixus365.

---

Add an attachment

Add an attachments array to your POST /v1/emails request. Each item needs four fields:

{
  "to": "user@example.com",
  "subject": "Your invoice",
  "html": "<p>Please find your invoice attached.</p>",
  "attachments": [
    {
      "filename": "invoice-1042.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJ...",
      "inline": false
    }
  ]
}

Field		Type	Description
filename	required	string	The filename shown to the recipient (1–255 characters). Use a descriptive name — it appears in the recipient’s email client.
contentType	required	string	MIME type of the file. Must be one of the allowed types below.
content	required	string	The file’s bytes, base64-encoded. Standard base64 (RFC 4648). The decoded size must be within the per-file limit.
inline	optional	boolean	Default false. Set to true to embed the file inline using a CID reference. See Inline images.
contentId	optional	string	Required when inline: true. A unique identifier you choose (e.g. logo-001). Referenced in your HTML as cid:logo-001. Must be omitted when inline: false.

Encoding tip. In Node.js: Buffer.from(fileBytes).toString('base64'). In Python: base64.b64encode(file_bytes).decode().

---

Inline (CID) images

Inline attachments embed an image directly into the email body, so it renders without requiring the recipient to download it separately. This is the reliable way to include a logo or header image in a transactional email.

{
  "to": "user@example.com",
  "subject": "Welcome",
  "html": "<p><img src='cid:header-logo' alt='Logo' /></p>",
  "attachments": [
    {
      "filename": "logo.png",
      "contentType": "image/png",
      "content": "iVBORw0KGgoAAAANS...",
      "inline": true,
      "contentId": "header-logo"
    }
  ]
}

Rules:

• inline: true requires a non-empty contentId.
• contentId must be omitted (or null) when inline: false.
• Reference it in HTML as cid:<contentId> — no angle brackets in the attribute value.
• Inline attachments count toward the same per-file and total size limits as regular attachments.

---

Size limits and file type rules

Limit	Value
Per-file size (decoded)	5 MB
Total attachment size per message (decoded)	10 MB
Maximum number of attachments per message	10

Sizes are measured on the decoded bytes — not the base64 string. A 5 MB file becomes roughly 6.7 MB when base64-encoded; only the 5 MB decoded value is checked.

---

Allowed file types

Only the MIME types in this table are accepted. Requests using any other type receive a 400 attachment_type_not_allowed error.

Category	MIME type	Common extension
PDF	application/pdf	.pdf
Calendar	text/calendar	.ics
Images	image/png	.png
	image/jpeg	.jpg / .jpeg
	image/gif	.gif
	image/webp	.webp
Text	text/plain	.txt
	text/csv	.csv
Word	application/msword	.doc
	application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
Excel	application/vnd.ms-excel	.xls
	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	.xlsx
PowerPoint	application/vnd.ms-powerpoint	.ppt
	application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx

---

Attachment errors

All attachment errors return HTTP 400 with the standard error envelope.

Error code	When it fires	Fix
attachment_too_large scope: per_attachment	A single file’s decoded size exceeds 5 MB.	Compress the file or host it externally and link to it instead of attaching.
attachment_too_large scope: total	The sum of all decoded attachment sizes exceeds 10 MB.	Split across multiple emails or reduce individual file sizes.
attachment_type_not_allowed	The contentType is not in the allowed list.	Use one of the supported MIME types. Convert the file format if needed.
too_many_attachments	More than 10 attachments in a single request.	Split across multiple sends.
validation_failed	inline: true without contentId, or contentId set when inline: false.	Match inline and contentId as a pair — both set for inline, both absent for regular.

The details object on attachment_too_large includes size_bytes, limit_bytes, and (for per-file) filename — useful for logging exactly which file triggered the error.

---

What’s next

You want to…	Go to
See the full send request schema	Send email
Avoid duplicate sends on retry	Idempotency
Understand all error codes	Error codes