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