realay.io API

Appearance

Quick Start: realay.io SMS Gateway API ​

Welcome to the realay.io SMS Gateway API! This guide will help you send your first SMS in minutes.

1. Get Your API Key ​

Before you begin, you'll need an API key.

  1. Sign Up: If you don't have an account, register at https://realay.io/signup.
  2. Dashboard Access: Log in to your realay.io dashboard.
  3. Generate API Key: Navigate to the API Keys section and generate a new Bearer API token.
  4. Keep it Secure: Treat your API key like a password. Do not share it publicly or commit it to version control.

2. Send Your First SMS ​

The primary way to send an SMS is via the POST /api/send/sms endpoint.

Authentication: Include your API Key in the Authorization header as a Bearer token: Authorization: Bearer YOUR_API_KEY.

cURL Example ​

This example sends a simple SMS.

bash
curl -X POST https://api.realay.io/send/sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "recipient": "+61400123456",
        "originator": "realay.io",
        "text": "Hello from realay.io! This is your first SMS."
      }'

Python Example (using requests) ​

This example includes basic error handling.

python
import requests
import json

API_KEY = "YOUR_API_KEY"
API_URL = "https://api.realay.io/send/sms"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "recipient": "+61400123456",
    "originator": "realay.io",
    "text": "Hello from realay.io using Python!"
}

try:
    response = requests.post(API_URL, headers=headers, data=json.dumps(payload))
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)

    print("SMS accepted successfully:")
    print(json.dumps(response.json(), indent=2))

except requests.exceptions.HTTPError as err:
    print(f"HTTP error occurred: {err}")
    print(f"Response: {response.status_code} - {response.text}")
except requests.exceptions.RequestException as err:
    print(f"An error occurred: {err}")

Node.js Example (using fetch) ​

This example shows how to handle success and error responses.

javascript
const API_KEY = "YOUR_API_KEY";
const API_URL = "https://api.realay.io/send/sms";

const payload = {
    recipient: "+61400123456",
    originator: "realay.io",
    text: "Hello from realay.io using Node.js!"
};

async function sendSms() {
    try {
        const response = await fetch(API_URL, {
            method: "POST",
            headers: {
                "Authorization": `Bearer ${API_KEY}`,
                "Content-Type": "application/json"
            },
            body: JSON.stringify(payload)
        });

        const data = await response.json();

        if (!response.ok) {
            console.error(`Error: ${response.status} ${response.statusText}`);
            console.error("Details:", data);
            return;
        }

        console.log("SMS accepted successfully:", data);

    } catch (error) {
        console.error("An unexpected error occurred:", error);
    }
}

sendSms();

3. Check Message Delivery ​

The API response confirms that your message was accepted. The final delivery status is reported asynchronously via webhooks.

  1. Configure Webhooks: Set up a webhook endpoint in your realay.io dashboard to receive delivery reports (DLRs).
  2. Receive DLRs: realay.io will send a JSON payload to your webhook URL when the message status changes (e.g., to DELIVERED or FAILED). The id from the API response can be used to correlate the report to your original message.

For more details, see our Webhooks documentation.

4. Next Steps ​

You've successfully sent your first SMS! Now, explore more capabilities: