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.

      Recipients, CC and BCC

      Four fields decide who receives a message and where a reply goes. They are not interchangeable, and two of them behave in ways worth knowing before you rely on them.

      Field Visible to recipients Receives the mail Receives replies
      to Yes Yes Only if they reply-all, or no reply_to is set
      cc Yes Yes Same as to
      bcc No Yes Same as to
      reply_to Yes No Yes

      reply_to is the odd one out: it is the only field here that is not a recipient. Nothing is delivered to it. It only tells the recipient’s mail client where to address a reply.

      One send, several recipients

      to, cc and bcc all take arrays, so the simple case is just a longer list:

      {
        "from": "receipts@yourcompany.com",
        "to": ["alice@example.com", "bob@example.com"],
        "cc": ["records@yourcompany.com"],
        "subject": "Invoice 4021",
        "text": "Attached."
      }

      This produces one message with three recipients, not three messages. Alice and Bob can see each other’s addresses and the CC. They cannot see any BCC.

      The cap is 100, and it is shared

      to + cc + bcc  ≤  100

      The limit is on the total across all three fields, not 100 of each. Exceed it and the send is rejected before anything is queued:

      {
        "type": "about:blank",
        "status": 400,
        "title": "Too many recipients",
        "detail": "Hard cap is 100 recipients per send (got 104). Split into batches."
      }

      When to use BCC, and when not to

      BCC is the right tool for a silent archive address, and the wrong tool for sending the same message to many unrelated people.

      It is tempting because it hides the list. The problems are that every BCC recipient still receives one identical message, so you cannot personalise any of it, suppression is applied to the send as a whole rather than per person, and a single bounce is harder to attribute. Spam filters also treat a message whose to does not include the reader with more suspicion than one addressed to them directly.

      For anything resembling a mailing, send one message per recipient through batch sending instead. It costs the same against your allowance, and each recipient gets their own message id, their own delivery event and their own bounce.

      Reply-To, and when it is mandatory

      reply_to is optional most of the time and required in one case: when you send from an address that has no mailbox behind it.

      API accounts can send from any address on a verified domain without creating it first, which is deliberate and useful. The consequence is that a reply to noreply@yourcompany.com would arrive nowhere, with nobody told. So when the from address has no mailbox, the API insists you nominate somewhere real:

      {
        "from": "noreply@yourcompany.com",
        "reply_to": "support@yourcompany.com",
        "reply_to_name": "Acme Support",
        "to": ["customer@example.com"]
      }

      That sends Reply-To: "Acme Support" <support@yourcompany.com>.

      reply_to_name is cosmetic but worth setting: it is the difference between a reply addressed to “Acme Support” and one addressed to a bare string. Accents, non-Latin scripts, commas and quotes are all handled, because Lockally does the RFC 2047 encoding and the quoting for you.

      A Reply-To entry in headers satisfies the same requirement, so an existing integration that already sets it needs no change. When both are present, reply_to wins.

      See Sender identity for which addresses you may put in from in the first place.

      Addresses are lowercased

      Every address in from, to, cc and bcc is trimmed and lowercased before anything else happens. Alice@Example.COM and alice@example.com are the same recipient, and the second is what appears in the message and in GET /v1/messages/{id}.

      Nothing is deduplicated after that. The cap counts entries rather than distinct people, so listing an address twice consumes two of your 100, and the envelope carries it twice. Whether the receiving server then delivers one copy or two is its decision, not ours, so do not rely on either. Deduplicate your own list before you send.