Take More Control of Outbound Messages Using Validity Period


Better late than never…or is it? For some applications, it may be better for a message to fail completely than to arrive late. Now you have more control over your messages using  validity period. This period dictates how long you want Twilio to try to deliver your messages before failing with an error.

Imagine you subscribe to SMS traffic alerts for your daily evening commute home. You time your departure based on the alerts, but that day you get nothing. You drive off uninformed and steer right into Carmageddon 2.0. As you pull into your driveway three hours later, you get the text you were expecting three hours earlier. At this point the text serves no purpose other than to annoy you.

You, the developer, can save your users from this fate. Configure a validity period on those time-sensitive SMS messages.

Why Messages May Arrive Late

To better understand validity period, let’s look at some of the reasons messages may arrive late in the first place:

  • Not enough messages per second (MPS): Long code phone numbers can send 1 MPS by default in the US and Canada. Twilio Short Codes can handle up to 100 MPS by default in the US, Canada, and the UK (more info in this blog post). As a safeguard, Twilio handles carrier compliance for you by automatically rate limiting messages into the carrier network. So if your outbound messages are queueing at a higher rate, your messages will pile up. After sitting in the queue beyond the default validity period of 4 hours – or time you set – those messages will fail and won’t be sent.
  • Service outages: As hard as we work to prevent them, service disruptions can happen. Your message may get enqueued when the service comes back up, which could result in delays. Validity period lets you rest assured that you’re covered in that instance.

How to Set Validity Period


To set validity period, include the optional ValidityPeriod= parameter in your HTTP POST request to /2010-04-01/Accounts/{AccountSid}/Messages with the number of seconds that the message can remain in a Twilio queue. Valid values are between 1 and 14400 seconds< (the default), however we recommend avoiding validity periods of less than 5 seconds.   After exceeding this time limit, the message will fail and a POST request will later be made to your Status Callback URL. Please note that Twilio cannot guarantee that a message will not be queued by the carrier after they accept the message.   Finally, in case you needed one more reason to set validity period - you won’t pay for any messages that reach the validity period timer.   We can’t wait to see what you build!

  • http://lumberj.github.io/ Alan Cohen

    > Please note that Twilio cannot guarantee that a message will not be queued by the carrier after they accept the message.

    Does this mean it’s possible that the validity period expires, and Twilio still sends the message on to the carrier and the carrier accepts it?

    • Ari Sigal

      Good question Alan, what I was trying to say was that Twilio would only send the message to the carrier before the validity period expires. However, its possible that the carrier then delivers the message after the validity period has expired. Does that make sense? Feel free to email me with questions ari [at] twilio [dot] com.

      • http://lumberj.github.io/ Alan Cohen

        Thanks, Ari. This makes sense

      • Anthony Mary Enright

        I’m confused .. but I have a cheap Obama phone. Old phone. Mine says validity period. Maximum.. what does that mean.. my husbands phone in that same spot same phone has nothing at all there.. it doesn’t even show the word validity but when I text someone they get it right away but when someone sends me a text I don’t get it at all. But I can make and receive all phone calls. Please email me at maryandant36gmail.com I need your help please!(:

        • Ari Sigal

          Hi Anthony, I just followed up via email!

          • Anthony Mary Enright

            ? What does it mean though

          • Ari Sigal

            Hey Anthony, the email you gave me bounced, is there another email address I can try?
            I’m not sure if I understand your question. Have you built an application with the Twilio Programmable Messaging API? This blog post is talking about a new feature that you can use to set how long Twilio will try to deliver a message before failing.

  • Viktor Gergely Bán

    Is this also available for SMS sent using TwiML (i.e. reply to an inbound SMS)?

    • Ari Sigal

      Hey Viktor, this isn’t available today, but it’s an interesting idea. Would love to learn more about what you’re working on. Feel free to email me directly as well ari [at] twilio [dot] com.

  • Kanefire

    How do we restrict the time in which SMS are sent? Our cron (that triggers sending messages) runs 3am to avoid conflicts with business operations, however, we don’t want the messages sent then as people are sleeping. How do we insure they are only sent between the hours 8a-8p, whatever timezone?