Using MaxPrice with Twilio SMS

The MaxPrice parameter is an option that sets a high-end limit on your cost for outbound messages when using Twilio Programmable SMS. When MaxPrice is included with your outbound message API requests, Twilio will only send messages that are this price or lower. This can be a helpful tool to avoid sending messages to locations that have a high cost.

How Does MaxPrice Work?

Messages that would cost more your MaxPrice value will have the status Failed, and return an Error Code property of 30010. These messages will not be sent or charged on your project.

Notice: MaxPrice limits do not automatically adjust when adding media (MMS) or using multiple segments. Either of these actions would make a message fail if the MaxPrice value is set for the standard single segment SMS price.

Send an SMS with MaxPrice

The MaxPrice parameter is called out in your API request for sending a message. Here’s an example cURL script:

curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
--data-urlencode 'Body=Hello from my Twilio line!' \
--data-urlencode "MaxPrice=0.0075" \
--data-urlencode 'StatusCallback=https://mysite.com/callbacks \
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

This example requests to send an outbound message from the sender (212) 555-1234 (+12125551234) to the recipient at (310) 555-5555 (+13105555555) with the message Hello from my Twilio line!. The MaxPrice value is set for $0.0075, which tells Twilio to only send the message if it is this price or below. Messages above this price will have the status Failed, and be flagged with Error 30010.

To make this script work for you, make the following updates, and then paste it into a terminal window:

  • Line 1 update with your Account SID
  • Line 2 update with a valid destination
  • Line 3 update with a valid caller number
  • Line 4 update with the desired message body text
  • Line 5 update with the desired maximum message price value
  • Line 6 update with your status callback url
  • Line 7 update with your Account SID and Auth Token

For more details, including code samples using our Helper Library SDKs, please see Create a Message Resource (Twilio Docs).

API Explorer

The MaxPrice parameter is also available from the Create a Message page in the Console API Explorer. Just login to your Twilio account, and then select Runtime > API Explorer. Click here to try it yourself: API Explorer Create a Message.

Additional Resources

Have more questions? Submit a request
Powered by Zendesk