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.

      Retry strategies

      Three different things can retry, and only two of them are automatic. Knowing which is which is the difference between a message that eventually arrives and one that sits still forever.

      1. The mail server retries delivery

      Once your message is handed to the mail server, it owns delivery. A temporary failure from the receiving side is retried on the server’s own schedule, for days, without involving you or us.

      You do not configure this, and there is nothing to tune. A message in that state is working as intended, which is also why the platform deliberately leaves it alone rather than writing it off as unconfirmed.

      2. We retry our own handoff, but only one failure

      If our worker cannot reach the mail server before the message body is on the wire (connect, TLS or authentication failure), the message goes back on the queue and is tried again. That is safe precisely because nothing was transmitted.

      Once the body has been sent, we never re-queue automatically, even if we never read the reply. The server may already hold a copy, and re-queueing would deliver twice. A duplicate receipt is worse than a delayed one.

      3. We retry a refused submission, on a backoff

      If the relay refused the message, we try again automatically: after 1 minute, 5, 15, an hour, then four hours. Five attempts over roughly five and a half hours, then it stops.

      While a message is waiting for its next attempt it sits as queued, not deferred, so a message in queued longer than you expect is usually one being retried.

      “Refused” is doing real work in that sentence. It means either an explicit 4xx reply at any stage, or a connection that dropped before the message body went out. In both cases the relay demonstrably does not have a copy, so another attempt cannot deliver twice.

      4. Nothing retries an ambiguous failure

      A message that exhausts its five attempts ends the same way, with a reason saying it gave up rather than just the last SMTP text.

      So deferred now means “stopped, and somebody has to decide”, rather than “stopped” covering both cases. Build for it:

      • subscribe to delivery.failed or poll GET /v1/messages?status=deferred;
      • decide whether the cause is fixed and whether a duplicate is acceptable;
      • retry explicitly.
      curl -X POST https://api.lockally.com/v1/messages/$ID/retry \
        -H "Authorization: Bearer $LOCKALLY_API_KEY"

      POST /v1/messages/retry retries in bulk. Both need send:write, and both reset the automatic attempt budget, so a message you retry by hand gets a fresh five attempts rather than inheriting an exhausted counter.

      What your own client should retry

      Retry a 5xx from our API. That is us failing, not your request, and the send did not happen. Exponential backoff with jitter.

      Retry a 429, after the Retry-After header. Every 429 we return carries one: 60 seconds for a rate cap, and the seconds remaining until UTC midnight for a warm-up cap. Honour it rather than guessing.

      Never retry a 400. The request is wrong and will be wrong next time.

      Never blind-retry a timeout. You do not know whether we accepted it. Use an idempotency key and retry with the same key, which is exactly what it is for: a replay inside the window returns the original response instead of sending twice. See Idempotency.

      const send = (body, key) =>
        fetch('https://api.lockally.com/v1/send', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.LOCKALLY_API_KEY}`,
            'Content-Type': 'application/json',
            'Idempotency-Key': key          // the SAME key on every attempt
          },
          body: JSON.stringify(body)
        });

      What never to retry

      A bounced message. The address was permanently rejected and is now suppressed, so a retry is either skipped or is you asking to damage your own reputation.

      An unconfirmed message. It very probably arrived, and nothing recorded it. Resending is a coin flip on sending a duplicate.

      Summary

      Failure Retried by Automatic
      Receiving server says 4xx The mail server Yes, for days
      We cannot reach the mail server pre-transmission Us Yes, immediately
      The relay refuses our submission (4xx, or a drop before the body) Us Yes, 5 attempts over about 5.5 hours
      Submission fails ambiguously at or after the body Nobody No, status deferred
      Retries exhausted Nobody No, status deferred
      Our API returns 5xx or 429 Your client Only if you write it
      Receiving server says 5xx Nobody, by design No