Campaigns and Campaign Messages
This API provides comprehensive message management capabilities for marketing campaigns, including AI-powered message generation, approval workflows, and secure message storage and retrieval.Introduction#
The Campaign Messages API enables organisations to:AI Message Generation: Create personalised messages using advanced AI models
Message Storage & Retrieval: Securely store and access campaign messages
Approval Workflows: Manage message review and approval processes
Bulk Operations: Handle large-scale message generation and export
Endpoints Overview#
| Endpoint | Method | Description |
|---|
/v1/campaign/all | POST | Get all campaigns across workspaces |
/v1/messages/publish | POST | Export messages to secure storage |
/v1/messages/fetch | POST | Retrieve stored message files |
Endpoints#
Endpoint#
Description#
Retrieves all campaigns associated with your account, organised by workspace, providing a comprehensive overview of campaign activity across your organization.Purpose#
Enables applications to display and manage all campaigns in your account with workspace-level organisation for better campaign oversight and management.Business Use Cases#
Campaign Dashboard: Display all campaigns in management interfaces and dashboards
Cross-Workspace Analytics: Analyse campaign performance across different business units
Resource Planning: Understand campaign workload and resource allocation
Campaign Portfolio Management: Manage multiple campaigns across different workspaces
Team Collaboration: Provide team members with visibility into all relevant campaigns
Reporting & Analytics: Generate comprehensive reports across all campaign activities
Campaign Management Strategy#
This endpoint supports comprehensive campaign management by:Centralised Visibility: Single API call provides a complete campaign overview
Workspace Organisation: Maintains business unit separation while enabling cross-functional visibility
Status Tracking: Real-time campaign status for operational management
Team Collaboration: Creator attribution for accountability and communication
Organisational Benefits#
Operational Efficiency: Quick access to all campaign information
Resource Management: Understanding of campaign workload across teams
Performance Monitoring: Status and stage tracking for all campaigns
Compliance Oversight: Centralised view for governance and compliance
Endpoint#
POST /v1/messages/publishDescription#
Exports generated campaign messages to secure cloud storage in CSV format, making them accessible for download and integration with external systems.Purpose#
Enables secure, scalable access to generated messages for campaign execution, analytics, and integration with delivery platforms.Business Use Cases#
Campaign Execution: Export messages for email marketing platforms or SMS services
Compliance Documentation: Store messages for regulatory compliance and audit trails
Analytics Integration: Export data for campaign performance analysis
Backup & Archive: Create secure backups of campaign content
Third-Party Integration: Provide message data to external delivery systems
Quality Assurance: Export messages for review before campaign launch
Technical Implementation#
The system processes all approved messages for the campaign and exports them as a CSV file to secure cloud storage. The export includes customer data, personalised messages, and metadata required for campaign execution.Security Features#
Usage Limits: Validates account limits before processing large exports
Secure Storage: Files stored in encrypted, access-controlled cloud storage
Account Scoping: Only exports messages belonging to your account
Asynchronous Processing: Large exports handled without blocking other operations
Endpoint#
Description#
Retrieves campaign message files in various formats, including raw CSV, parsed JSON, or secure download URLs.Purpose#
Provides flexible access to stored message files with multiple export options to support different integration patterns.Business Use Cases#
Direct Integration: Retrieve JSON data for direct API integration
File Downloads: Generate secure URLs for manual file downloads
Data Processing: Access raw CSV data for custom processing workflows
Analytics Integration: Export data for business intelligence and reporting tools
Campaign Management: Display message content in management interfaces
Quality Assurance: Review message content before campaign launch
Technical Implementation#
The system retrieves files from secure cloud storage and processes them according to the specified export type. JSON parsing extracts structured message data, while URL generation creates time-limited access links.Security Features#
Account Validation: Ensures file access is limited to your account
Time-Limited URLs: Download URLs expire after a set period for security
File Validation: Verifies file existence and accessibility before processing
Format Validation: Validates export type to prevent invalid requests
Description#
Returns the number of message files available for a campaign, enabling pagination when retrieving large message datasets.Purpose#
Allows applications to understand file structure and implement proper pagination for message retrieval.Business Use Cases#
UI Pagination: Build pagination controls for message file navigation
Batch Processing: Plan batch downloads of large message datasets
Progress Tracking: Show download progress for multi-file campaigns
Resource Planning: Understand file volume before initiating downloads
User Experience: Provide file count information in management interfaces
Technical Implementation#
The system queries cloud storage to count available message files for the specified campaign, returning the total count for pagination purposes.Security Features#
Account Scoping: Only counts files accessible to your account
Campaign Validation: Ensures you have access to the specified campaign
Efficient Queries: Uses optimised storage queries without downloading file content
Campaign Organisation Structure#
Workspace-Based Organization#
Campaigns are organised by workspace to provide:Department Separation: Marketing teams can manage campaigns by business unit
Permission Management: Access control at the workspace level
Resource Allocation: Budget and resource tracking per workspace
Performance Analysis: Compare performance across different business areas
Cross-Workspace Visibility#
The API provides account-level access to:Unified Dashboard: Single view of all campaign activity
Resource Planning: Understand total campaign workload
Compliance Oversight: Ensure all campaigns meet standards
Performance Benchmarking: Compare campaigns across workspaces
Usage Limits & Quotas#
Generation Limits#
Message Volume: Generation limited by your account's message quota
Concurrent Jobs: Limited number of simultaneous generation jobs
Rate Limiting: API calls are subject to rate limiting for optimal performance
Storage Limits#
File Size: Individual export files are limited to reasonable sizes
Retention Period: Files retained in storage for a specified period
Download Limits: Number of downloads may be limited per file
Security & Compliance#
Access Control#
Account Isolation: Users can only access campaigns within their account
Authentication Required: Valid API token required for all requests
Workspace Boundaries: Campaigns properly scoped to appropriate workspaces
User Attribution: Campaign creators properly identified for accountability
Data Protection#
Encryption: All data is encrypted in transit and at rest
Access Control: Strict account-level access controls
Audit Logging: Comprehensive logging of all message operations
Data Isolation: Complete separation between different accounts
Minimal Data Exposure: Only essential campaign information returned
AI Content Safety#
Content Filtering: AI-generated content filtered for appropriateness
Brand Guidelines: Messages generated according to configured brand standards
Compliance Checks: Automated compliance validation for regulated industries
Human Oversight: Optional human review workflows for sensitive content
Privacy Compliance#
Data Minimisation: Only necessary customer data is used in message generation
Retention Policies: Configurable data retention periods
Right to Deletion: Support for data deletion requests
Consent Management: Integration with consent management systems
User Privacy: Creator names are properly formatted and controlled
Access Auditing: Campaign access tracked for compliance reporting
Common Error Codes#
| Status Code | Description | Common Causes |
|---|
400 | Bad Request | Missing required fields, invalid campaign_id format |
401 | Unauthorized | Missing required fields, invalid campaign |
403 | Forbidden | Missing authentication, insufficient permissions |
404 | Not Found | Campaign not found, file not found |
429 | Too Many Requests | Rate limit exceeded, usage quota exceeded |
500 | Internal Server Error | AI service issues, storage service errors |
Modified at 2025-10-31 13:08:11
