Skip to main content
The Email API accepts attachments as base64-encoded content. Decode and validate the source file before building the request so an oversized or unsafe file does not consume retry capacity.

Attachment fields

Limits

Keep combined decoded attachment content at or below 10 MiB, the default service ceiling. The message may contain at most 500 MIME parts, including text and HTML body parts. Base64 increases the HTTP payload size, so set client timeouts and upstream body limits accordingly.
A deployment-specific lower configured limit wins. Handle the returned validation problem instead of retrying the same oversized payload.

Inline images

Set disposition to inline and provide a unique contentId. Reference it from HTML with cid:<contentId>. Also provide useful alt text because clients can block images.

Security checklist

  • Derive the filename on the server; do not trust a client path.
  • Allowlist content types your product actually needs.
  • Scan untrusted files before sending.
  • Do not log base64 content or sensitive document bodies.
  • Use a short-lived object-store workflow for large files instead of forcing them into email.
  • Explain sensitive attachments in the message so recipients can judge them safely.

Common failures

Invalid base64, a missing content type, an unsafe filename, too many MIME parts, or an oversized decoded total causes validation failure before delivery. Correct the payload; do not retry unchanged.

SDK example

Start with the basic send example, then attach the encoded file using your SDK’s request model. Encode the file as base64 first, then add the attachment to the normal SendEmailRequest.
TypeScript