Brazeno.com

Authorization

All requests require an API key for authorization. The API key must be included in the x-api-key header for each request.

API Key: The x-api-key header must be included with every request to authenticate the client. Requests without this header will return a 401 Unauthorized error.

Getting Your API Key

1. Contact your Brazeno representative
2. Request API access for your project
3. Receive your API key via secure communication
4. Store the API key securely in your application

Example Header:

x-api-key: YOUR_API_KEY

1. Send SMS

POST https://api.brazeno.com/api/v1/sms

Sends an SMS message to any phone number worldwide. The message can be directly specified or templated using our template system. Supports both single messages and bulk messaging with advanced features like scheduling and delivery tracking.

Headers

• x-api-key (required): API key for authorization.
• Content-Type (required): Must be application/json

Request Body

Sample Request (Non Templated)

curl --location 'https://api.brazeno.com/api/v1/sms' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "to": "+15551234567",
  "from": "+15558675309",
  "body": "This is a sample SMS message for testing purposes.",
  "clientIdentifier": "client-001"
}'

Sample Request (Templated)

curl --location 'https://api.brazeno.com/api/v1/sms' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "templateId": "tmpl_1234567890abcdef",
  "to": "+15551234567",
  "from": "+15558675309",
  "data": {
    "name": "Alex Example",
    "address": "123 Example Street",
    "etor": "8pm"
  },
  "clientIdentifier": "client-001",
  "notBefore": "2025-01-01T12:00:00Z",
  "notAfter": "2025-01-01T14:00:00Z"
}'

Sample Response

200 OK

{
    "status": "queued",
    "messageId": "1234567890abcdef"
}

Response Fields

Rate Limiting

To ensure fair usage of resources, the Send SMS API endpoint is rate-limited based on each client’s API key. If the rate limit is exceeded, subsequent requests will be temporarily blocked until the rate limit resets.

Current Rate Limit

The current rate limit may vary based on your subscription plan and usage agreement. Please refer to the API’s response headers to monitor your rate limit status, or contact us for your specific rate limit settings.

Rate Limit Headers

On each response, the following headers provide rate limit details:

Exceeded Rate Limit Response

If the rate limit is exceeded, the following response will be returned:

{
    "error": "Rate limit exceeded"
}

Increasing Rate Limit

If your application requires a higher rate limit, please reach out to the Brazeno support team to discuss rate limit adjustments that suit your requirements. We are happy to accommodate higher traffic where possible. Contact us via email at contact@brazeno.com or through your Brazeno representative.

2. Get SMS Status

Retrieve message status events using either a POST (for multiple message IDs) or a GET (for a single message ID).

Headers

• x-api-key (required): API key for authorization.
• Content-Type: application/json

Endpoint

https://api.brazeno.com/api/v1/message/status

Sample Request (POST - multiple messageIds)

curl --location 'https://api.brazeno.com/api/v1/message/status' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "messageIds": [
    "1eff6f78-0701-453e-8c6c-8cb969d2e5cd",
    "7d4b3db1-e4fa-44ff-8ac6-94b29b40885e"
  ]
}'

Sample Request (GET - single messageId)

curl --location --request GET 'https://api.brazeno.com/api/v1/message/status?messageId=390b6f28-20bd-4cc5-8cae-6e598f9abf8b' \
--header 'x-api-key: YOUR_API_KEY'

Sample Response (both verbs)

[
  {
    "messageId": "390b6f28-20bd-4cc5-8cae-6e598f9abf8b",
    "clientIdentifier": "approval-886f97ec-ecfe-4285-b2e7-f4fdff4c9000-1757449306535",
    "to": "+15551234567",
    "from": "+15558675309",
    "channel": "sms",
    "statuses": [
      {
        "status": "queued",
        "statusAt": "2025-09-09T20:21:46.646Z",
        "url": null,
        "userAgent": null
      },
      {
        "status": "sent to provider",
        "statusAt": "2025-09-09T20:21:47.162Z",
        "url": null,
        "userAgent": null
      }
    ]
  }
]

Response Fields

statuses Array

Error Responses

401 Unauthorized

{
    "error": "API key is required"
}

403 Forbidden

{
    "error": "Invalid API key"
}

500 Internal Server Error

{
    "error": "Failed to retrieve SMS status"
}

429 Too Many Requests

{
    "error": "Rate limit exceeded"
}

Best Practices

Message Content

• Keep messages concise: SMS has a 160-character limit for single messages
• Use clear language: Avoid abbreviations and technical jargon
• Include opt-out instructions: Add "Reply STOP to opt out" for marketing messages
• Test your messages: Send test messages to verify formatting and content

Error Handling

• Implement retry logic: Retry failed requests with exponential backoff
• Handle rate limits: Monitor rate limit headers and implement queuing
• Validate phone numbers: Use E.164 format and validate before sending
• Log all requests: Keep detailed logs for debugging and compliance

Security

• Store API keys securely: Use environment variables or secure key management
• Use HTTPS only: Always use secure connections for API calls
• Implement access controls: Restrict API key access to necessary personnel
• Monitor usage: Set up alerts for unusual API activity
• Contact Brazeno for key management: API keys are provided by Brazeno representatives

Performance

• Use bulk messaging: Send multiple messages in batches when possible
• Implement caching: Cache frequently used data like phone number validation
• Monitor delivery rates: Track and analyze delivery success rates
• Optimize timing: Send messages during appropriate hours for your audience

Code Examples

Ready-to-use code examples in popular programming languages to help you get started quickly.

Node.js

const axios = require('axios');

const sendSMS = async (to, message, from = 'Brazeno') => {
  try {
    const response = await axios.post('https://api.brazeno.com/api/v1/sms', {
      to: to,
      from: from,
      body: message,
      clientIdentifier: `node-${Date.now()}`
    }, {
      headers: {
        'x-api-key': process.env.BRAZENO_API_KEY,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('SMS sent successfully:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error sending SMS:', error.response?.data || error.message);
    throw error;
  }
};

// Usage
sendSMS('+1234567890', 'Hello from Node.js!')
  .then(result => console.log('Message ID:', result.messageId))
  .catch(error => console.error('Failed to send SMS:', error));

Python

import requests
import os
import json
from datetime import datetime

def send_sms(to, message, from_number='Brazeno'):
    url = 'https://api.brazeno.com/api/v1/sms'
    headers = {
        'x-api-key': os.getenv('BRAZENO_API_KEY'),
        'Content-Type': 'application/json'
    }
    data = {
        'to': to,
        'from': from_number,
        'body': message,
        'clientIdentifier': f'python-{int(datetime.now().timestamp())}'
    }
    
    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Error sending SMS: {e}')
        if hasattr(e, 'response') and e.response is not None:
            print(f'Response: {e.response.text}')
        raise

# Usage
try:
    result = send_sms('+1234567890', 'Hello from Python!')
    print(f'Message ID: {result["messageId"]}')
except Exception as e:
    print(f'Failed to send SMS: {e}')

PHP

 $to,
        'from' => $from,
        'body' => $message,
        'clientIdentifier' => 'php-' . time()
    ];
    
    $options = [
        'http' => [
            'header' => [
                'x-api-key: ' . $apiKey,
                'Content-Type: application/json'
            ],
            'method' => 'POST',
            'content' => json_encode($data)
        ]
    ];
    
    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    
    if ($result === FALSE) {
        throw new Exception('Failed to send SMS request');
    }
    
    $response = json_decode($result, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new Exception('Invalid JSON response: ' . json_last_error_msg());
    }
    
    return $response;
}

// Usage
try {
    $result = sendSMS('+1234567890', 'Hello from PHP!');
    echo 'Message ID: ' . $result['messageId'] . PHP_EOL;
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
}
?>

cURL

# Basic SMS sending
curl -X POST 'https://api.brazeno.com/api/v1/sms' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+1234567890",
    "from": "Brazeno",
    "body": "Hello from cURL!",
    "clientIdentifier": "curl-example"
  }'

# Scheduled SMS
curl -X POST 'https://api.brazeno.com/api/v1/sms' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+1234567890",
    "from": "Brazeno",
    "body": "This is a scheduled message",
    "notBefore": "2025-01-01T12:00:00Z",
    "notAfter": "2025-01-01T18:00:00Z"
  }'