> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Send your first SMS

> Connect an SMS provider such as Twilio, store an E.164 phone number on the profile, and send a text, then plan for segments, registration, and opt-out.

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

> [!NOTE]
>
> 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, which is the most common reason a first send fails.

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* An account with an SMS provider, such as [Twilio](https://www.twilio.com/), and a number that can send
* A phone you can receive a text on

## Send it

**1. Connect your SMS provider**

In [Integrations](https://app.courier.com/integrations/catalog), 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.

[Twilio](https://www.courier.com/docs/integrations/sms/twilio.md) covers the credential fields, and [SMS providers](https://www.courier.com/docs/integrations/sms/overview.md) lists every alternative.

**2. 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. [Users](https://www.courier.com/docs/recipients/overview.md#what-each-channel-needs) covers the field every other channel reads.

```javascript Node.js highlight={2} theme={null}
await client.profiles.create("user_123", {
  profile: { phone_number: "+12025550156" },
});
```

```python Python highlight={3} theme={null}
client.profiles.create(
    "user_123",
    profile={"phone_number": "+12025550156"},
)
```

```bash cURL highlight={4} theme={null}
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" } }'
```

```ruby Ruby highlight={3} theme={null}
courier.profiles.create(
  "user_123",
  profile: {phone_number: "+12025550156"}
)
```

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

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("phone_number", JsonValue.from("+12025550156"))
        .build())
    .build();

client.profiles().create(params);
```

```php PHP highlight={3} theme={null}
$client->profiles->create(
  'user_123',
  profile: ['phone_number' => '+12025550156'],
);
```

```csharp C# highlight={7} theme={null}
await client.Profiles.Create(
    "user_123",
    new()
    {
        Profile = new Dictionary<string, JsonElement>
        {
            { "phone_number", JsonSerializer.SerializeToElement("+12025550156") },
        },
    }
);
```

```bash CLI highlight={3} theme={null}
courier profiles create user_123 \
  --api-key "$COURIER_API_KEY" \
  --profile '{"phone_number": "+12025550156"}'
```

```text MCP theme={null}
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` isn't a valid recipient, and `+12025550156` is.

**3. Send the text**

Route to `sms` and Courier picks the provider you connected.

```javascript Node.js highlight={4} theme={null}
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." },
  },
});
```

```python Python highlight={4} theme={null}
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."},
    },
)
```

```bash cURL highlight={7} theme={null}
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." }
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
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."}
  }
)
```

```go Go highlight={8} theme={null}
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.",
			},
		},
	},
})
```

```java Java highlight={6} theme={null}
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());
```

```php PHP highlight={4} theme={null}
$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.'],
  ],
);
```

```csharp C# highlight={6} theme={null}
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);
```

```bash CLI highlight={4} theme={null}
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."}'
```

```text MCP theme={null}
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

**1. Check the phone**

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

**2. Read the status**

Open [Logs](https://app.courier.com/logs). `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. [Why a message is UNROUTABLE](https://www.courier.com/docs/send/statuses.md#why-a-message-is-unroutable) 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 isn't optional.** Carriers expect STOP to work. Courier applies [preferences](https://www.courier.com/docs/recipients/preferences/overview.md) on every send, so wire your provider's opt-out webhook to them rather than tracking it separately.
