Send your first SMS

Three things stand between you and a delivered text: a connected provider, a phone number on the profile, and a send.

Unlike email, SMS has no default provider in Test. A new workspace can email you immediately, but a text needs your own Twilio or other SMS account connected first. That is the most common reason a first SMS goes nowhere.

Prerequisites

An account with an SMS provider, such as Twilio, and a number that can send
A phone you can receive a text on

Send it

Connect your SMS provider

In , add your provider and paste its credentials. For Twilio that is the Account SID, Auth Token, and a Messaging Service SID or sending number.Integrations are per environment, so connect it in the same environment your API key belongs to. A provider added in Production does nothing for a Test key. covers the credential fields, and lists every alternative.

Put a phone number on the profile

SMS addresses a recipient by phone_number, and it must be E.164: a plus sign, country code, then the number, with no spaces, dashes, or brackets. covers the field every other channel reads.

await client.profiles.create("user_123", {
  profile: { phone_number: "+12025550156" },
});

client.profiles.create(
    "user_123",
    profile={"phone_number": "+12025550156"},
)

curl -X POST https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile": { "phone_number": "+12025550156" } }'

courier.profiles.create(
  "user_123",
  profile: {phone_number: "+12025550156"}
)

_, err := client.Profiles.New(context.TODO(), "user_123", courier.ProfileNewParams{
	Profile: map[string]any{"phone_number": "+12025550156"},
})

ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("phone_number", JsonValue.from("+12025550156"))
        .build())
    .build();

client.profiles().create(params);

$client->profiles->create(
  'user_123',
  profile: ['phone_number' => '+12025550156'],
);

await client.Profiles.Create(
    "user_123",
    new()
    {
        Profile = new Dictionary<string, JsonElement>
        {
            { "phone_number", JsonSerializer.SerializeToElement("+12025550156") },
        },
    }
);

courier profiles create user_123 \
  --api-key "$COURIER_API_KEY" \
  --profile '{"phone_number": "+12025550156"}'

With Courier MCP, set the phone number +12025550156 on user_123.

A number without the country code is the single most common cause of an UNROUTABLE SMS. 2025550156 is not a valid recipient, and +12025550156 is.

Send the text

Route to sms and Courier picks the provider you connected.

const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    routing: { method: "single", channels: ["sms"] },
    content: { title: "Delivery update", body: "Your order is out for delivery." },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "routing": {"method": "single", "channels": ["sms"]},
        "content": {"title": "Delivery update", "body": "Your order is out for delivery."},
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "routing": { "method": "single", "channels": ["sms"] },
      "content": { "title": "Delivery update", "body": "Your order is out for delivery." }
    }
  }'

response = courier.send_.message(
  message: {
    to: {user_id: "user_123"},
    routing: {method: "single", channels: ["sms"]},
    content: {title: "Delivery update", body: "Your order is out for delivery."}
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("sms")}},
		},
		Content: courier.SendMessageParamsMessageContentUnion{
			OfElementalContentSugar: &shared.ElementalContentSugarParam{
				Title: "Delivery update",
				Body:  "Your order is out for delivery.",
			},
		},
	},
})

SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("sms")))
        .build())
    .content(ElementalContentSugar.builder()
        .title("Delivery update")
        .body("Your order is out for delivery.")
        .build())
    .build();

client.send().message(SendMessageParams.builder().message(message).build());

$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'routing' => ['method' => 'single', 'channels' => ['sms']],
    'content' => ['title' => 'Delivery update', 'body' => 'Your order is out for delivery.'],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Routing = new() { Method = "single", Channels = ["sms"] },
        Content = new ElementalContentSugar
        {
            Title = "Delivery update",
            Body = "Your order is out for delivery.",
        },
    },
};

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

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.routing '{"method": "single", "channels": ["sms"]}' \
  --message.content '{"title": "Delivery update", "body": "Your order is out for delivery."}'

With Courier MCP, send user_123 an SMS saying their order is out for delivery.

SMS ignores title and sends body, so write the body to stand alone. Other channels use both, which is why the shorthand carries them together.

Verify

Check the phone

The text arrives from the number or messaging service you connected.

Read the status

Open . SENT means the provider accepted it. DELIVERED means the carrier confirmed it, and only some providers report that.

If the message is UNROUTABLE, the profile had no phone_number Courier could use. Check the number is E.164 and that the profile you sent to is the one you wrote. lists every reason.

What changes in production

Numbers need provisioning. Trial accounts at most providers only text verified numbers, which is a provider restriction rather than a Courier one. Long messages split. Over 160 GSM-7 characters a message becomes multiple segments and is billed per segment. Unicode, including emoji, drops the limit to 70. Regulations vary. Several countries require sender registration, and the United States requires it for application-to-person traffic. Your provider handles that registration, so check its rules before a launch. Opt-out is not optional. Carriers expect STOP to work. Courier applies on every send, so wire your provider’s opt-out webhook to them rather than tracking it separately.

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Send your first SMS

Prerequisites

Send it

Verify

What changes in production

​Prerequisites

​Send it

​Verify

​What changes in production

Prerequisites

Send it

Verify

What changes in production