· Natrajan
How to retry Twilio SMS follow-up safely without sending duplicates
Learn to configure per-step retries and idempotency keys so failed SMS follow-ups are retried without sending duplicate messages.

When a lead replies to a form, your first instinct is to fire off an SMS reminder or a quick thank-you note. But if the Twilio request times out, returns a 5xx error, or the network hiccups, you risk sending the same message twice — or, worse, never sending it at all. The result is a broken follow-up experience and wasted trust.
This guide shows owners and agency operators how to configure reliable retries for Twilio SMS steps while ensuring that each lead receives only one message, even when the underlying API call is ambiguous. The approach works for any outcome-based automation, whether you’re confirming a meeting, delivering a promo code, or simply acknowledging a new lead.
1. Why “run-based” retries break SMS follow-up
Most automation tools treat every step as a fire-and-forget operation. If a step fails, the platform simply runs it again. With SMS, that can mean:
| Failure type | What the platform does | Why duplicates appear |
|---|---|---|
| Network timeout | Retries immediately | The first request may have actually succeeded, but the platform never saw the response. |
| 5xx server error | Retries until success | Twilio may have processed the message on the first attempt, then returned an error on the retry. |
| Ambiguous client error (e.g., 429) | Retries with back-off | The rate limit may have been applied after the message was already queued. |
If you base success on “the step finished”, you can’t tell whether the lead actually got the SMS. Outcome-based automation solves this by requiring a trusted event—a signed webhook from Twilio confirming delivery—before marking the outcome as achieved.
2. Define the outcome and its success criteria
Before you build the workflow, write down the outcome you care about:
| Element | Example for an SMS follow-up |
|---|---|
| Start event | New lead created via form, CSV import, or inbound email. |
| Success events | Twilio message.delivered webhook (signed) confirming the exact message ID. |
| Failure events | Twilio message.failed webhook, or no webhook received within the deadline. |
| Deadline | 5 minutes after the lead is created (hypothetical example). |
Only when the signed message.delivered webhook arrives does the outcome count as achieved. A completed workflow that never receives that webhook stays in “in-progress” and can trigger alerts.
3. Configure the Twilio SMS step with an idempotency key
OutcomeOS lets you set an idempotency key for any step. The key is a deterministic string that uniquely identifies the action for a given lead. For an SMS follow-up, a good key combines the lead ID and the message template:
sms-followup-{lead_id}-{template_hash}Steps to set it up
- Create the SMS step – choose the Twilio integration, fill in the recipient number and message body.
- Add the idempotency key – in the step settings, enable “Idempotency” and paste the expression above (OutcomeOS provides a simple templating language).
- Define the retry policy – select a maximum of 3 attempts, with exponential back-off (e.g., 10 s, 30 s, 1 min).
- Map the success event – tell OutcomeOS to listen for the signed
message.deliveredwebhook from Twilio and match it to the same idempotency key.
When the first attempt succeeds, Twilio returns a message SID and sends the signed webhook. OutcomeOS records the SID, stores the idempotency key, and won’t resend even if the step is retried later. If the first attempt fails ambiguously, the retry uses the same key, so Twilio treats the second request as a duplicate and returns the original SID instead of sending a new SMS.
4. What to do when a step lands in “Requires attention”
If a step fails with a non-idempotent error (for example, a malformed phone number) the platform cannot safely retry. OutcomeOS automatically moves the lead to a “Requires attention” state:
- An email alert (and optional SMS via Twilio) is sent to the designated owner, including the lead’s name, phone number, and the error details.
- The dashboard shows the lead under “Pending – Manual review”.
From there you can correct the data or decide to skip the SMS altogether. Because the outcome is still waiting for a trusted success event, you retain full visibility of which leads are truly uncontacted.
5. Concrete example with numbers
Imagine a boutique fitness studio that receives 120 new sign-ups per day through a website form. Their automation sends a welcome SMS with a discount code.
| Metric | Without idempotency | With idempotency |
|---|---|---|
| SMS sent (raw attempts) | 150 (30 % duplicate sends) | 120 (no duplicates) |
| Twilio cost @ $0.0075 per SMS | $1.13 | $0.90 |
| Customer complaints about duplicate texts | 12 per week | 0 |
| Follow-up success rate (delivered webhook) | 92 % (some duplicates never delivered) | 98 % (retries recover 6 % of failures) |
| Time spent fixing duplicates (minutes) | 45 min/week | 0 min/week |
The studio saves $0.23 per day on SMS fees and eliminates a source of frustration for both staff and members. More importantly, the outcome success rate climbs to 98 %, giving the owner confidence that every new lead receives the promised discount.
6. Quick checklist for safe SMS retries
- Write the outcome definition: start event, success webhook, failure events, deadline.
- Build the Twilio SMS step and enable an idempotency key that uniquely identifies the lead + message.
- Set a per-step retry policy (max attempts, back-off).
- Map the
message.deliveredsigned webhook as the success proof. - Test with a single lead: force a timeout, verify only one SMS is received.
- Configure email (and optional Twilio SMS) alerts for “Requires attention” cases.
- Monitor the dashboard for pending outcomes and adjust the deadline if needed.
7. How OutcomeOS makes it effortless
OutcomeOS treats automation as outcome-driven, not run-driven. By requiring a trusted event—such as a signed Twilio webhook—to mark success, you can confidently retry steps without risking duplicate messages. The built-in idempotency key system, per-step retry configuration, and clear alerts keep your SMS follow-up reliable and transparent.
Ready to stop guessing whether your leads got the message? Sign up for a free Starter account and see the difference. Compare plans and features at outcomeos.cloud/compare.