Message IDs and tracking
Every send produces identifiers in more than one place, and the same field name does not always mean the same thing. Read this page before you write correlation logic.
The two identifiers
| What it is | Looks like | |
|---|---|---|
| The Lockally id | A UUID we mint. The one you pass to GET /v1/messages/{id}. |
d290f1ee-6c54-4b01-90e6-d701748f0851 |
| The Internet Message-ID | The RFC 5322 header, as every other mail system knows the message. | <d290f1ee-...@lockally.com> |
They are derived from the same UUID today, but do not rely on that: treat them as two opaque values, because the angle brackets and domain make them unequal as strings in any case.
The trap: message_id means two different things
| Where | id |
message_id |
rfc_message_id |
|---|---|---|---|
POST /v1/send response |
the Lockally id | the Internet Message-ID | absent |
delivery.* webhook |
absent | the Lockally id | the Internet Message-ID |
GET /v1/messages/{id} |
the Lockally id | the Internet Message-ID | absent |
So to join a webhook to the send that produced it:
send response .id == webhook .message_id
A reader who joins message_id to message_id gets no matches at all, which
at least fails loudly. The subtler mistake is passing the send response’s
message_id to GET /v1/messages/{id}, which returns 400 Invalid id because
it is not a UUID.
Store id. It is the key to every other surface.
lockally_id also appears on delivery events. It is deprecated, repeats
message_id, and should not be read in new code.
Delivery statuses
GET /v1/messages/{id} reports one of these:
| Status | Terminal | Meaning |
|---|---|---|
scheduled |
no | Accepted with a future send_at. Derived, not stored. |
queued |
no | Waiting for the send worker. |
sending |
no | Being handed to the mail transfer agent now. |
delivered |
yes | The receiving server accepted it. |
bounced |
yes | Permanently rejected. bounce_reason says why. |
deferred |
no | Temporarily rejected, will be retried. |
complaint |
yes | The recipient marked it as spam. |
unconfirmed |
yes | Handed over successfully, outcome unknown. See below. |
There is no sent and no cancelled: a cancelled scheduled message is deleted
outright rather than marked.
unconfirmed is a real outcome, not an error
It means the mail transfer agent accepted the message, and then no delivery or bounce notification ever arrived for it within 24 hours.
It deliberately counts as neither delivered nor bounced. Guessing
delivered would inflate your stats; guessing bounced would wrongly suppress
a recipient who may well have received the mail. Once the notification is lost
the outcome is genuinely unknowable, so the status says exactly that instead of
picking one.
You should expect to see it, and you should not treat it as a failure. If you are reconciling against your own records, count it separately rather than folding it into either side.
Tracking through webhooks
Polling GET /v1/messages/{id} works, but webhooks are the intended path.
Subscribe to the delivery.* events and correlate on message_id, which, as
above, is the Lockally id.
See Event types for the envelope, the full event list, and
why you must deduplicate on the event id.
What does not exist
Three things the word “tracking” often implies are not part of Lockally, and nothing in the API hints at them:
No open tracking. There is no tracking pixel, no opened event, and no
open count anywhere.
No click tracking. Links in your HTML are sent exactly as you wrote them.
Nothing is rewritten through a redirector, and there is no clicked event.
No custom metadata or tags. There is no field for attaching your own
key-value data to a send and reading it back on the webhook, and no way to tag
a message so you can group sends by campaign or template later.
GET /v1/messages/stats aggregates over the whole account only.
Message size
GET /v1/messages/{id} also returns size_bytes, an approximation of the
assembled message recorded at submission. It is useful for spotting an
unexpectedly large send. See Message size limits.