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.

      Temporary and permanent failures

      A message you send is accepted with 202 and then has a life of its own. This page is the vocabulary for the rest of that life.

      The five states

      GET /v1/messages/{id} reports one of these.

      Status Meaning
      queued Accepted by us, not yet handed to the mail server.
      delivered The receiving server accepted it.
      bounced Permanently rejected. The address is now suppressed.
      deferred Our submission failed and automatic retries are finished or were never safe. See Retry strategies.
      unconfirmed Handed over, and we never found out what happened.

      A scheduled send also reads as scheduled until its time arrives.

      Temporary against permanent

      The split is the SMTP response class, and it is made at the point of failure:

      • 5xx is permanent. The server is saying this will never work: no such mailbox, domain refuses you, message rejected. The outcome is bounced and the recipient is added to your suppression list.
      • 4xx is temporary. The server is saying not now: greylisted, over quota, rate limited, busy. A temporary failure is not a bounce, is not counted against your bounce rate, and does not suppress anybody.
      • A connection-level error with no SMTP code at all is treated as temporary, which is the safe reading.

      unconfirmed is an honest answer, not a failure

      This is the state people misread, so it is worth being exact.

      unconfirmed means: the mail server accepted the message, no delivery or bounce event ever reached us, 24 hours passed, and the message is no longer sitting in the server’s queue being retried.

      At that point the outcome is genuinely unknowable. The server no longer holds the message and nothing else recorded whether it arrived. The platform marks it unconfirmed and never guesses, because the two available guesses are both harmful: calling it delivered inflates your stats, and calling it bounced would suppress a recipient who may have received the message perfectly well.

      Things unconfirmed does not mean:

      • it does not mean the message failed;
      • it does not suppress the recipient;
      • it does not count against your bounce rate;
      • it does not mean the message is still being attempted. A message the server is still working on is deliberately excluded, so a healthy send is never written off while the queue is retrying it.

      A few are normal; a lot is a signal. A healthy integration sees the occasional one, where a confirmation genuinely went missing. If most of your recent sends are ending up here, that is a reporting problem worth raising with support rather than a deliverability problem, because the mail most likely arrived.

      Either way, read your stats as delivered-versus-bounced among messages that reached a decided outcome, and leave the undecided ones out of both sides. Monitoring has the arithmetic.

      Mapping to webhooks

      Event Fires on
      delivery.delivered The receiving server accepted it
      delivery.failed Submission failed
      delivery.dsn-perm-fail A permanent failure report, the one that bounces and suppresses
      delivery.dsn-temp-fail A temporary failure report, informational

      There is no event for unconfirmed, because nothing happens at that moment except a timer expiring. If you need to know, poll GET /v1/messages/{id} or read the aggregate counts.

      See Webhook event types.

      What to do with each

      Status Your move
      bounced Nothing to retry. Remove the address at source; it is already suppressed.
      deferred Automatic retries are done. Investigate, then retry explicitly.
      unconfirmed Nothing. Resending risks a duplicate for a message that very likely arrived.
      queued for a long time Check the rate and warm-up caps, then contact support.