Message size limits
Three limits apply, and all three are enforced by the API itself, so every size failure comes back as a problem document you can parse.
| Limit | Value | On failure |
|---|---|---|
| Per attachment | 10 MB of file content | 400 Attachment too large, names the file |
| All attachments together | 20 MB of file content | 400 Attachments too large, names the total |
| Whole request body | 30 MB of JSON | 413 Request too large, names both caps |
Attachments are measured before base64
The 10 MB cap is on the decoded file, so what you send is larger. Base64 inflates by roughly four bytes for every three:
10 MB file -> about 13.4 MB of JSON
Over the cap, the API rejects the request cleanly and names the file:
{
"type": "about:blank",
"status": 400,
"title": "Attachment too large",
"detail": "\"report.pdf\" exceeds 10 MB cap."
}
Each attachment can be legal while the set is not
The per-file and the total caps are separate checks, and the second is the one people meet without expecting it:
3 attachments x 9 MB = 27 MB of files each one legal
= over the 20 MB total
That is rejected before anything is queued, naming the total rather than any one file:
{
"status": 400,
"title": "Attachments too large",
"detail": "Attachments total about 27 MB; the cap is 20 MB across all attachments on one message."
}
Keep your own total under 20 MB of actual file content and you are inside every limit with room for the body and the JSON structure.
What counts toward the request
Everything in the JSON body, not just attachments:
- the base64 of every attachment, at 4/3 of the file size
- the
htmlandtextbodies, which matter more than people expect when the HTML carries embeddeddata:images - headers, recipient lists, template variables and the JSON syntax itself
For a batch, the 30 MB ceiling applies to the whole batch request, while the 10 MB and 20 MB attachment caps apply per message inside it. A batch of messages with attachments reaches the request ceiling quickly, so keep batches with attachments small.
Recipient-side limits are not ours
A message that Lockally accepts can still be rejected by the receiving mail server, which applies its own maximum. Many common providers sit around 25 MB for the whole assembled message, including the base64 encoding of its attachments.
So two 9 MB attachments pass every check described on this page, and then bounce at a recipient whose own ceiling is 25 MB once base64 is counted. If attachments are central to what you are building, host the file and send a link.
Checking what was actually sent
GET /v1/messages/{id} returns size_bytes, an approximation of the assembled
message recorded at submission time. It is a useful signal when a send is
bouncing at recipients and you suspect size.