Skip to main content

​
Setup

You will need a Twilio account with a phone number that has SMS capabilities and a Messaging Service configured. If you don’t have these yet, follow Twilio’s guides:
  1. Purchase a phone number with SMS capability.
  2. Create a Messaging Service and add your phone number to it.
In Courier, navigate to the Twilio Integration page and enter your:
  • Account SID and Auth Token from the Twilio Console Dashboard
  • Messaging Service SID from your Messaging Service configuration page
Click “Save” to complete the integration.
Twilio trial accounts may limit sending to verified numbers only. See the Twilio trial account guide for details.

​
Profile Requirements

To deliver a message to a recipient over Twilio, Courier must be provided the recipient’s SMS-compatible phone number. This value should be included in the recipient profile as phone_number. 
{
  "message": {
    "to": {
      "phone_number": "+12025550156"
    }
  }
}

​
Overrides

Overrides can be used to change the request body that Courier uses to send an SMS message. You can override any of the fields supported by Twilio’s Messages.json endpoint (see all request body fields here).
Courier relies on configured credentials for status polling. Using config overrides to swap credentials will prevent Courier from polling Twilio’s API for delivery status events.
{
  "message": {
    "template": "NOTIFICATION_TEMPLATE_ID",
    "to": {
      "phone_number": "+12345678901"
    },
    "data": {
      "name": "Katherine Pryde"
    },
    "providers": {
      "twilio": {
        "override": {
          "body": {
            "To": "+10987654321"
          },
          "config": {
            "accountSid": "<your Account SID>",
            "authToken": "<your Auth Token>",
            "messagingServiceSid": "<your Messaging Service SID>"
          }
        }
      }
    }
  }
}
The Twilio API uses PascalCase field names (Body, To, From). Courier auto-capitalizes override body keys for backwards compatibility, so both "to" and "To" work in the body override.

​
Troubleshooting

Message failed to deliver due to unreachable destination.
  • Send another test message via the Twilio API Explorer
  • Check device status, signal strength, and carrier network
  • Use the “Fallback to Long Code” feature if needed
  • Open a Twilio support request if the issue persists
Carrier issue, signal loss, or inactive number.
  • Verify the number is active and formatted correctly (E.164)
  • Check device status and signal
  • Test with other devices on the same carrier
Message sent to a landline or unreachable carrier.
  • Use the Lookup API to check if the number is a landline
  • Try an alternative phone number
Messages filtered by Twilio or carrier due to policy violations.
  • Ensure compliance with Twilio’s Messaging and Acceptable Use Policies
  • Secure account credentials
  • Open a support request if you suspect a mistake
Message failed for unknown reasons.
  • Test with a simpler message and a different sender ID
  • Check device roaming status
  • Contact Twilio support with recent message SIDs if the issue persists
Lack of permission to access the requested resource.
  • Verify the correct Auth Token and Account SID combination
  • Check account type (sub-account vs master, test vs live)
  • Confirm API Key and Auth Token are valid
Requested resource doesn’t exist or is unavailable.
  • Check that the resource exists and verify API case-sensitivity
  • Verify Account SID and base URL
Incorrectly formatted or invalid recipient number.
  • Ensure E.164 format with the correct country code
  • Avoid calling or messaging a Twilio number from itself
Permission not enabled for the recipient’s region.
Recipient previously unsubscribed using the “STOP” keyword.
  • Request the recipient text “START” to resubscribe
  • Ensure you have consent for messaging
Failed to retrieve content from the given URL.
  • Verify web server status and accessibility
  • Check for network issues
  • Ensure proper server configuration for static resources
Twilio unable to process the URL’s Content-Type.
  • Verify the correct Content-Type is returned by the server
  • Ensure the URL refers to a valid, acceptable resource