> ## 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 using template

> Send SMS using a template with variable substitution.

Send SMS using a template with variable substitution.


## OpenAPI

````yaml POST /templates/{template_id}/send
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:
  /templates/{template_id}/send:
    post:
      tags:
        - Templates
      summary: Send using template
      description: Send SMS using a template with variable substitution.
      operationId: sendWithTemplate
      parameters:
        - $ref: '#/components/parameters/Xerobi-Version'
        - name: template_id
          in: path
          required: true
          description: Template ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  type: string
                  description: Recipient phone number
                  example: '8801712345678'
                from:
                  type: string
                  description: Sender ID
                  example: HIXBE
                variables:
                  type: object
                  description: Key-value pairs for template variables
                  additionalProperties:
                    type: string
                  example:
                    customer_name: John
                    order_id: '12345'
                    delivery_date: Jan 20
                route:
                  type: string
                  enum:
                    - otp
                    - transactional
                    - promotional
                  example: transactional
              required:
                - to
                - variables
      responses:
        '201':
          description: Message sent using template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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'
  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
  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 SMS](https://docs.xerobi.com/sms-api/endpoint/send-sms.md)
- [Certification API FAQ](https://docs.xerobi.com/faq-guides/certification-api-faq.md)
- [Xerobi SMS Gateway API Introduction](https://docs.xerobi.com/sms-api/introduction.md)
- [Send Bulk SMS](https://docs.xerobi.com/sms-api/endpoint/send-bulk-sms.md)
- [List Templates](https://docs.xerobi.com/certify/endpoint/list-templates.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.