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.

      Bounce handling

      A bounce is the receiving side telling us a message cannot be delivered. What happens next depends entirely on whether it said “never” or “not now”.

      Hard and soft

      A hard bounce is a permanent failure. The SMTP status begins with 5, or a failure report arrives with a 5.x.x status and an action of failed. The address does not exist, the domain refuses you, or the message was rejected outright.

      The platform:

      1. marks the message bounced;
      2. adds the recipient to your suppression list, immediately and automatically;
      3. counts it toward the 24 hour bounce rate the reputation engine watches;
      4. fires delivery.dsn-perm-fail.

      A soft bounce is a temporary failure. A 4.x.x status, a greylist, a full mailbox, a busy server. It is not a bounce in any way that matters here: it does not suppress, it does not count toward your bounce rate, and the mail server keeps retrying for days.

      A delayed-delivery notice is also not a bounce. Only failed plus a 5.x.x status qualifies.

      Two routes in

      Bounces reach the platform two ways, and you will see the effect of both.

      The mail server’s own delivery events, in real time, which is how most bounces arrive and why a delivery.dsn-perm-fail webhook usually lands within seconds.

      A collector that reads bounce reports from the return path, for reports that arrive as ordinary email rather than as a delivery event. It parses the report, ties it to the original message, and records the bounce. Reports our own server generated are recognised and not double-counted.

      If you have set a custom Return-Path, that is where those reports go, and the collector reads them from there.

      Seeing them

      curl -s "https://api.lockally.com/v1/messages?status=bounced" \
        -H "Authorization: Bearer $LOCKALLY_API_KEY"

      GET /v1/messages/{id} carries a bounce_reason with the SMTP text, and GET /v1/messages/{id}/events gives the per-recipient timeline. Aggregate counts by outcome come from GET /v1/messages/stats.

      What to do about them

      Remove the address at source. Suppression stops the message leaving, but it does not stop your application from asking, and it does not improve your bounce rate: the rate is computed from what actually went out and failed. Fixing it in your own database is the only thing that moves the number.

      Do not retry a hard bounce. There is nothing to retry. Re-submitting across a cleaned-looking list is the most common way workspaces trip the reputation engine.

      Investigate a sudden cluster. A spike at one provider is usually a reputation or authentication problem at that provider, not a list problem. Check authentication before blaming the addresses.

      The one thing to know about hard bounces here

      The suppression is per workspace, across every stream. A hard bounce from a marketing send blocks that address for your transactional mail too, password resets and receipts included.

      That is the right default, because an address that does not exist does not exist for receipts either. It is also a sharp edge if a bad import poisons addresses that were fine. Suppression management covers how to see the list and remove an entry.