# Send SMS · One API, segment-aware, idempotent One message. A visible outcome. Example send Explore acceptance and a later carrier receipt. This example does not send a text; delivery does not establish that someone read it. ## Test your first SMS integration. ## From the language you already use. Sending is the core of the [Bird SMS API](/sms-api). The example below shows the request shape. For a controlled test, replace the recipient with the documented sandbox number +15005550006. Set up a suitable US sender and enable the destination first, then verify acceptance and delivery events before sending to customers. **Node.js**: `npm install @messagebird/sdk` ```typescript const msg = await bird.sms.send({ from: "+15557654321", to: "+14155550100", text: "Your verification code is 123456.", category: "authentication", }); console.log(msg.id, msg.status); ``` Examples: [TypeScript](/de-de/sms-api/features/sending.ts.md) · [Python](/de-de/sms-api/features/sending.py.md) · [Go](/de-de/sms-api/features/sending.go.md) · [PHP](/de-de/sms-api/features/sending.php.md) · [CLI](/de-de/sms-api/features/sending.cli.md) · [MCP](/de-de/sms-api/features/sending.mcp.md) · [cURL](/de-de/sms-api/features/sending.curl.md) An SMS send delivers the text you supply. For login and account verification, use [Bird Verify](/verify-api) to generate, expire and check codes as part of a verification flow. ## Build on a clear sending contract. Prepare the request and follow the result. - **01** Segment counting before send. Bird reports the calculated encoding and segment count in its response. Use the segment calculator to inspect a draft before you submit it. - **02** GSM-7 and Unicode, decided for you. Characters determine the encoding. GSM-7 fits 160 units in a single segment; Unicode fits 70. Multipart messages reserve space for reassembly, and emoji can occupy more than one unit. - **03** Batch in one call. Submit up to 100 independent messages in one batch. Validation happens before enqueueing; each accepted message then has its own outcome. - **04** Retry with an idempotency key. Use one idempotency key per logical request and reuse it for an identical retry. The retained API response can be replayed; this does not guarantee exactly-once carrier delivery. - **05** Delivery events for your application. Subscribe to accepted, sent and terminal outcome events. Verify signatures, deduplicate webhook retries and use message reads to investigate missing or delayed observations. ## Know the segment count before submission. GSM-7 fits 160 septets in a single segment; UCS-2 fits 70 code units. Multipart capacity is 153 or 67 respectively. Extended GSM-7 characters use two septets and emoji may use two code units. Bird returns encoding and segments at acceptance; the applicable rate and any carrier fee are priced separately. **segments.ts** ```typescript const { data, error } = await bird.sms.send({ from: "Bird", to: "+31612345678", text: "Your code is 123456.", category: "authentication", }).safe(); if (error) throw error; console.log(data.segments); // → { characters: 20, count: 1, encoding: "GSM_7BIT" } ``` ## One message or a hundred, one call. Batch up to 100 independent messages, each with its own recipient and text. Invalid input rejects the request before enqueueing. After a successful 202 response, processing and delivery can succeed or fail separately for each SMS. Reuse the request and idempotency key when retrying within the documented retention window. **reminders.ts** ```typescript const { data: batch, error } = await bird.sms .sendBatch( users.map((u) => ({ from: "Bird", to: u.phone, text: `Hi ${u.name}, your appointment is tomorrow at ${u.time}.`, })), { idempotencyKey: `reminders-${runId}` }, ) .safe(); if (error) throw error; console.log(`queued ${batch.data.length} messages`); ``` ## Go deeper in the docs. Wire up [webhooks](/docs/guides/webhooks), make every send safe to retry with [idempotency keys](/docs/guides/idempotency), and read the [error reference](/docs/guides/errors) so you handle each failure the right way. ## Questions before you build ### Do I choose the sender? For a free-text send, provide a sender your workspace can use in the destination and the appropriate message category. A system-template send resolves its category and sender from the template. ### How do retries avoid a duplicate text? Provide an idempotency key and reuse it for a retry of the same request. A send without that key can be treated as a new message. ### Does accepted mean delivered? No. A 202 response means the API accepted the request. Follow the message record and signed events for the carrier-reported outcome. A delivery receipt does not establish that the recipient read the text. ### Is a batch the same as a broadcast? A batch contains up to 100 independent messages, each with its own recipient and body. A broadcast is an audience campaign with shared content and a managed send lifecycle. Choose the workflow that matches your job. ## The rest of the SMS platform One API, one set of keys. Explore the other capabilities. - [Numbers](/sms-api/features/numbers): Long codes, short codes, toll-free, and alphanumeric sender IDs. - [Two-way](/sms-api/features/two-way): Inbound SMS and conversational replies as HMAC-signed webhooks. - [Compliance](/sms-api/features/compliance): A2P 10DLC registration, opt-out keywords and sender-ID rules. - [Routing](/sms-api/features/routing): Destination controls, carrier handoff and delivery evidence. - [Analytics](/sms-api/features/analytics): Delivery outcomes, failure reasons and latency from carrier receipts. - [SMS API overview](/sms-api): The full SMS API: sending, numbers, two-way, compliance, routing, and analytics. - [SMS resource library](/sms-api/resources): Find guides, explained answers and tools for your next step. ## Scale without losing control. Organize teams in workspaces, control API access, and trace changes through audit logs. Harbor Organization Workspaces Production Sandbox ### Delivery agent API key · Customer operations team Active Permissions Access Email Read & write SMS Read & write WhatsApp Read Read & write AL Alex Lee Admin Permissions updated ### Audit log Production API key updated Alex Lee · 09:42:18 UTC Workspace Production Resource Delivery agent WhatsApp Read Read & write Succeeded [Workspaces](/docs/guides/workspaces)[Team roles](/docs/guides/users-teams-roles)[API authentication](/docs/guides/authentication) [Explore Enterprise](/enterprise) ## Start with SMS. Build across channels with Bird. [Get started](/dashboard/signup?returnTo=%2Fdashboard%2Fw%2Fsms%2Fonboarding) · [Contact Sales](/demo?product=sms) [Email](/email-api) · [SMS](/sms-api) · [WhatsApp](/whatsapp-api) · [Apple Messages](/apple-messages-api) · [Voice](/voice-api) ## Related resources - [Sending your first SMS](/learn/sms/sending-your-first-sms) (video) - [Sending SMS](/docs/guides/sms/sending-sms) (docs) - [What does SMS mean?](/explained/sms/what-does-sms-mean) (answer) - [Build your first integration](/learn/paths/integration) (course) [Get an implementation brief](/learn/workspace?topic=sms)