# Messaging and 10DLC registration

`POST /v1/messages {to,body,line?,purpose?,category?,approval?,smart_encoding?}`
uses `sms.send`; a project key names `agent`. Message content is 1–1600
characters with a maximum estimated ten parts. Read replies with
`sms.receive` via `/messages`, `/messages/{msg}`, or a conversation query
`?with=%2B12125550101`.

## Segments and costs

GSM-7 single/concatenated capacity is 160/153 septets; extension
characters (`^{}\\[~]|€`) use two. UTF-16 capacity is 70/67 units; emoji
consume surrogate pairs. Provider-reported parts determine actuals.

`POST /policies/check {action:"sms.send",to,body,smart_encoding?}` returns
segment/encoding and cost estimates without reserving or sending.
`smart_encoding: true` substitutes typographic quotes, dashes, ellipsis
and nonbreaking space with ASCII equivalents — other Unicode and emoji are
preserved, and the returned body is exactly what was sent.

Failed or unconfirmed delivery may still cost money. `cost_micros: null`
with `billing_status: pending` means unknown cost, not zero.

## Customer-scoped 10DLC

US application-to-person messaging requires each business to register its
own brand and campaign with the carrier. An owner or developer session
(key with `lines:write`):

1. Read `/orgs/{org}/messaging` and quote expected carrier fees with
   `/messaging/quote?usecase=LOW_VOLUME_MIXED`.
2. POST `/messaging/brand` with the actual business identity
   (`entityType`, `displayName`, `country`, `email`, `vertical`, …).
   Registration data is sent to the carrier to represent the business.
3. For sole-proprietor verification, request an OTP
   (`/messaging/otp/request`) and verify the human-received code
   (`/otp/verify {code}`).
4. Once `brand_ready`, POST `/messaging/campaign` with `usecase`,
   `description`, sample messages, help/opt-out wording, and your
   privacy-policy and terms links.
5. Poll until the campaign and number assignment are active.

Each business has its own brand/campaign/profile — tenants never share a
global registration. Campaign auto-renewal is disabled: an expired
campaign needs an explicitly funded resubmission. `409
a2p_registration_pending` means no SMS was attempted; onboarding can take
days to weeks, and retrying sends does not change carrier filtering.