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

# Send SMS

Send transactional SMS messages to users using the Antryk SMS Service.

This endpoint allows you to deliver alerts, notifications, reminders, and other time-sensitive messages directly to a user's mobile device. It is optimized for high deliverability and low latency, making it ideal for real-time communication use cases.

Authentication is handled securely via headers, ensuring your API credentials are never exposed in the request body.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://ses.antryk.com/api/v1/sms/send \
    --header "Content-Type: application/json" \
    --header "x-access-key: YOUR_ACCESS_KEY" \
    --header "x-secret-key: YOUR_SECRET_KEY" \
    --data '{
      "to": "+1XXXXXXXXXX",
      "body": "Your appointment is scheduled at 3 PM.",
      "serviceId": "YOUR_SERVICE_ID"
    }'
  ```

  ```javascript JavaScript theme={null}
  fetch("https://ses.antryk.com/api/v1/sms/send", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-access-key": "YOUR_ACCESS_KEY",
      "x-secret-key": "YOUR_SECRET_KEY",
    },
    body: JSON.stringify({
      to: "+1XXXXXXXXXX",
      body: "Your appointment is scheduled at 3 PM.",
      serviceId: "YOUR_SERVICE_ID",
    }),
  });
  ```

  ```javascript NodeJs theme={null}
  // npm i @antryk/sdk
  import { AntrykClient } from "@antryk/sdk";

  const client = new AntrykClient({
    accessKey: process.env.ANTRYK_ACCESS_KEY,
    secretKey: process.env.ANTRYK_SECRET_KEY,
  });

  async function sendSms() {
    const result = await client.sms.send({
      to: "+1XXXXXXXXXX",
      body: "Your appointment is scheduled at 3 PM.",
      serviceId: "YOUR_SERVICE_ID",
    });

    console.log(result.data); // null for standard SMS
  }

  sendSms();
  ```

  ```python Python theme={null}
  # pip install requests
  import requests

  url = "https://ses.antryk.com/api/v1/sms/send"

  headers = {
      "Content-Type": "application/json",
      "x-access-key": "YOUR_ACCESS_KEY",
      "x-secret-key": "YOUR_SECRET_KEY"
  }

  data = {
      "to": "+1XXXXXXXXXX",
      "body": "Your appointment is scheduled at 3 PM.",
      "serviceId": "YOUR_SERVICE_ID"
  }

  response = requests.post(url, headers=headers, json=data)

  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

<Note>
  {" "}

  For Node.js applications, it is recommended to use the official
  [`@antryk/sdk`](https://www.npmjs.com/package/@antryk/sdk). The SDK simplifies
  SMS sending by handling authentication, validation, retries, and error
  handling internally.{" "}
</Note>

<Note>
  {" "}

  Authentication is handled via headers (`x-access-key`, `x-secret-key`). The
  request body should only contain SMS-related fields such as recipient number,
  message body, and service ID.{" "}
</Note>

### New SMS Sending Approach (Recommended)

This is the recommended and modern approach for sending SMS messages:

* Authentication is passed via headers instead of request body.
* Request body contains only SMS-related parameters.
* mproved security and cleaner API design.
* Easier backend integration and maintenance.

<Note>
  ⚠️ The older approach (passing `accessKey` and `secretKey` in the request
  body) may still work for backward compatibility, but it is **strongly
  recommended to migrate to header-based authentication**.
</Note>

## Request Parameters

<ParamField header="x-access-key" type="string" required>
  {" "}

  Your Antryk access key used for API authentication.{" "}
</ParamField>

<ParamField header="x-secret-key" type="string" required>
  {" "}

  Your Antryk secret key used to securely authorize requests.{" "}
</ParamField>

<ParamField body="to" type="string" required>
  {" "}

  Recipient phone number in E.164 format (e.g. `+919876543210`). Only one number
  is supported per request.{" "}
</ParamField>

<ParamField body="body" type="string" required>
  {" "}

  The SMS message content. Maximum length is 1600 characters.{" "}
</ParamField>

<ParamField body="serviceId" type="string" required>
  {" "}

  UUID v4 identifier of your configured SMS service.{" "}
</ParamField>

<Tip>
  {" "}

  Keep SMS messages concise and clear. Short messages improve readability and
  delivery performance.{" "}
</Tip>

<Warning>
  {" "}

  Ensure the phone number is valid and properly formatted. Invalid inputs may
  result in delivery failure or API errors.{" "}
</Warning>

## Examples

<ParamField header="x-access-key" type="string" required>
  {" "}

  Example: YOUR\_ACCESS\_KEY{" "}
</ParamField>

<ParamField header="x-secret-key" type="string" required>
  {" "}

  Example: YOUR\_SECRET\_KEY{" "}
</ParamField>

<ParamField body="to" type="string" required>
  {" "}

  Example: +919876543210{" "}
</ParamField>

<ParamField body="body" type="string" required>
  {" "}

  Example: Your verification code is 482193{" "}
</ParamField>

<ParamField body="serviceId" type="string" required>
  {" "}

  Example: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx{" "}
</ParamField>

<Note>
  {" "}

  ### Additional Notes This endpoint is suitable for transactional messaging

  such as alerts, reminders, and confirmations. Avoid sending promotional or
  spam messages to maintain high deliverability rates. Always protect API
  credentials and use server-side integrations or the SDK for better security
  and reliability.{" "}
</Note>

## Response

Returns a confirmation that the SMS request has been accepted for delivery.

```json theme={null}
{
  "success": true,
  "messageId": "msg_5QZ9S6",
  "to": "+1XXXXXXXXXX",
  "queuedAt": "2025-11-06T11:21:00.000Z"
}
```

<Note>
  Note: When using the SDK, result.data is null for standard SMS send operations.
</Note>

## Error Scenarios

* **401 invalid credentials** – Invalid `x-access-key` or `x-secret-key`
* **400 invalid\_recipient** – Phone number is missing or incorrectly formatted
* **404 service\_not\_found** – `serviceId` missing, revoked, or disabled
* **429 rate\_limited** – service exceeds per-minute quota or Too many requests in a short peroid
* **500 provider\_unavailable** – upstream SMS provider outage; retry with backoff

## Error Response Example

```json theme={null}
{
  "success": false,
  "errors": [
    {
      "message": "Invalid recipient",
      "code": 400
    }
  ]
}
```

<Warning>
  Always validate phone numbers and throttle retries to avoid rate limiting.
</Warning>