Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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."
      }

      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 html and text bodies, which matter more than people expect when the HTML carries embedded data: 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.