README

NotifyHub API Documentation

Unified notifications platform for SMS, Email, and WhatsApp messaging

Welcome to the NotifyHub API documentation. This guide will help you integrate multi-channel messaging into your applications quickly and securely.

📚 Table of Contents

Getting Started

  1. Getting Started

    • Quick start guide
    • Your first API call
    • Code examples (JavaScript, Python, PHP)

  2. Authentication

    • Sign up and login
    • JWT tokens
    • Security best practices

Core Features

  1. Contacts & Groups

    • Managing contacts
    • Organizing with groups
    • Bulk operations

  2. Multi-Channel Messaging

    • SMS via Lancola
    • Email via SMTP
    • WhatsApp via Meta Cloud API
    • Attachments and formatting

  3. Campaigns

    • Create and schedule campaigns
    • Targeted messaging
    • Analytics and tracking

Reference

  1. Complete API Reference
    • All endpoints documented
    • Request/response examples
    • Error handling

🚀 Quick Start

1. Sign Up

curl -X POST https://api.notifyhub.com/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@yourcompany.com",
    "password": "SecurePassword123!",
    "countryCode": "+254",
    "phoneNumber": "712345678",
    "companyName": "Your Company Ltd",
    "sector": "Technology",
    "country": "Kenya"
  }'

2. Send Your First Message

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

📖 Documentation Structure

Phase 1: Essential Documentation (✅ Complete)

  • [x] Getting Started Guide
  • [x] Authentication
  • [x] Core Messaging (SMS, Email, WhatsApp)
  • [x] Contacts Management
  • [x] Code Examples (cURL, JavaScript, Python)

Phase 2: Advanced Features (📝 In Progress)

  • [x] Campaigns
  • [ ] Message Logs & Analytics
  • [ ] Organization Management
  • [ ] User Management
  • [ ] Credential Configuration

Phase 3: Extended Resources (🔜 Coming Soon)

  • [ ] Webhooks
  • [ ] Templates
  • [ ] SDKs (JavaScript, Python, PHP)
  • [ ] Video Tutorials
  • [ ] Postman Collection

🌐 Base URL

All API requests are made to:

https://api.notifyhub.com

Test Environment (if available):

https://api-sandbox.notifyhub.com

🔐 Authentication

All API endpoints (except signup and login) require authentication via JWT tokens or API Keys.

Include your credentials in every request:

  • JWT: Authorization: Bearer YOUR_TOKEN_HERE
  • API Key: X-API-Key: YOUR_API_KEY_HERE or query param ?apikey=YOUR_API_KEY_HERE
Authorization: Bearer YOUR_TOKEN_HERE

Token expires after 24 hours. Login again to get a new token.

📡 Supported Channels

SMS

  • Provider: Lancola
  • Use Cases: OTP codes, alerts, reminders
  • Format: International phone numbers (+254712345678)
  • Cost: Per message (varies by destination)

Email

  • Provider: SMTP (any provider)
  • Use Cases: Newsletters, invoices, receipts
  • Format: Standard email addresses
  • Features: HTML, attachments, personalization

WhatsApp

  • Provider: Meta Cloud API
  • Use Cases: Customer support, notifications
  • Format: International phone numbers
  • Restrictions: 24-hour messaging window, templates required outside window

📊 Key Features

Multi-Channel Messaging

Send SMS, Email, and WhatsApp from a single API endpoint.

Contact Management

Organize recipients with groups, tags, and custom attributes.

Campaign Management

Schedule bulk messages, target specific audiences, track performance.

Real-Time Analytics

Monitor delivery rates, failures, and campaign metrics.

Flexible Credentials

Use default credentials or configure per-organization overrides.

Secure & Scalable

JWT authentication, organization-level isolation, enterprise-ready infrastructure.

🛠️ SDKs & Libraries

Official SDKs

  • JavaScript/Node.js: Coming soon
  • Python: Coming soon
  • PHP: Coming soon

Community SDKs

  • Submit your SDK via pull request!

Code Examples

Complete examples available in:

📝 Example Use Cases

Transactional Messages

// Send OTP code
await sendSMS('+254712345678', 'Your OTP: 483920. Valid for 10 min.');
 
// Order confirmation
await sendEmail(
  'customer@example.com',
  'Order Confirmed',
  '<h1>Thank you!</h1><p>Order #12345 confirmed.</p>'
);

Marketing Campaigns

// Create campaign
const campaign = await createCampaign({
  name: 'Winter Sale',
  channels: ['email', 'sms'],
  recipients: { groups: ['vip-customers'] },
  scheduleDate: '2026-02-01T09:00:00Z'
});
 
// Launch immediately
await launchCampaign(campaign._id);

Customer Support

// WhatsApp notification
await sendWhatsApp(
  '+254712345678',
  'Your support ticket #6789 has been created. We\'ll respond within 24h.'
);

🔧 Rate Limits

Current Limits (per organization):

  • No explicit platform limits (provider-side limits apply)
  • Recommended: Max 100 messages per batch
  • Implement your own rate limiting for best performance

Best Practices:

  • Batch requests when sending to multiple recipients
  • Implement retry logic with exponential backoff
  • Monitor delivery rates and adjust accordingly

🐛 Error Handling

All errors follow a consistent format:

{
  "statusCode": 400,
  "message": "Descriptive error message",
  "error": "Bad Request"
}

Common HTTP Status Codes:

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request (invalid input)
  • 401 - Unauthorized (missing/invalid token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 500 - Server Error

See Error Handling Guide for detailed examples.

🔒 Security

Best Practices

  1. Never expose tokens in client-side code or version control
  2. Use HTTPS only for all API requests
  3. Rotate tokens regularly by logging in periodically
  4. Implement rate limiting to prevent abuse
  5. Validate input before sending to API
  6. Monitor for suspicious activity

Data Privacy

  • All data is encrypted in transit (TLS 1.2+)
  • Organization-level data isolation
  • GDPR compliance features available
  • SOC 2 Type II certified (coming soon)

📞 Support

Documentation

Contact

  • Email: support@notifyhub.com
  • Status Page: https://status.notifyhub.com
  • Community Forum: https://community.notifyhub.com

Response Times

  • Critical issues: < 1 hour
  • General support: < 24 hours
  • Feature requests: Reviewed weekly

🗺️ Roadmap

Q1 2026

  • ✅ Core API (SMS, Email, WhatsApp)
  • ✅ Campaigns
  • 🔜 Webhooks
  • 🔜 Templates

Q2 2026

  • Official SDKs (JavaScript, Python, PHP)
  • Advanced analytics (open rates, click tracking)
  • A/B testing for campaigns
  • Two-factor authentication

Q3 2026

  • Voice calls API
  • Push notifications
  • Automated workflows
  • AI-powered message optimization

📜 Changelog

v1.0.0 (January 2026)

  • Initial public API release
  • SMS, Email, WhatsApp channels
  • Contact and group management
  • Campaign scheduling and analytics
  • JWT authentication

See complete changelog for version history.

📄 License

NotifyHub API is a commercial product. Usage requires an active subscription.

Free Tier: 100 messages/month Paid Plans: Starting at $29/month

See pricing page for details.

🤝 Contributing

We welcome contributions to our documentation!

How to Contribute

  1. Fork the documentation repository
  2. Make your changes
  3. Submit a pull request
  4. We'll review and merge

Areas We Need Help

  • Additional code examples (other languages)
  • Tutorials and guides
  • Typo fixes and clarifications
  • SDK development

🎓 Learning Resources

Tutorials

Video Guides

  • Getting Started (5 min) - Coming soon
  • Advanced Campaigns (10 min) - Coming soon
  • WhatsApp Integration (8 min) - Coming soon

Blog Posts

⚡ Quick Links

Ready to get started? → Send your first message now