Send SMS with Twilio through Courier

Prerequisites

A Twilio account
An SMS-capable Twilio phone number
A Messaging Service containing that phone number
Your Twilio Account SID and Auth Token
Your Twilio Messaging Service SID

Setup

Get your Twilio credentials

In Twilio, open the console and copy your Account SID and Auth Token. The Messaging Service SID is on the Messaging Services page.

Configure in Courier

Open the in Courier, enter your Account SID, Auth Token, and Messaging Service SID, then click “Save.”

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: and .

Trial accounts

Twilio trial accounts may only send to verified numbers. See the Twilio trial account guide.

Overrides

covers the two levels and which one wins. Overrides change the request body Courier sends to Twilio. You can override any field on Twilio’s Messages.json endpoint, listed in the Twilio message resource reference.

Courier polls Twilio’s API for delivery status using the credentials you configured. Swapping those credentials with a config override stops delivery status events.

const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    data: {
      name: "Sarah Bennett",
    },
    providers: {
      twilio: {
        override: {
          body: {
            To: "+10987654321",
          },
          config: {
            accountSid: "<your Account SID>",
            authToken: "<your Auth Token>",
            messagingServiceSid: "<your Messaging Service SID>",
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "data": {
            "name": "Sarah Bennett",
        },
        "providers": {
            "twilio": {
                "override": {
                    "body": {
                        "To": "+10987654321",
                    },
                    "config": {
                        "accountSid": "<your Account SID>",
                        "authToken": "<your Auth Token>",
                        "messagingServiceSid": "<your Messaging Service SID>",
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "data": {
        "name": "Sarah Bennett"
      },
      "providers": {
        "twilio": {
          "override": {
            "body": {
              "To": "+10987654321"
            },
            "config": {
              "accountSid": "<your Account SID>",
              "authToken": "<your Auth Token>",
              "messagingServiceSid": "<your Messaging Service SID>"
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    data: {
      name: "Sarah Bennett"
    },
    providers: {
      twilio: {
        override: {
          body: {
            To: "+10987654321"
          },
          config: {
            accountSid: "<your Account SID>",
            authToken: "<your Auth Token>",
            messagingServiceSid: "<your Messaging Service SID>"
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
		Providers: shared.MessageProvidersParam{
			"twilio": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"To": "+10987654321",
					},
					"config": map[string]any{
						"accountSid": "<your Account SID>",
						"authToken": "<your Auth Token>",
						"messagingServiceSid": "<your Messaging Service SID>",
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("twilio", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "To", "+10987654321"
                    ),
                    "config", java.util.Map.of(
                        "accountSid", "<your Account SID>",
                        "authToken", "<your Auth Token>",
                        "messagingServiceSid", "<your Messaging Service SID>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'data' => [
      'name' => 'Sarah Bennett',
    ],
    'providers' => [
      'twilio' => [
        'override' => [
          'body' => [
            'To' => '+10987654321',
          ],
          'config' => [
            'accountSid' => '<your Account SID>',
            'authToken' => '<your Auth Token>',
            'messagingServiceSid' => '<your Messaging Service SID>',
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "twilio",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "To": "+10987654321"
                          },
                          "config": {
                            "accountSid": "<your Account SID>",
                            "authToken": "<your Auth Token>",
                            "messagingServiceSid": "<your Messaging Service SID>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}' \
  --message.providers '{"twilio": {"override": {"body": {"To": "+10987654321"}, "config": {"accountSid": "<your Account SID>", "authToken": "<your Auth Token>", "messagingServiceSid": "<your Messaging Service SID>"}}}}'

With Courier MCP, send my template to +12345678901 through Twilio with different credentials.

The Twilio API uses PascalCase field names (Body, To, From). Courier auto-capitalizes body override keys for backwards compatibility, so both "to" and "To" work.

Troubleshooting

Error 30003: Destination Unavailable

The destination handset was unreachable.

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

Error 30005: Unknown or Inactive Destination

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

Error 30006: Landline or Unreachable Carrier

The message went to a landline or an unreachable carrier.

Use the Lookup API to check if the number is a landline
Try an alternative phone number

Error 30007: Message Filtered

Twilio or the carrier filtered the message for a policy violation.

Ensure compliance with Twilio’s Messaging and Acceptable Use Policies
Secure account credentials
Open a support request if you suspect a mistake

Error 30008: Unknown Delivery Failure

The 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

Error 20003: Permission Denied

No 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

Error 20404: Resource Not Found

The resource doesn’t exist or isn’t available.

Check that the resource exists and verify API case-sensitivity
Verify Account SID and base URL

Error 21211: Invalid To Phone Number

The recipient number is invalid or formatted incorrectly.

Ensure E.164 format with the correct country code
Avoid calling or messaging a Twilio number from itself

Error 21408: Permission Not Enabled for Region

Enable permission in Geo-Permissions settings

Error 21610: SMS STOP Filter

The recipient unsubscribed with the “STOP” keyword.

Request the recipient text “START” to resubscribe
Ensure you have consent for messaging

Error 11200: HTTP Retrieval Failure

Twilio could not retrieve content from the given URL.

Verify web server status and accessibility
Check for network issues
Ensure proper server configuration for static resources

Error 12300: Invalid Content-Type

Twilio could not 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

Provider details

twilio

Courier recommends routing to the channel. Naming this key in routing.channels instead is supported, and sends through just this provider.

Send to a specific provider

When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

Get started

Available integrations

Send SMS with Twilio through Courier

Prerequisites

Setup

Trial accounts

Overrides

Troubleshooting

Provider details

Send to a specific provider

​Prerequisites

​Setup

​Trial accounts

​Overrides

​Troubleshooting

​Provider details

Send to a specific provider

Prerequisites

Setup

Trial accounts

Overrides

Troubleshooting

Provider details