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 Email

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

Sends an HTML email message to any email address worldwide. The message can be directly specified or templated using our template system. Supports both transactional and marketing emails with advanced features like scheduling, tracking, and delivery optimization.

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/email' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "to": "someone@example.com",
  "from": "alerts@example.com",
  "subject": "Test Email",
  "body": "
Test Email
This is a sample HTML email message for testing purposes.
",
  "clientIdentifier": "client-001"
}'

Sample Request (Templated)

curl --location 'https://api.brazeno.com/api/v1/email' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "templateId": "tmpl_1234567890abcdef",
  "to": "someone@example.com",
  "from": "alerts@example.com",
  "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 Email 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 Email 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": "someone@example.com",
    "from": "alerts@example.com",
    "channel": "email",
    "statuses": [
      {
        "status": "queued",
        "statusAt": "2025-09-09T20:21:46.646Z",
      },
      {
        "status": "sent to provider",
        "statusAt": "2025-09-09T20:21:47.162Z"
      },
      {
        "status": "delivered",
        "statusAt": "2025-09-09T20:21:47.162Z"
      },
      {
        "status": "open",
        "statusAt": "2025-09-09T20:21:47.162Z"
      },
      {
        "status": "click",
        "statusAt": "2025-09-09T20:21:47.162Z",
        "url": "https://example.com"
      },
      {
        "status": "bounced",
        "statusAt": "2025-09-09T20:21:47.162Z"
      },
      {
        "status": "complained",
        "statusAt": "2025-09-09T20:21:47.162Z"
      }      
    ]
  }
]

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 Email status"
}

429 Too Many Requests

{
    "error": "Rate limit exceeded"
}

Best Practices

Email Content

• Use responsive HTML: Design emails that work on all devices and email clients
• Optimize subject lines: Keep them under 50 characters and avoid spam trigger words
• Include text alternatives: Provide plain text versions for better deliverability
• Test across clients: Verify rendering in major email clients (Gmail, Outlook, Apple Mail)
• Include unsubscribe links: Add clear opt-out mechanisms for marketing emails

Error Handling

• Implement retry logic: Retry failed requests with exponential backoff
• Handle bounces gracefully: Remove bounced email addresses from your lists
• Monitor delivery rates: Track open, click, and bounce rates
• Validate email addresses: Use email validation 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
• Verify sender domains: Use SPF, DKIM, and DMARC records
• Contact Brazeno for key management: API keys are provided by Brazeno representatives

Performance

• Use bulk sending: Send multiple emails in batches when possible
• Optimize images: Compress images and use appropriate formats
• Monitor delivery rates: Track and analyze delivery success rates
• Segment your audience: Send targeted emails to improve engagement
• Schedule strategically: Send emails during optimal times 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 sendEmail = async (to, subject, htmlBody, from = 'noreply@yourdomain.com') => {
  try {
    const response = await axios.post('https://api.brazeno.com/api/v1/email', {
      to: to,
      from: from,
      subject: subject,
      body: htmlBody,
      clientIdentifier: `node-${Date.now()}`
    }, {
      headers: {
        'x-api-key': process.env.BRAZENO_API_KEY,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Email sent successfully:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error sending email:', error.response?.data || error.message);
    throw error;
  }
};

// Usage
sendEmail('user@example.com', 'Welcome!', '
Welcome to our service!
Thank you for signing up.
')
  .then(result => console.log('Message ID:', result.messageId))
  .catch(error => console.error('Failed to send email:', error));

Python

import requests
import os
import json
from datetime import datetime

def send_email(to, subject, html_body, from_email='noreply@yourdomain.com'):
    url = 'https://api.brazeno.com/api/v1/email'
    headers = {
        'x-api-key': os.getenv('BRAZENO_API_KEY'),
        'Content-Type': 'application/json'
    }
    data = {
        'to': to,
        'from': from_email,
        'subject': subject,
        'body': html_body,
        '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 email: {e}')
        if hasattr(e, 'response') and e.response is not None:
            print(f'Response: {e.response.text}')
        raise

# Usage
try:
    result = send_email('user@example.com', 'Welcome!', '
Welcome to our service!
Thank you for signing up.
')
    print(f'Message ID: {result["messageId"]}')
except Exception as e:
    print(f'Failed to send email: {e}')

PHP

 $to,
        'from' => $from,
        'subject' => $subject,
        'body' => $htmlBody,
        '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 email 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 = sendEmail('user@example.com', 'Welcome!', '
Welcome to our service!
Thank you for signing up.
');
    echo 'Message ID: ' . $result['messageId'] . PHP_EOL;
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
}
?>

cURL

# Basic email sending
curl -X POST 'https://api.brazeno.com/api/v1/email' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "user@example.com",
    "from": "noreply@yourdomain.com",
    "subject": "Welcome to our service!",
    "body": "
Welcome!
Thank you for signing up.
",
    "clientIdentifier": "curl-example"
  }'

# Templated email
curl -X POST 'https://api.brazeno.com/api/v1/email' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "tmpl_welcome_email",
    "to": "user@example.com",
    "from": "noreply@yourdomain.com",
    "data": {
      "name": "John Doe",
      "company": "Example Corp"
    }
  }'