API Documentation - usmantahirr/infobip-notification-service GitHub Wiki

The Infobip Notification Service provides RESTful APIs for sending email and SMS notifications. All endpoints require authentication using an API key.

All API requests require an API key to be included in the Authorization header:

Authorization: Bearer YOUR_API_KEY

• Rate limit: 100 requests per minute
• Rate limit headers are included in responses:
  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when the rate limit window resets

POST /api/v1/notifications/email

{
  "recipient": "[email protected]",
  "subject": "Welcome Email",
  "message": "Welcome to our platform!",
  "attachments": [
    {
      "filename": "document.pdf",
      "content": "base64_encoded_content",
      "contentType": "application/pdf"
    }
  ]
}

{
  "success": true,
  "messageId": "123456789",
  "timestamp": "2025-03-20T10:00:00Z"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "details": {
      "recipient": ["Invalid email format"]
    }
  }
}

POST /api/v1/notifications/sms

{
  "recipient": "+1234567890",
  "message": "Your verification code is: 123456"
}

{
  "success": true,
  "messageId": "123456789",
  "timestamp": "2025-03-20T10:00:00Z"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid phone number",
    "details": {
      "recipient": ["Invalid phone number format"]
    }
  }
}

• Recipient must be a valid email address
• Subject is required and max 100 characters
• Message is required
• Attachments:
  • Max file size: 2MB
  • Allowed types: PDF, DOC, DOCX, JPG, PNG
  • Max 5 attachments per request

• Recipient must be a valid phone number with country code
• Message is required and max 160 characters
• No special characters in message

All responses follow this format:

{
  "success": boolean,
  "data": object | null,
  "error": {
    "code": string,
    "message": string,
    "details": object | null
  } | null
}

# Send Email
curl -X POST https://api.example.com/api/v1/notifications/email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "[email protected]",
    "subject": "Welcome",
    "message": "Welcome to our platform!"
  }'

# Send SMS
curl -X POST https://api.example.com/api/v1/notifications/sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+1234567890",
    "message": "Your verification code is: 123456"
  }'

const { NotificationService } = require("infobip-notification-service");

const client = new NotificationService({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://api.example.com",
});

// Send Email
await client.sendEmail({
  recipient: "[email protected]",
  subject: "Welcome",
  message: "Welcome to our platform!",
});

// Send SMS
await client.sendSMS({
  recipient: "+1234567890",
  message: "Your verification code is: 123456",
});

1. Error Handling

   • Always check the success field in responses
   • Handle all possible error codes
   • Implement retry logic for transient errors

2. Rate Limiting

   • Monitor rate limit headers
   • Implement exponential backoff for retries
   • Consider implementing a queue for high-volume scenarios

3. Validation

   • Validate data before sending
   • Handle file size and type restrictions
   • Sanitize message content

4. Security

   • Keep API keys secure
   • Use HTTPS for all requests
   • Implement proper error logging

The complete OpenAPI specification is available at /api-docs endpoint when running the service.