Campaign Messages Management
This API provides comprehensive campaign management and message export capabilities, enabling external systems to retrieve campaign data and download generated customer messages in multiple formats.Introduction#
The Campaign Messages Management API enables organisations to integrate with the campaign and messaging system:Campaign Listing: Retrieve all campaigns grouped by workspace with status and metadata
Async Message Export: Queue bulk message exports for background processing
Storage Integration: Messages stored securely with account and campaign isolation
Multiple Export Formats: Download messages as UTF-8 CSV, JSON array, or pre-signed URL
Usage Tracking: Quota enforcement for message generation and export operations
Field Descriptions#
Response: Message Export Fields
Endpoints#
Endpoints Overview#
| Endpoint | Method | Purpose | Access Control |
|---|
/v1/campaign/all | POST | List all campaigns grouped by workspace | API Authentication (JWT + API Headers) |
POST /v1/messages/publish | POST | Queue async message export | API Authentication + Usage Quota Check |
POST /v1/messages/pages | POST | Get count of exported message files | API Authentication + Usage Tracking |
POST /v1/messages/fetch | POST | Download specific message file | API Authentication |
Authentication#
All endpoints require API authentication via HTTP headers.| Header | Required | Description |
|---|
| authorization | Yes | Bearer token (JWT) containing user_id, account_id, role_code |
| x-auth-context | Yes | JSON object: { "api_access": true, "api_code": "<API_CODE>" } |
| x-ip | Yes | Client IP address for audit logging |
| x-api-key | No | Optional API key for additional validation |
Authentication Flow#
1.
API Code Validation: Validate api_code in x-auth-context matches server configuration
2.
JWT Verification: Verify JWT token signature against API secret
3.
Access Check: Confirm api_access is set to true
4.
Account Extraction: Extract account_id from JWT for data isolation
authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-auth-context: {"api_access": true, "api_code": "your-api-code"}
x-ip: 192.168.1.100
Content-Type: application/json
Endpoint#
Description#
Retrieves all campaigns for the authenticated account, organized by workspace. Returns essential campaign metadata including status, stage, and date range for each campaign.Purpose#
Enables external systems to discover available campaigns and their current state, facilitating integration with CRM systems, dashboards, and campaign management tools.Business Use Cases#
Integration Dashboards: Display all campaigns in an external management interface.
Campaign Selection: Allow users to choose which campaign's messages to export.
Status Monitoring: Track campaign progress and workflow stages across workspaces.
Reporting: Generate reports on campaign activity by workspace.
Workflow Automation: Trigger actions based on campaign status changes.
Security Features#
JWT token validation with account-specific secret.
API code verification against server configuration.
Account-level data isolation (only returns campaigns for authenticated account).
All queries scoped to authenticated account_id.
Endpoint#
POST /v1/messages/publish
Description#
Exports generated campaign messages to secure cloud storage in CSV format, making them accessible for download and integration with external systems. When the campaign is in the "Ready to Publish" stage, the campaign will move to the "Published" stage and the campaign messages will also be published.Purpose#
Enables secure, scalable access to generated messages for campaign execution, analytics, and integration with delivery platforms.Business Use Cases#
Bulk Download Preparation: Prepare large message datasets for download.
Marketing Automation: Feed generated messages into marketing automation platforms.
Multi-Channel Delivery: Export messages for distribution across multiple channels.
Security Features#
Full API authentication stack.
Usage quota enforcement prevents resource abuse.
Campaign ownership validation.
Async processing prevents request timeout on large datasets.
Endpoint#
Description#
Returns the total count of exported message files stored for a specific campaign. Used to determine pagination when downloading message files.Purpose#
Allows applications to understand the size of the exported dataset and implement proper pagination controls for downloading message files.Business Use Cases#
Pagination UI: Build page navigation controls in download interfaces.
Progress Indicators: Display download progress (e.g., "File 3 of 10").
Export Validation: Verify that message export completed successfully.
Batch Processing: Plan batch download operations based on file count.
Memory Management: Allocate appropriate resources for processing downloads.
Security Features#
API authentication required.
Queries scoped to account's path prefix.
No actual message data exposed (only file count).
Efficient query that doesn't load file contents.
Endpoint#
Description#
Downloads a specific exported message file in the requested format. Supports three output formats: raw UTF-8 CSV content, parsed JSON array, or a pre-signed URL for direct download.Purpose#
Provides flexible options for retrieving exported message data, accommodating different integration requirements and use cases.Business Use Cases#
Direct Integration (JSON): Parse messages programmatically for CRM or marketing automation.
Spreadsheet Export (UTF-8): Download raw CSV for import into Excel or Google Sheets.
Secure Sharing (URL): Generate time-limited URLs for secure file sharing.
Bulk Processing: Download files sequentially for batch processing pipelines.
Data Analysis: Retrieve messages for analytics and reporting tools.
Security Features#
Campaign ownership validation via account_id.
Pre-signed URLs have limited validity period.
Export Type Options#
The data transforms based on the export_type:| Type | Description | Use Cases |
|---|
utf8 | Returns raw CSV file content as UTF-8 string | Direct file processing, spreadsheet import |
json | Returns parsed array of {customer_id, message} JSON objects (max 1000 rows) | API integration, small dataset processing |
url | Generates pre-signed URL for direct download | Browser downloads, secure sharing |
Security & Compliance#
Data Protection#
Account-Level Isolation: All data queries filtered by account_id from JWT
Pre-signed URL Expiry: Generated URLs have limited validity (typically 1 hour)
Encrypted Transport: All API communications over HTTPS
Access Control#
JWT Authentication: All endpoints require valid JWT token
API Code Validation: api_code must match server configuration
Campaign Ownership: Campaign queries validate account ownership
Database Context: All operations use authenticated database context
Usage Tracking#
Quota Enforcement: Message exports tracked against account quota
Usage Limit Response: Returned when quota exceeded
Usage Middleware: Applied to /api/store and /api/pages endpoints
Audit Logging#
User Context: All operations logged with user ID
Job Tracking: Async operations tracked with unique job IDs
Timestamp Recording: Creation and modification times recorded
Common Error Codes#
| Status Code | Description | Common Causes |
|---|
| 400 | Bad Request | Malformed JSON, invalid data types |
| 401 | Unauthorized | Missing required fields, campaign not found, invalid export option |
| 403 | Forbidden | Missing authentication headers, invalid API code, invalid JWT |
| 404 | Not Found | Campaign not found, file not found |
| 500 | Internal Server Error | Database errors, CSV parsing failures |
Specific Error Messages#
| Message | Cause | Resolution |
|---|
"auth error" | Missing req.auth or entity manager | Ensure valid JWT token in authorization header |
"Unauthorized" | API validation failed | Verify x-auth-context contains valid api_code |
"Missing required fields." | Required body fields missing | Include all required fields in request body |
"Campaign/details not found." | Campaign missing messages or audience | Ensure campaign has generated messages and audience setup |
"Campaign not found." | Invalid campaign_id | Verify campaign_id exists and belongs to account |
"File not found." | File doesn't exist | Check file_num is within valid range (0 to num_files-1) |
"Invalid export option." | Invalid export_type value | Use utf8, json, or url |
"Failed to parse." | CSV parsing error | Contact support if error persists |
Modified at 2026-02-02 06:54:15
