Email API
RevBridge Email API v1.0.0
Welcome to the RevBridge Email API, a comprehensive solution for professional email marketing campaign management. Our API provides everything you need to send, track, and analyze email campaigns at scale.
Overview
The RevBridge Email API is designed for modern applications that require reliable, high-performance email delivery with advanced tracking and analytics capabilities. Whether you're building a transactional email system, managing marketing campaigns, or creating a customer communication platform, our API provides the tools you need.
Core Capabilities
Email Sending
Our email sending engine is built for high-performance delivery with support for both transactional and marketing emails. The system features personalized templates with dynamic content substitution, ensuring each recipient receives a tailored message. The asynchronous queueing system processes thousands of emails per minute while maintaining delivery reliability.Key Features:
- Transactional & Marketing Emails: Send both automated system emails and promotional campaigns
- Template Personalization: Dynamic content with variable substitution per recipient
- High-Performance Queueing: Asynchronous processing for optimal throughput
- Real-Time Tracking: Live delivery status monitoring and reporting
- Real-Time Notifications: Instant alerts for email events and status changes
- Automatic Retry System: Built-in retry logic with exponential backoff for reliability
- HMAC Security: Secure webhook authentication with cryptographic signatures
- Performance Monitoring: Comprehensive metrics and health monitoring
- Delivery Statistics: Detailed metrics on email delivery and bounce rates
- Engagement Tracking: Monitor opens, clicks, and user interactions
- Deliverability Reports: Analyze sender reputation and inbox placement
- Performance Dashboard: Real-time visualization of key metrics
- JWT Authentication: Secure token-based authentication system
- Role-Based Access Control: Granular permissions and user management
- Rate Limiting: Protection against abuse and spam
- Data Validation: Rigorous input validation and sanitization
- Open & Click Tracking: Detailed engagement analytics with pixel tracking
- Suppression List Management: Automated unsubscribe and bounce handling
- Event Geolocation: Track user engagement by geographic location
- Multi-Domain Support: Manage multiple sending domains and configurations
Smart Webhooks
Stay informed about email events with our intelligent webhook system. Receive real-time notifications for delivery events, engagement metrics, and system status updates. The system includes automatic retry logic with exponential backoff to ensure reliable delivery of webhook notifications.Advanced Features:
Analytics & Reports
Gain deep insights into your email performance with our comprehensive analytics suite. Track delivery rates, engagement metrics, and deliverability scores to optimize your email strategy and improve campaign effectiveness.Analytics Capabilities:
Security & Compliance
Built with enterprise-grade security to protect your data and ensure compliance with email regulations. Our multi-layered security approach includes JWT authentication, role-based access control, and comprehensive audit logging.Security Features:
Advanced Features
Take your email campaigns to the next level with our advanced tracking and management tools. From detailed engagement analytics to automated list management, our features help you build better relationships with your audience.Advanced Capabilities:
---
*Developed by RevBridge | Version 1.0.0 | Interactive Documentation*
Environment Configuration
Base URL: https://api.{domain}
Authentication
The API uses Bearer Token (JWT) authentication. For protected endpoints, include the header:
Authorization: Bearer <your-jwt-token>
Authentication
https://api.{domain}/auth/login
User Login
User Authentication
Authenticate users and obtain access tokens for API usage. This endpoint serves as the primary entry point for user authentication in the RevBridge system, supporting multiple credential formats and providing secure token-based access.
How it works: The authentication process accepts either a username or email address along with the corresponding password. Upon successful validation, the system generates a JWT token that serves as the authentication mechanism for all subsequent API requests. The token includes user information, permissions, and expiration details.
Security features: Our authentication system implements rigorous credential validation with secure password hashing, JWT tokens signed with cryptographic keys, and built-in rate limiting to prevent brute force attacks. All login attempts are logged for security monitoring and audit purposes.
Token management: Generated tokens are valid for 30 minutes by default, providing a balance between security and usability. The token includes complete user information, domain associations, and role-based permissions that are automatically applied to subsequent API calls.
Request Body
{
"email": "user@example.com",
"password": "mypassword123"
}
Responses
cURL Example
curl -X POST "https://api.{domain}/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"mypassword123"}'
https://api.{domain}/auth/me
🔒 Protected
User Information
Authenticated User Information
Retrieve comprehensive information about the currently authenticated user. This endpoint provides detailed user data including identity, permissions, and session information, making it essential for building user interfaces and implementing role-based access control.
What you get: The response includes the user's unique identifier, username or email address, associated domain information, role-based permissions, and token metadata such as creation and expiration timestamps. This information is crucial for determining what actions the user can perform and what data they can access.
Common use cases: This endpoint is typically used to verify token validity, populate user interface elements with current user data, validate permissions before performing sensitive operations, and maintain user session state in client applications. It's also useful for implementing user profile displays and permission-based UI rendering.
Authentication required: This endpoint requires a valid JWT token in the Authorization header. The token must be active and not expired to successfully retrieve user information.
Responses
cURL Example
curl -X GET "https://api.{domain}/auth/me" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json"
https://api.{domain}/auth/users
🔒 Protected
List Users
List System Users
Retrieve a comprehensive list of users within your domain. This administrative endpoint provides visibility into all user accounts, their roles, and account status, enabling effective user management and oversight.
Administrative access: This endpoint is restricted to users with administrative privileges only. The system enforces role-based access control to ensure only authorized personnel can view user information. Additionally, the results are scoped to your domain, ensuring you only see users within your organization.
Comprehensive user data: The response includes detailed information about each user, including their basic profile information, assigned roles and permissions, current account status (active or inactive), and account creation timestamps. This data is essential for user management, security auditing, and understanding your organization's user base.
Scalable design: The endpoint supports pagination to handle large user lists efficiently. This ensures optimal performance even for organizations with thousands of users, allowing you to retrieve user data in manageable chunks.
Responses
cURL Example
curl -X GET "https://api.{domain}/auth/users" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json"
https://api.{domain}/auth/users
🔒 Protected
Create User
Create New User
Create new user accounts within your domain with comprehensive validation and security measures. This administrative endpoint enables you to onboard new team members, set up appropriate permissions, and maintain proper access control across your organization.
Administrative control: Only users with administrative privileges can create new accounts, ensuring proper oversight of user provisioning. The system automatically associates new users with your domain, maintaining organizational boundaries and data isolation.
Robust validation: Every new user account undergoes rigorous validation to ensure data integrity and security. The system validates email format and uniqueness, enforces strong password requirements, and verifies that all required information is properly formatted. This prevents duplicate accounts and ensures security best practices.
Flexible user setup: You can define user roles and permissions during account creation, allowing you to grant appropriate access levels from the start. The system supports various user types and permission levels, enabling you to implement least-privilege access principles. New accounts are automatically activated and ready for immediate use.
Required information: To create a new user, you'll need to provide a unique email address, a secure password that meets our security criteria, and the desired role or permission level. Additional profile information such as name and contact details are optional but recommended for better user management.
Request Body
{
"email": "newuser@example.com",
"password": "password123",
"name": "New User",
"role": "user"
}
Responses
cURL Example
curl -X POST "https://api.{domain}/auth/users" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"email":"newuser@example.com","password":"password123","name":"New User","role":"user"}'
https://api.{domain}/auth/users/{user_id}/password
🔒 Protected
Change Password
Change User Password
Securely update user passwords with comprehensive security measures and immediate effect. This endpoint ensures password changes are performed safely while maintaining account security and invalidating potentially compromised sessions.
Security-first approach: The password change process requires verification of the current password to prevent unauthorized access. The system enforces strong password requirements including minimum length, complexity rules, and checks against common password patterns. This ensures that new passwords meet security best practices and are resistant to common attack methods.
Immediate security measures: Once a password is successfully changed, the new password takes effect immediately across all systems. For enhanced security, all other active sessions for the user are automatically invalidated, forcing re-authentication with the new password. This prevents unauthorized access from any previously authenticated sessions.
Required verification: To change a password, you must provide the current password for verification, ensuring that only authorized users can modify account credentials. The new password must meet our security criteria, and the user ID must be specified in the path parameter to identify the target account.
Authentication requirement: This endpoint requires a valid JWT token in the Authorization header, ensuring that only authenticated users can initiate password changes.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
user_id
Required
|
path | string |
User ID |
Request Body
{
"current_password": "currentpass123",
"new_password": "newpass456"
}
Responses
cURL Example
curl -X PUT "https://api.{domain}/auth/users/{user_id}/password" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"current_password":"currentpass123","new_password":"newpass456"}'
Emails
https://api.{domain}/emails/send
🔒 Protected
Send Email
Send Transactional/Marketing Email
Send high-volume emails through our robust queueing system designed for both transactional and marketing campaigns. This endpoint provides the core functionality for email delivery with advanced personalization, tracking, and performance optimization.
Advanced personalization: Create highly personalized email experiences with dynamic content substitution for each recipient. The system supports both HTML and plain text formats, allowing you to craft rich, engaging emails while maintaining accessibility. You can include both content types in a single request, ensuring maximum compatibility across email clients.
High-performance delivery: Our asynchronous queueing system processes thousands of emails per minute while maintaining delivery reliability. The system automatically handles retry logic for failed deliveries, implements intelligent backoff strategies, and provides real-time status tracking for monitoring campaign performance.
Comprehensive tracking: Every email sent through this endpoint includes automatic open and click tracking capabilities. The system generates unique tracking pixels and clickable links, providing detailed engagement analytics that help you understand recipient behavior and optimize future campaigns.
Flexible configuration: Set email priority levels from 1 to 10 to control processing order, add custom headers for specialized requirements, and specify target SMTP servers for load balancing. The system supports up to 1000 recipients per request, with a 30-second timeout to ensure responsive API performance.
Authentication required: This endpoint requires a valid JWT token in the Authorization header to ensure secure access to email sending capabilities.
Request Body
{
"personalizations": [
{
"to": [
{
"address": "recipient@example.com",
"name": "John Silva"
}
],
"substitutions": {
"{{name}}": "John Silva",
"{{company}}": "XYZ Company"
},
"headers": {
"X-Custom-Header": "custom-value"
}
}
],
"headers": {
"X-Global-Header": "global-value"
},
"from": {
"address": "noreply@revbridge.com",
"name": "RevBridge Team"
},
"subject": "Welcome {{name}}!",
"content": [
{
"type": "text/plain",
"value": "Hello {{name}}, welcome to {{company}}!"
},
{
"type": "text/html",
"value": "<h1>Hello {{name}}</h1><p>Welcome to <strong>{{company}}</strong>!</p>"
}
],
"priority": 5,
"server": "server-1"
}
Responses
cURL Example
curl -X POST "https://api.{domain}/emails/send" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"personalizations":[{"to":[{"address":"recipient@example.com","name":"John Silva"}],"substitutions":{"{{name}}":"John Silva","{{company}}":"XYZ Company"},"headers":{"X-Custom-Header":"custom-value"}}],"headers":{"X-Global-Header":"global-value"},"from":{"address":"noreply@revbridge.com","name":"RevBridge Team"},"subject":"Welcome {{name}}!","content":[{"type":"text/plain","value":"Hello {{name}}, welcome to {{company}}!"},{"type":"text/html","value":"Hello {{name}}
Welcome to {{company}}!
"}],"priority":5,"server":"server-1"}'
https://api.{domain}/emails/status/{message_id}
🔒 Protected
Email Status
Check Delivery Status
Monitor the real-time delivery status of individual emails with comprehensive tracking information. This endpoint provides detailed insights into email processing, delivery attempts, and final outcomes, enabling you to track campaign performance and troubleshoot delivery issues.
Comprehensive status tracking: The system tracks emails through their entire lifecycle, from initial queuing to final delivery. You can monitor various statuses including pending (awaiting processing), queued (in sending queue), sending (currently being transmitted), sent (successfully transmitted), delivered (confirmed receipt), bounced (returned by recipient server), and failed (delivery unsuccessful).
Detailed delivery information: Each status check returns comprehensive details including the current email status, precise event timestamps, DSN (Delivery Status Notification) codes when available, the number of delivery attempts made, and the recipient email address. This information is crucial for understanding delivery patterns and identifying potential issues.
Real-time monitoring capabilities: This endpoint is designed for real-time monitoring applications, allowing you to build user interfaces that show live delivery status, implement automated notifications for delivery events, and provide users with immediate feedback on their email campaigns. It's also invaluable for investigating delivery problems and confirming successful email delivery.
Authentication required: This endpoint requires a valid JWT token in the Authorization header to ensure secure access to delivery status information.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
message_id
Required
|
path | string |
Unique message ID |
domain_id
Required
|
query | string |
Domain ID |
Responses
cURL Example
curl -X GET "https://api.{domain}/emails/status/{message_id}" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json"
https://api.{domain}/emails/history
🔒 Protected
Email History
Retrieve Email History
Access comprehensive email history with powerful filtering and analysis capabilities. This endpoint provides detailed historical data about your email campaigns, enabling thorough analysis, reporting, and performance monitoring across all your email activities.
Advanced filtering system: Filter your email history by specific delivery statuses (sent, delivered, bounced, etc.), date ranges, and other criteria to focus on the data that matters most. The system supports complex filter combinations, allowing you to drill down into specific campaigns, time periods, or delivery outcomes for detailed analysis.
Comprehensive historical data: Retrieve detailed information about each email including delivery status, timestamps, recipient information, and campaign metadata. The response includes pagination metadata to help you navigate through large datasets efficiently, along with statistics about applied filters to understand your data scope.
Scalable data access: The endpoint supports pagination with a maximum of 1000 items per page, ensuring optimal performance even when dealing with extensive email histories. Results are ordered by timestamp with the most recent emails first, making it easy to review recent activity and identify trends.
Analytics and reporting: This endpoint is essential for generating delivery reports, analyzing campaign performance, investigating delivery issues, and monitoring overall email system health. The rich historical data enables you to identify patterns, track improvements, and make data-driven decisions about your email strategy.
Authentication required: This endpoint requires a valid JWT token in the Authorization header to ensure secure access to historical email data.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
domain_id
Required
|
query | string |
Domain ID |
page
|
query | integer |
Page number |
limit
|
query | integer |
Items per page limit |
status
|
query | string |
Filter by status (e.g., sent, delivered, bounced). |
start_date
|
query | string |
Start date (YYYY-MM-DD) |
end_date
|
query | string |
End date (YYYY-MM-DD) |
Responses
cURL Example
curl -X GET "https://api.{domain}/emails/history" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json"
Webhook Management
https://api.{domain}/webhooks/
🔒 Protected
Create Webhook
Create New Webhook
Endpoint for creating a new webhook that will be triggered on specific email events. This endpoint allows for comprehensive webhook configuration, including event selection, security settings, and retry policies.
Key Features:
- Multiple Events: Subscribe to various event types in a single webhook.
- HMAC Security: Secure your webhook with a secret key for signature validation.
- Custom Headers: Include custom headers in webhook requests for easier integration.
- Smart Retries: Configure an intelligent retry system with exponential backoff.
- Configurable Timeout: Set a custom timeout for webhook requests to match your system's performance.
Request Body
{
"name": "My Webhook",
"url": "https://example.com/my-webhook",
"events": [
"delivered",
"bounced"
],
"secret_key": "supersecret"
}
Responses
cURL Example
curl -X POST "https://api.{domain}/webhooks/" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"name":"My Webhook","url":"https://example.com/my-webhook","events":["delivered","bounced"],"secret_key":"supersecret"}'
https://api.{domain}/webhooks/
🔒 Protected
List Webhooks
List Webhooks
Endpoint for listing webhooks with advanced filtering and pagination. This allows for easy management and overview of all configured webhooks.
Filtering Options:
- Status: Filter webhooks by active or inactive status.
- Event Type: Find webhooks subscribed to specific events.
- Search: Search by webhook name or URL.
- Pagination: Control the number of results with limit and offset parameters.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
is_active
|
query | boolean |
Filter by active status |
event_type
|
query | string |
Filter by a specific event type |
search
|
query | string |
Search by name or URL |
limit
|
query | integer |
Limit results |
offset
|
query | integer |
Offset for pagination |
Responses
cURL Example
curl -X GET "https://api.{domain}/webhooks/" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json"
https://api.{domain}/webhooks/{webhook_id}
🔒 Protected
Get Webhook
Get Specific Webhook
Endpoint for retrieving a specific webhook by its ID. This provides the full configuration details of a single webhook.
Information Returned:
- Complete webhook configuration, including name, URL, and events.
- Activation status, retry and timeout settings, and custom headers.
- Creation and last update timestamps.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
webhook_id
Required
|
path | integer |
Webhook ID |
Responses
cURL Example
curl -X GET "https://api.{domain}/webhooks/{webhook_id}" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json"
https://api.{domain}/webhooks/{webhook_id}
🔒 Protected
Update Webhook
Update Webhook
Endpoint for updating an existing webhook. This allows for modification of all configurable webhook parameters.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
webhook_id
Required
|
path | integer |
Webhook ID |
Request Body
{
"name": "My Updated Webhook",
"url": "https://example.com/my-updated-webhook",
"events": [
"delivered",
"bounced",
"opened"
]
}
Responses
cURL Example
curl -X PUT "https://api.{domain}/webhooks/{webhook_id}" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"name":"My Updated Webhook","url":"https://example.com/my-updated-webhook","events":["delivered","bounced","opened"]}'
https://api.{domain}/webhooks/{webhook_id}
🔒 Protected
Delete Webhook
Delete Webhook
Endpoint for deleting a webhook. This action is irreversible and will stop all event notifications for the specified webhook.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
webhook_id
Required
|
path | integer |
Webhook ID |
Responses
cURL Example
curl -X DELETE "https://api.{domain}/webhooks/{webhook_id}" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json"
https://api.{domain}/webhooks/{webhook_id}/toggle
🔒 Protected
Toggle Webhook
Toggle Webhook Status
Endpoint for activating or deactivating a webhook. This provides a quick way to enable or disable event notifications without deleting the webhook configuration.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
webhook_id
Required
|
path | integer |
Webhook ID |
is_active
Required
|
query | boolean |
Set webhook to active or inactive |
Responses
cURL Example
curl -X PATCH "https://api.{domain}/webhooks/{webhook_id}/toggle" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json"
https://api.{domain}/webhooks/bulk-toggle
🔒 Protected
Bulk Toggle Webhooks
Bulk Toggle Webhook Status
Endpoint for activating or deactivating multiple webhooks at once. This is useful for managing the status of several webhooks in a single API call.
Request Body
{
"webhook_ids": [
1,
2,
3
],
"is_active": false
}
Responses
cURL Example
curl -X POST "https://api.{domain}/webhooks/bulk-toggle" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"webhook_ids":[1,2,3],"is_active":false}'
https://api.{domain}/webhooks/{webhook_id}/test
🔒 Protected
Test Webhook
Test Webhook
Endpoint for sending a test payload to a webhook. This allows for verification of the webhook endpoint and payload processing before use in a production environment.
Key Features:
- Custom Payload: Send custom data in the test payload.
- Asynchronous Processing: The test is queued and processed in the background.
- Detailed Logs: Review the test results in the webhook logs.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
webhook_id
Required
|
path | integer |
Webhook ID |
Request Body
{
"webhook_id": 1,
"test_payload": {
"message_id": "test_msg_123",
"status": "delivered"
}
}
Responses
cURL Example
curl -X POST "https://api.{domain}/webhooks/{webhook_id}/test" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"webhook_id":1,"test_payload":{"message_id":"test_msg_123","status":"delivered"}}'
Health
https://api.{domain}/
Service Information
Service Information
Access basic service information and status details for the RevBridge Email API. This public endpoint provides essential information about the service, including version details, current status, and basic configuration information.
Service overview: The endpoint returns comprehensive service information including the service name, current version number, API status, and basic configuration details. This information is essential for service discovery, version checking, and understanding the current state of the API.
Health indicators: Get real-time health indicators that show the current operational status of the service. These indicators help you determine if the API is functioning normally and can help with troubleshooting connectivity or service issues.
Common applications: This endpoint is typically used for service discovery in microservices architectures, health monitoring in automated systems, API version checking for compatibility verification, and general status verification. It's also useful for building service dashboards and monitoring applications.
Responses
cURL Example
curl -X GET "https://api.{domain}/" \
-H "Content-Type: application/json"
https://api.{domain}/health
Health Check
Service Health Verification
Perform comprehensive health checks to verify the operational status of the RevBridge Email API and its dependencies. This public endpoint provides detailed health information for monitoring, load balancing, and automated system management.
Comprehensive health monitoring: The endpoint checks multiple system components including service status (running or stopped), database connectivity, queue system status, and external service dependencies. This multi-layered health check ensures that all critical components are functioning properly and can handle incoming requests.
Real-time status reporting: Get immediate feedback on the current health status of the service, allowing you to quickly identify any issues or outages. The health check covers both internal system components and external dependencies, providing a complete picture of service availability.
Integration capabilities: This endpoint is designed for integration with load balancers, monitoring systems, and automated recovery mechanisms. It provides the health status information needed for load balancer health checks, monitoring system integration, service availability verification, and triggering automated recovery procedures when issues are detected.
Responses
cURL Example
curl -X GET "https://api.{domain}/health" \
-H "Content-Type: application/json"
https://api.{domain}/info
Detailed Information
Detailed Service Information
Access comprehensive service information including detailed configuration, version details, and system capabilities. This public endpoint provides in-depth information about the RevBridge Email API for system diagnostics, configuration verification, and troubleshooting support.
Comprehensive system details: The endpoint returns detailed information about the complete service configuration, including all available features, performance metrics, and system requirements. This information is essential for understanding the full capabilities of the API and ensuring proper integration.
Version and feature information: Get detailed version information including API version, feature availability, and compatibility details. This helps you understand which features are available in your current version and plan for future upgrades or feature utilization.
Diagnostic capabilities: This endpoint is particularly useful for system diagnostics, configuration verification, feature availability checking, and troubleshooting support. The detailed information helps identify configuration issues, verify system capabilities, and resolve integration problems.
Performance insights: Access performance metrics and system requirements that help you understand the API's capabilities and plan your integration accordingly. This information is valuable for capacity planning and performance optimization.
Responses
cURL Example
curl -X GET "https://api.{domain}/info" \
-H "Content-Type: application/json"