Getting Started

NotifyHub API Documentation

Welcome to NotifyHub

NotifyHub is a unified notifications platform that enables you to send SMS, Email, and WhatsApp messages through a single, powerful API. Built for developers who need reliable, multi-channel messaging at scale.

Key Features

Multi-Channel Messaging: Send SMS, Email, and WhatsApp from one API
Contact Management: Organize recipients with groups and tags
Campaign Management: Schedule and automate bulk messaging campaigns
Real-Time Analytics: Track delivery status and campaign performance
Flexible Credentials: Use default credentials or configure per-organization overrides
Secure & Scalable: JWT authentication with organization-level isolation

Supported Channels

| Channel | Provider | Use Cases | |---------|----------|-----------| | SMS | Lancola | OTP codes, alerts, reminders | | Email | SMTP (any provider) | Newsletters, invoices, receipts | | WhatsApp | Meta Cloud API | Customer support, notifications |

Quick Start

Get your first message sent in under 5 minutes.

Create your NotifyHub account and get your organization set up:

Endpoint: POST https://api.notifyhub.com/auth/signup

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@yourcompany.com",
  "password": "YourSecurePassword123!",
  "countryCode": "+254",
  "phoneNumber": "712345678",
  "companyName": "Your Company Ltd",
  "sector": "Technology",
  "country": "Kenya"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "_id": "695cc3b0212740bd1dba40d4",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@yourcompany.com",
    "role": "admin",
    "organization": "695cc3b0212740bd1dba40d2",
    "isActive": true
  }
}

Important: Save your token - you'll need it for all API requests!

Step 2: Send Your First Message

Send an SMS using your authentication token:

Endpoint: POST https://api.notifyhub.com/notifications/send

Headers:

Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: application/json

Request Body:

{
  "type": "sms",
  "to": "+254712345678",
  "message": "Hello from NotifyHub! This is your first test message."
}

Response:

{
  "recipient": "+254712345678",
  "status": "success"
}

Complete cURL Example:

curl -X POST https://api.notifyhub.com/notifications/send \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "to": "+254712345678",
    "message": "Hello from NotifyHub! This is your first test message."
  }'

Step 3: Send an Email

Request Body:

{
  "type": "email",
  "to": "recipient@example.com",
  "subject": "Welcome to NotifyHub!",
  "message": "<h1>Hello!</h1><p>Welcome to our platform.</p>"
}

Response:

{
  "recipient": "recipient@example.com",
  "status": "success"
}

Step 4: Send to Multiple Recipients

Request Body:

{
  "type": "sms",
  "to": ["+254712345678", "+254723456789", "+254734567890"],
  "message": "Bulk message to multiple recipients!"
}

Response:

[
  { "recipient": "+254712345678", "status": "success" },
  { "recipient": "+254723456789", "status": "success" },
  { "recipient": "+254734567890", "status": "success" }
]

Understanding Responses

Success Response

When a message is sent successfully:

{
  "recipient": "+254712345678",
  "status": "success"
}

Error Response

When something goes wrong:

{
  "statusCode": 400,
  "message": "Invalid phone number format",
  "error": "Bad Request"
}

Common HTTP Status Codes

| Code | Meaning | Common Causes | |------|---------|---------------| | 200 | Success | Request processed successfully | | 201 | Created | Resource created successfully | | 400 | Bad Request | Invalid input data, missing required fields | | 401 | Unauthorized | Missing or invalid authentication token | | 403 | Forbidden | Insufficient permissions (admin required) | | 404 | Not Found | Resource doesn't exist | | 500 | Server Error | Internal server issue |

Next Steps

Now that you've sent your first messages, explore more features:

Authentication - Understand JWT tokens and login
Contacts Management - Organize your recipients
Channel Guides - Deep dive into SMS, Email, WhatsApp
Campaigns - Schedule and automate bulk messaging
API Reference - Complete endpoint documentation

Need Help?

Email: support@notifyhub.com
Documentation: https://docs.notifyhub.com
Status Page: https://status.notifyhub.com

Code Examples

JavaScript/Node.js

const axios = require('axios');
 
const notifyhub = {
  baseURL: 'https://api.notifyhub.com',
  token: 'YOUR_TOKEN_HERE',
  
  async sendSMS(to, message) {
    try {
      const response = await axios.post(
        `${this.baseURL}/notifications/send`,
        { type: 'sms', to, message },
        { headers: { Authorization: `Bearer ${this.token}` } }
      );
      return response.data;
    } catch (error) {
      console.error('Error:', error.response.data);
      throw error;
    }
  },
  
  async sendEmail(to, subject, message) {
    try {
      const response = await axios.post(
        `${this.baseURL}/notifications/send`,
        { type: 'email', to, subject, message },
        { headers: { Authorization: `Bearer ${this.token}` } }
      );
      return response.data;
    } catch (error) {
      console.error('Error:', error.response.data);
      throw error;
    }
  }
};
 
// Usage
(async () => {
  // Send SMS
  await notifyhub.sendSMS('+254712345678', 'Hello from Node.js!');
  
  // Send Email
  await notifyhub.sendEmail(
    'user@example.com',
    'Test Email',
    '<p>Hello from Node.js!</p>'
  );
})();

Python

import requests
 
class NotifyHub:
    def __init__(self, token):
        self.base_url = 'https://api.notifyhub.com'
        self.token = token
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    
    def send_sms(self, to, message):
        response = requests.post(
            f'{self.base_url}/notifications/send',
            headers=self.headers,
            json={'type': 'sms', 'to': to, 'message': message}
        )
        response.raise_for_status()
        return response.json()
    
    def send_email(self, to, subject, message):
        response = requests.post(
            f'{self.base_url}/notifications/send',
            headers=self.headers,
            json={
                'type': 'email',
                'to': to,
                'subject': subject,
                'message': message
            }
        )
        response.raise_for_status()
        return response.json()
 
# Usage
notifyhub = NotifyHub('YOUR_TOKEN_HERE')
 
# Send SMS
notifyhub.send_sms('+254712345678', 'Hello from Python!')
 
# Send Email
notifyhub.send_email(
    'user@example.com',
    'Test Email',
    '<p>Hello from Python!</p>'
)

PHP

<?php
 
class NotifyHub {
    private $baseURL = 'https://api.notifyhub.com';
    private $token;
    
    public function __construct($token) {
        $this->token = $token;
    }
    
    private function request($endpoint, $data) {
        $ch = curl_init($this->baseURL . $endpoint);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->token,
            'Content-Type: application/json'
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode !== 200) {
            throw new Exception('Request failed: ' . $response);
        }
        
        return json_decode($response, true);
    }
    
    public function sendSMS($to, $message) {
        return $this->request('/notifications/send', [
            'type' => 'sms',
            'to' => $to,
            'message' => $message
        ]);
    }
    
    public function sendEmail($to, $subject, $message) {
        return $this->request('/notifications/send', [
            'type' => 'email',
            'to' => $to,
            'subject' => $subject,
            'message' => $message
        ]);
    }
}
 
// Usage
$notifyhub = new NotifyHub('YOUR_TOKEN_HERE');
 
// Send SMS
$notifyhub->sendSMS('+254712345678', 'Hello from PHP!');
 
// Send Email
$notifyhub->sendEmail(
    'user@example.com',
    'Test Email',
    '<p>Hello from PHP!</p>'
);
?>

Ready to build? Continue to Authentication to learn more about securing your API requests.