Send an SMS

curl --request POST \
  --url https://avraapi.com/api/v1/sms/send \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-SECRET: <api-key>' \
  --data '
{
  "send_method": "single",
  "to": "RECIPIENT_NUMBER",
  "message": "Text message"
}
'

{
  "success": true,
  "request_id": "1af26040-c878-472f-88bd-6c5158905637",
  "data": {
    "send_method": "single",
    "message_count": 1,
    "credits_charged": 2000,
    "provider_response": {
      "status": "success",
      "id": "4726abaf7ab34f31378"
    }
  }
}

POST

sms

send

curl --request POST \
  --url https://avraapi.com/api/v1/sms/send \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-SECRET: <api-key>' \
  --data '
{
  "send_method": "single",
  "to": "RECIPIENT_NUMBER",
  "message": "Text message"
}
'

{
  "success": true,
  "request_id": "1af26040-c878-472f-88bd-6c5158905637",
  "data": {
    "send_method": "single",
    "message_count": 1,
    "credits_charged": 2000,
    "provider_response": {
      "status": "success",
      "id": "4726abaf7ab34f31378"
    }
  }
}

Use this endpoint to send SMS through the active QuickSend SMS integration in the selected project environment. It supports a single recipient, a bulk list with one message, and a small bulk list with different messages.

This is a real external action. A successful response confirms that QuickSend accepted the request; it is not final delivery proof. While testing, send messages only to phone numbers you own or are allowed to use. Do not automatically retry after a timeout or uncertain provider outcome, because that can send duplicate messages. In the Documentation Playground, turn on X-Confirm-Send only after reviewing every recipient and message.

Live Testing Guide: Before using Try it, create a Development project, then enter its Client ID and Client Secret. Configure the relevant provider for that project before sending the request.

API endpoint

POST

https://avraapi.com/api/v1/sms/send

Request fields

Field	Required	Rules
`send_method`	Yes	One of `single`, `bulk_same`, or `bulk_different`.
`to`	For `single`	One QuickSend-compatible Sri Lankan number: local `07XXXXXXXX` or E.164 `+947XXXXXXXX`.
`message`	For `single` and `bulk_same`	Message text. Input is capped at 4,096 characters and each recipient message may use at most three SMS units.
`recipients`	For `bulk_same`	Array of 1–10,000 QuickSend-compatible Sri Lankan numbers.
`check_cost`	No; `bulk_same` only	Boolean. With `true`, QuickSend returns campaign cost information instead of sending the bulk campaign.
`msg_list`	For `bulk_different`	Array of 1–20 objects. Every object needs `to` and `msg`.
`msg_list[].to`	For `bulk_different`	One QuickSend-compatible Sri Lankan number.
`msg_list[].msg`	For `bulk_different`	Message text for that recipient, with the same three-unit maximum.

Use a Managed QuickSend integration for single only. bulk_same and bulk_different require a Manual (BYOK) QuickSend integration. check_cost is forwarded only for bulk_same; setting it for bulk_different does not turn that request into a cost estimate and the messages are still sent.

SMS units and character limits

AvraAPI calculates message_count from SMS units, not simply from the number of API requests. For predictable message sizing and billing, use 153 GSM-7 characters per SMS unit or 67 Unicode (UCS-2) characters per SMS unit. Each individual recipient message is limited to a maximum of 3 SMS units. Therefore, a single request can return a maximum message_count of 3; a bulk response reports the total units across all recipients and can be higher. For example, a two-recipient bulk_same campaign with a one-unit message returns message_count: 2. A long or Unicode single message can return a message_count greater than one.

Result fields

Field	Type	Notes
`send_method`	string	The accepted AvraAPI send method.
`message_count`	integer	Total calculated SMS units across the request.
`credits_charged`	integer	AvraAPI credits charged for this request. Manual (BYOK) sends return `0`; QuickSend may charge the connected provider account separately.
`provider_response`	object	Raw QuickSend acceptance or cost-estimate response. Its fields vary by QuickSend operation.

Single SMS

Request example

curl

curl --request POST "https://avraapi.com/api/v1/sms/send" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"send_method":"single","to":"RECIPIENT_NUMBER","message":"Text message"}'

Response example

{
  "success": true,
  "request_id": "1af26040-c878-472f-88bd-6c5158905637",
  "data": {
    "send_method": "single",
    "message_count": 1,
    "credits_charged": 2000,
    "provider_response": {
      "status": "success",
      "id": "4726abaf7ab34f31378"
    }
  }
}

Bulk SMS with the same message

Request example

curl

curl --request POST "https://avraapi.com/api/v1/sms/send" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"send_method":"bulk_same","recipients":["FIRST_RECIPIENT_NUMBER","SECOND_RECIPIENT_NUMBER"],"message":"Text message","check_cost":true}'

Response example

{
  "success": true,
  "request_id": "2ddf0451-ab4d-47d6-877a-8d167d25d680",
  "data": {
    "send_method": "bulk_same",
    "message_count": 2,
    "credits_charged": 0,
    "provider_response": {
      "status": "success",
      "id": "4726abaf95f01e62378"
    }
  }
}

Bulk SMS cost check

Request example

curl

curl --request POST "https://avraapi.com/api/v1/sms/send" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"send_method":"bulk_same","recipients":["FIRST_RECIPIENT_NUMBER","SECOND_RECIPIENT_NUMBER"],"message":"Text message","check_cost":true}'

Response example

{
  "success": true,
  "request_id": "d5ca2bbb-9cab-42ef-932a-62ef61470447",
  "data": {
    "send_method": "bulk_same",
    "message_count": 2,
    "credits_charged": 0,
    "provider_response": {
      "status": "success",
      "campaign_data": {
        "campaign_method": "Same Message To Bulk",
        "campaign_type": "Transactional",
        "sender_id": "APIX SENDER",
        "campaign_total_cost": "1.12 LKR (0.56×2)",
        "campaign_total_numbers": "2 Numbers",
        "sms_msg_data": [
          {
            "msg": "BULK TRANSACTION TEST",
            "unicode": "NO",
            "msg_size": "1 SMS",
            "per_sms_cost": "0.56 LKR",
            "msg_cost": "0.56 LKR (1×0.56)"
          }
        ]
      }
    }
  }
}

Bulk SMS with different messages

Request example

curl

curl --request POST "https://avraapi.com/api/v1/sms/send" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"send_method":"bulk_different","msg_list":[{"to":"FIRST_RECIPIENT_NUMBER","msg":"First text message"},{"to":"SECOND_RECIPIENT_NUMBER","msg":"Second text message"}]}'

Response example

{
  "success": true,
  "request_id": "5bf45f1d-e0ee-4293-8a47-f033d1fb0c4a",
  "data": {
    "send_method": "bulk_different",
    "message_count": 2,
    "credits_charged": 0,
    "provider_response": {
      "status": "success",
      "id": "4726abafafabbb0a378"
    }
  }
}

Error codes

HTTP	`error.code`	When it happens	What to do
`401`	`unauthorized`	Credentials are missing, invalid, inactive, or do not match the selected environment.	Check your backend secret configuration and `X-ENV`.
`402`	`insufficient_funds`	A Managed SMS send requires AvraAPI credits that are unavailable.	Top up the AvraAPI wallet or reduce the message units before sending again.
`403`	`forbidden`	A Managed integration attempted `bulk_same` or `bulk_different`, or a trial destination restriction rejected the recipient.	Use `single` for Managed SMS, or configure Manual (BYOK) QuickSend for bulk sending. Check any trial recipient restriction before retrying.
`428`	`send_confirmation_required`	A Documentation Playground send did not explicitly acknowledge the real delivery action.	Review every recipient and message, then set `X-Confirm-Send` to `true`. This does not make an uncertain send safe to retry.
`422`	`validation_failed`	The request body does not satisfy the selected send-method fields. The response includes field details.	Correct the body and submit a new request.
`422`	`provider_selection_failed`	No active QuickSend SMS integration can be selected for the project environment.	Configure or enable the QuickSend integration for the selected environment.
`422`	`http_error`	The active integration is incomplete, the message exceeds three SMS units, or the SMS configuration cannot be used.	Correct the configuration or request; do not repeat an uncertain send.
`429`	`rate_limit_exceeded`	The configured request limit was reached.	Respect `Retry-After` when present; do not retry in a tight loop.
`500`	`internal_error`	The request could not complete unexpectedly.	Investigate with the request ID before deciding whether to submit a new send.
`502`	`http_error`	QuickSend rejected the request, returned an unexpected response, or its configured credentials failed.	Correct the request or integration. Do not repeat the same send until you know it was not accepted.
`503`	`http_error`	QuickSend was temporarily unreachable.	Treat delivery as uncertain; check your provider records before any manual retry.
`503`	`project_paused`	The project is paused.	Reactivate the project before retrying.

Keep the JSON request_id or X-APIX-Request-ID response header with your support record. It is the safest way for AvraAPI support to trace a request.

See the REST API guide for shared credential, privacy, and error-handling guidance.

Playground resources

The generated reference below lists this endpoint’s API standard details: request fields, authorizations, and response schema. The complete integration guide, request and response examples, and endpoint-specific error handling are above.

Authorizations

X-API-KEY

string

header

required

Your Development project's Client ID. Enter your own value in the Documentation Playground.

X-API-SECRET

string

header

required

Your Development project's Client Secret. Mintlify does not proxy these requests; the browser sends them directly to AvraAPI. Never enter a Production secret in the Documentation Playground.

Headers

X-ENV

enum<string>

default:development

Selects the Development credential environment. The Documentation Playground exposes Development values only; normal backend integrations may use their documented Production credentials outside this tool.

Available options:

dev,

development

string

Requests a JSON response where the selected operation supports JSON.

Example:

"application/json"

X-Privacy-Mode

boolean

default:false

Optional privacy override. Turn this on to request that AvraAPI suppress request-payload storage in observability logs for this request.

Example:

true

X-Confirm-Send

boolean

default:false

Documentation Playground safeguard for real SMS delivery. Turn this on only after reviewing every recipient and message. It is required for documentation-origin SMS send requests and does not make a timed-out send safe to retry.

Example:

true

Body

application/json

Single SMS
Bulk SMS
Bulk Different

send_method

enum<string>

default:single

required

Fixed to single for this form.

Available options:

single

string

required

Local Sri Lankan 07XXXXXXXX or E.164 +947XXXXXXXX number. Replace this with the recipient number before sending.

Maximum string length: 20

Example:

"RECIPIENT_NUMBER"

message

string

required

Message text. The released service limits each recipient message to three SMS units.

Maximum string length: 4096

Example:

"Text message"

Response

Provider acceptance result or bulk-same cost estimate.

success

enum<boolean>

required

Available options:

true

request_id

string<uuid>

required

Include this value when contacting AvraAPI support.

data

object

required

Operation-specific result data.

Show child attributes

Last modified on October 1, 2026

Introduction

Currencies

SMS

Security

Location

Utilities

API endpoint

Request fields

SMS units and character limits

Result fields

Single SMS

Request example

Response example

Bulk SMS with the same message

Request example

Response example

Bulk SMS cost check

Request example

Response example

Bulk SMS with different messages

Request example

Response example

Error codes

Playground resources

Authorizations

Headers

Body

Response

​API endpoint

​Request fields

​SMS units and character limits

​Result fields

​Single SMS

​Request example

​Response example

​Bulk SMS with the same message

​Request example

​Response example

​Bulk SMS cost check

​Request example

​Response example

​Bulk SMS with different messages

​Request example

​Response example

​Error codes

​Playground resources

Authorizations

Headers

Body

Response

API endpoint

Request fields

SMS units and character limits

Result fields

Single SMS

Request example

Response example

Bulk SMS with the same message

Request example

Response example

Bulk SMS cost check

Request example

Response example

Bulk SMS with different messages

Request example

Response example

Error codes

Playground resources