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.