> ## Documentation Index > Fetch the complete documentation index at: https://docs.xerobi.com/llms.txt > Use this file to discover all available pages before exploring further. # Send SMS > Send a single SMS message to one recipient. **Features:** - Automatic route optimization based on message type - Support for scheduled delivery - Unicode and emoji support - Automatic message segmentation - Delivery status tracking **Message Length:** - Standard (GSM-7): 160 characters per segment - Unicode: 70 characters per segment - Each additional segment reduces by 7 characters for concatenation header **Best Practices:** - Use OTP route for time-sensitive verification codes - Include sender ID for brand recognition - Keep messages concise to minimize segments - Use templates for consistent messaging - Implement idempotency for reliable retries ## OpenAPI ````yaml POST /messages openapi: 3.1.0 info: title: Xerobi SMS Gateway API version: '2026-01-01' description: >- A modern, developer-friendly SMS Gateway API supporting transactional, OTP, promotional and bulk messaging. ## Overview The Xerobi SMS Gateway API enables you to send SMS messages programmatically with support for: - **Transactional SMS**: Account notifications, confirmations, alerts - **OTP Messages**: One-time passwords with optimized delivery routes - **Promotional SMS**: Marketing campaigns and announcements - **Bulk Messaging**: Send to thousands of recipients efficiently - **Templates**: Reusable message templates with variable substitution - **Webhooks**: Real-time delivery status notifications ## Authentication Authenticate using your API key as a Bearer token: ```bash curl -H "Authorization: Bearer sk_live_xxxxx" \ -H "Xerobi-Version: 2026-01-01" \ https://api.hixbe.com/sms/messages ``` **API Key Types:** - `sk_live_*` - Production keys for live messaging - `sk_test_*` - Test keys for development (no actual SMS sent) Get your API keys from the [Xerobi Dashboard](https://dashboard.hixbe.com/api-keys). ## Rate Limits - **Standard accounts**: 100 requests/minute - **Business accounts**: 1,000 requests/minute - **Enterprise accounts**: Custom limits Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Requests remaining - `X-RateLimit-Reset`: Unix timestamp when limit resets ## Message Routes Different routes optimize for delivery speed, reliability, and cost: | Route | Use Case | Delivery Speed | Cost | |-------|----------|----------------|------| | **otp** | One-time passwords | < 5 seconds | Premium | | **transactional** | Notifications, alerts | < 30 seconds | Standard | | **promotional** | Marketing messages | < 2 minutes | Economy | ## Phone Number Format Phone numbers must be in international format without + or spaces: - ✅ Correct: `8801712345678` (Bangladesh) - ✅ Correct: `14155551234` (USA) - ❌ Incorrect: `+880 171 234 5678` - ❌ Incorrect: `01712345678` ## Idempotency Include `Idempotency-Key` header to safely retry requests: ```bash curl -H "Idempotency-Key: unique-key-123" \ -H "Authorization: Bearer sk_live_xxxxx" \ ... ``` ## Webhooks Receive real-time delivery updates via webhooks. Events include: - `message.queued` - Message accepted and queued - `message.sent` - Message sent to carrier - `message.delivered` - Successfully delivered - `message.failed` - Delivery failed ## Support Need help? Contact us: - Email: support@xerobi.com - Documentation: https://developer.hixbe.com - Status: https://status.hixbe.com contact: name: Xerobi Developer Support url: https://developer.hixbe.com email: support@xerobi.com termsOfService: https://hixbe.com/terms license: name: Commercial url: https://hixbe.com/license servers: - url: https://api.hixbe.com/sms description: Production Server - url: https://api-sandbox.hixbe.com/sms description: Sandbox Server (test mode) security: - bearerAuth: [] tags: - name: Messages description: Send and track individual SMS messages - name: Bulk description: CSV and list-based bulk sending for campaigns - name: Senders description: Manage sender IDs and registration - name: Templates description: Create and manage message templates with variables - name: Reports description: Delivery statistics and usage analytics - name: Account description: Balance, usage limits and account profile - name: Webhooks description: Configure delivery report callbacks paths: /messages: post: tags: - Messages summary: Send SMS description: >- Send a single SMS message to one recipient. **Features:** - Automatic route optimization based on message type - Support for scheduled delivery - Unicode and emoji support - Automatic message segmentation - Delivery status tracking **Message Length:** - Standard (GSM-7): 160 characters per segment - Unicode: 70 characters per segment - Each additional segment reduces by 7 characters for concatenation header **Best Practices:** - Use OTP route for time-sensitive verification codes - Include sender ID for brand recognition - Keep messages concise to minimize segments - Use templates for consistent messaging - Implement idempotency for reliable retries operationId: sendSMS parameters: - $ref: '#/components/parameters/Xerobi-Version' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object properties: to: type: string description: >- Recipient phone number in international format (no + or spaces) example: '8801712345678' pattern: ^[1-9][0-9]{7,14}$ from: type: string description: >- Sender ID (must be registered and approved). Defaults to account default sender. example: HIXBE maxLength: 11 message: type: string description: Message content (max 1000 characters) example: >- Welcome to HIXBE! Your account has been activated successfully. minLength: 1 maxLength: 1000 schedule_at: type: string format: date-time nullable: true description: >- Schedule message for future delivery (ISO 8601 format, max 7 days ahead) example: '2026-01-16T09:00:00Z' route: type: string enum: - otp - transactional - promotional default: transactional description: >- Message route. OTP: <5s delivery, Transactional: <30s, Promotional: <2min example: transactional reference_id: type: string description: Optional reference ID for your internal tracking example: order_12345 maxLength: 100 callback_url: type: string format: uri description: >- Optional webhook URL for this specific message (overrides account webhook) example: https://yourapp.com/webhook/order-12345 required: - to - message examples: otp: summary: OTP Message value: to: '8801712345678' from: HIXBE message: Your OTP is 391202. Valid for 5 minutes. Do not share. route: otp transactional: summary: Order Confirmation value: to: '8801712345678' from: HIXBE message: >- Your order #12345 has been confirmed. Estimated delivery: Jan 20. route: transactional reference_id: order_12345 scheduled: summary: Scheduled Reminder value: to: '8801712345678' from: HIXBE message: 'Reminder: Your appointment is tomorrow at 2 PM.' route: transactional schedule_at: '2026-01-16T02:00:00Z' responses: '201': description: Message accepted and queued for delivery headers: X-RateLimit-Remaining: schema: type: integer description: Requests remaining X-RateLimit-Reset: schema: type: integer description: Unix timestamp when limit resets content: application/json: schema: $ref: '#/components/schemas/Message' example: id: msg_abc123xyz to: '8801712345678' from: HIXBE body: Your OTP is 391202. Valid for 5 minutes. Do not share. status: queued route: otp segments: 1 cost: 0.75 scheduled_at: null sent_at: null delivered_at: null error_code: null created_at: '2026-01-15T10:30:00Z' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientBalance' '429': $ref: '#/components/responses/RateLimitError' components: parameters: Xerobi-Version: name: Xerobi-Version in: header description: >- API version in YYYY-MM-DD format. Using the latest version ensures access to newest features. required: true schema: type: string default: '2026-01-01' pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-01-01' IdempotencyKey: name: Idempotency-Key in: header description: >- Unique key for request idempotency. Prevents duplicate messages if you retry the same request within 24 hours. required: false schema: type: string maxLength: 255 example: req_20260115_abc123 schemas: Message: type: object description: SMS message object with delivery status and metadata properties: id: type: string description: Unique message identifier example: msg_abc123xyz to: type: string description: Recipient phone number in international format example: '8801712345678' from: type: string description: Sender ID (alphanumeric or numeric) example: HIXBE body: type: string description: Message content example: Your OTP is 391202. Valid for 5 minutes. status: type: string enum: - queued - sent - delivered - failed - expired description: Current message status example: delivered route: type: string enum: - otp - transactional - promotional description: Message route used for delivery example: transactional segments: type: integer description: Number of SMS segments (1 segment = 160 chars) example: 1 minimum: 1 cost: type: number description: Message cost in account currency example: 0.5 minimum: 0 scheduled_at: type: string format: date-time nullable: true description: Scheduled delivery time (ISO 8601 format) example: '2026-01-15T14:30:00Z' sent_at: type: string format: date-time nullable: true description: Timestamp when message was sent to carrier example: '2026-01-15T10:30:05Z' delivered_at: type: string format: date-time nullable: true description: Timestamp when message was delivered example: '2026-01-15T10:30:15Z' error_code: type: string nullable: true description: Error code if delivery failed example: number_unreachable created_at: type: string format: date-time description: Message creation timestamp example: '2026-01-15T10:30:00Z' required: - id - to - from - body - status - created_at Error: type: object description: Standard error response with detailed information properties: error: type: object properties: type: type: string description: Error category for programmatic handling example: validation_error code: type: string description: Specific error code example: invalid_phone_number message: type: string description: Human-readable error message example: >- Phone number must be in international format without spaces or special characters param: type: string nullable: true description: Parameter that caused the error example: to request_id: type: string description: Unique request identifier for support and debugging example: req_abc123xyz doc_url: type: string description: Link to relevant documentation example: https://developer.hixbe.com/errors/invalid-phone-number required: - type - code - message - request_id required: - error responses: ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: validation_error code: invalid_phone_number message: >- Phone number must be in international format (e.g., 8801712345678) param: to request_id: req_def456 doc_url: https://developer.hixbe.com/phone-format Unauthorized: description: Authentication failed - invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: authentication_error code: invalid_api_key message: >- Invalid API key provided. Check your API key at https://dashboard.hixbe.com/api-keys request_id: req_abc123 InsufficientBalance: description: Insufficient account balance content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: payment_error code: insufficient_balance message: >- Insufficient balance. Current balance: 5.20 BDT. Required: 25.00 BDT. Please recharge your account. request_id: req_ghi789 doc_url: https://dashboard.hixbe.com/billing/recharge RateLimitError: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Please retry after 60 seconds. request_id: req_xyz789 headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests per window example: 100 X-RateLimit-Remaining: schema: type: integer description: Requests remaining example: 0 X-RateLimit-Reset: schema: type: integer description: Unix timestamp when limit resets example: 1705324800 Retry-After: schema: type: integer description: Seconds to wait before retry example: 60 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: APIKEY description: >- Use your API key as a Bearer token. Format: `Authorization: Bearer sk_live_xxxxx` ```` ## Related topics - [Send Bulk SMS](https://docs.xerobi.com/sms-api/endpoint/send-bulk-sms.md) - [SMS API FAQ](https://docs.xerobi.com/faq-guides/sms-api-faq.md) - [Send using template](https://docs.xerobi.com/sms-api/endpoint/send-template.md) - [Xerobi Developer Documentation](https://docs.xerobi.com/index.md) - [Quickstart Guide](https://docs.xerobi.com/faq-guides/quickstart.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.