Overview

Programmatic access to Naxai messaging (SMS, RCS, Email, Voice), contacts, segments, calendars and webhooks over HTTPS, with OAuth 2.0 authentication, rate limiting and automatic webhook retries.

The Naxai REST API has predictable, resource-oriented URLs, accepts and returns JSON, and uses standard HTTP verbs, status codes and authentication. Use it to send SMS, RCS, emails and voice calls, manage contacts, attributes and segments, schedule sending windows with calendars, retrieve activity logs and reporting metrics, and configure webhooks for real-time events.

Base URLs

Requirements

General

• HTTPS required: all API requests must use HTTPS with TLS 1.2 or higher on port 443.
• Network access: firewalls and proxies must allow outbound traffic to https://api.naxai.com and https://auth.naxai.com on port 443.
• DNS TTL: clients must respect Naxai's DNS TTL of 60 seconds and must not cache or hard-code IP addresses.
• JSON: send request bodies with Content-Type: application/json. All responses are JSON-encoded.
• API version: pass the x-version header to pin the API version (current version: 2023-03-25).
• Phone numbers: use the E.164 format without leading + (e.g. 32470123456).
• Timestamps: dates are expressed in Unix time (seconds, or milliseconds where stated in the endpoint reference).

Authentication

The Naxai API uses OAuth 2.0 (client credentials). Access tokens are valid for 24 hours. Create up to 10 API credentials per subaccount in Integrations → API Credentials. See Authentication.

Rate limits

Limits are applied per API (e.g. 200 operations/second for transactional SMS and Email). Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and requests above the limit return 429. See Rate limits.

Errors

Naxai uses standard HTTP status codes. Every error response includes a naxaiTraceId; share it with [email protected] when you report an issue. See Errors.

Quick start

Send your first SMS in three steps.

1. Get an access token

Create API credentials in Integrations → API Credentials, then exchange them for a token:

curl --location 'https://auth.naxai.com/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=client_credentials'

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "send:sms ..."
}

Store the token and reuse it until it expires. Do not request a new token for every call.

2. Send an SMS

curl --location 'https://api.naxai.com/sms/send' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'x-version: 2023-03-25' \
  --data '{
    "to": ["+32470123456"],
    "from": "YOUR_SENDER_ID",
    "body": "Hello from Naxai!",
    "type": "auto",
    "reference": "order-12345"
  }'

The API answers 202 Accepted with one messageId per recipient:

{
  "count": 1,
  "messages": [
    { "messageId": "fd43a7f3-6288-49ff-b4a2-a4b570fc1481", "to": "+32470123456" }
  ]
}

Testing? Send to a Virtual Testing Phone such as +32450500200. It simulates a delivered message at no cost.

3. Track the delivery status

Option A: webhook (recommended). Create a webhook in Integrations → Webhooks for the sms.status.v1 event. Naxai will POST each status update to your endpoint. See Webhooks.

Option B: polling. Retrieve the status of a single message:

curl --location 'https://api.naxai.com/sms/activity-logs/fd43a7f3-6288-49ff-b4a2-a4b570fc1481' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-version: 2023-03-25'

Status values are listed in SMS status & error codes.

Webhooks

Naxai sends events (message status, inbound messages, email activity, calls…) as HTTP POST JSON requests to your endpoint.

• Timeout: your endpoint must answer within 3 seconds. Acknowledge first, then process asynchronously.
• Retries: on timeout, 408, 409, 429 or 5xx, Naxai retries up to 6 times (after 5, 10, 15, 30, 60 and 240 minutes).
• Source IPs: 80.169.61.10, 81.246.100.2, 194.78.45.194, 213.246.242.36.

See Webhooks.

Best practices

• Retry safely: on 429 and 5xx, retry with exponential backoff. Add an idempotencyKey to sending requests so that a retried call never sends a duplicate message (a reused key returns 409).
• Separate environments: use a dedicated subaccount or set of credentials for testing and for production.
• Paginate: list endpoints use page (default 1) and pagesize (default 25, max 100).
• Monitor: subscribe to status.naxai.com for incident and maintenance notifications.

Tools

• Postman: fork our ready-to-use collection and environment. See Use our Postman collection.
• Changelog: follow API updates in the Changelog.