Campaigns

Manage regular, AutoResponder, A/B Testing, or retargeting campaigns inside your account.
GET /campaigns/create-options

Retrieves all the selectable resources and metadata required to create or edit a campaign, including Lists, Segments, CAN-SPAM Addresses, Delivery Servers, Sending Domains, Tracking Domains, timezones, weekdays, and trigger events.

Response Example

{
    "success": true,
    "message": "Campaign creation options retrieved successfully.",
    "data": {
        "lists": [
            {
                "id": 1,
                "uuid": "4e73b75f-2c2d-9e1f-88b7-7a66c5d4b8f3",
                "name": "Newsletter List",
                "status": "active",
                "total_subscriber": 1250
            }
        ],
        "segments": [
            {
                "id": 1,
                "uuid": "8e3b75fa-9e1f-88b7-7a66-c5d4b8f34e73",
                "list_id": 1,
                "name": "Active in last 30 days"
            }
        ],
        "canspam_addresses": [
            {
                "id": 3,
                "uuid": "9a7b6f4a-3b4c-2d9e-1f88-b77a66c5d4b8",
                "company_name": "Acme Inc.",
                "address_1": "123 Business Rd",
                "city": "Metropolis",
                "state": "NY",
                "zip_code": "10001"
            }
        ],
        "sending_domains": [
            {
                "id": 1,
                "uuid": "7a66c5d4-b8f3-4e73-b75f-2c2d9e1f88b7",
                "domain_name": "acme.com",
                "from_email": "newsletter@acme.com",
                "status": "verified"
            }
        ],
        "tracking_domains": [
            {
                "id": 1,
                "uuid": "2c2d9e1f-88b7-7a66-c5d4-b8f34e73b75f",
                "domain_name": "track.acme.com",
                "status": "active"
            }
        ],
        "delivery_servers": [
            {
                "id": 5,
                "uuid": "88b77a66-c5d4-b8f3-4e73-b75f2c2d9e1f",
                "name": "AWS SES Dedicated Server",
                "server_speed": 1000
            }
        ],
        "timezones": [
            "UTC",
            "America/New_York",
            "Europe/London"
        ],
        "sending_days": [
            "monday",
            "tuesday",
            "wednesday",
            "thursday",
            "friday",
            "saturday",
            "sunday"
        ],
        "autoresponder_events": [
            "subscribe",
            "unsubscribe"
        ],
        "parent_campaigns": [
            {
                "id": 8,
                "uuid": "9c8a7b6f-4a3b-4c2d-9e1f-88b77a66c5d4",
                "campaign_name": "Summer Promotion 2026",
                "campaign_type": "regular",
                "status": "sent"
            }
        ]
    }
}
POST /campaigns

Creates a new campaign. Validates ownership and accessibility of all selected resources (Lists, Servers, CAN-SPAM, Domains).

Request Parameters

Parameter Type Status Description
campaign_type String Required Type of campaign: regular, autoresponder, ab_testing, or retargeting.
campaign_name String Required Name of the campaign.
subject String Required (unless ab_testing) Subject line of the email.
ab_subjects Array of Strings Required for ab_testing List of subject line variants (minimum 2).
message String Required HTML body text. Must contain [unsubscribeurl] or [unsubscribelink] tags.
list_uuids or list_ids Array Required Array of target list UUID strings or numeric IDs.
segment_uuids or segment_ids Array Optional Array of segment filters (must belong to target lists).
canspam_uuid or canspam_id String / Integer Required UUID or ID of CAN-SPAM configuration.
delivery_server_uuid or delivery_server_id String / Integer Required UUID or ID of the delivery server configuration.
tracking_domain_uuid or tracking_domain String Required UUID of tracking domain, or raw domain name string.
from_name String Required Name displayed as sender.
from_email String Required Sender email address (domain must be verified).
reply_to String Required Reply-to email address.
email_sending_speed Integer Required Emails sent per minute. Must not exceed delivery server speed limit.
timezone String Required Valid timezone string (e.g. America/New_York).
sending_days Array of Strings Required Days on which delivery is allowed (e.g. ["monday", "tuesday"]).
start_sending_from String Required Time of day to start sending (format: HH:MM, e.g. 09:00).
end_sending_at String Optional Time of day to stop sending (format: HH:MM).
send_at String Required for regular/ab_testing Datetime when delivery starts (format: YYYY-MM-DD HH:MM:SS).
status String Optional draft or pending (Default: pending).
ar_event String Required for autoresponder/retargeting Trigger event (e.g. subscribe).
ar_time_unit String Required for autoresponder/retargeting Delay time unit: minutes, hours, days, weeks.
ar_time_value Integer Required for autoresponder/retargeting Delay value.
ar_campaign_uuid or ar_campaign_id String / Integer Required for retargeting Parent campaign identifier.
triggers Array of Objects Optional Campaign webhook or list transfer actions.

Example Payload

{
    "campaign_type": "regular",
    "campaign_name": "Monthly Newsletter",
    "subject": "Here is what's new in August",
    "message": "<p>Hello subscriber! ... [unsubscribeurl]</p>",
    "list_uuids": ["4e73b75f-2c2d-9e1f-88b7-7a66c5d4b8f3"],
    "canspam_uuid": "9a7b6f4a-3b4c-2d9e-1f88-b77a66c5d4b8",
    "delivery_server_uuid": "88b77a66-c5d4-b8f3-4e73-b75f2c2d9e1f",
    "tracking_domain_uuid": "2c2d9e1f-88b7-7a66-c5d4-b8f34e73b75f",
    "from_name": "Newsletter Admin",
    "from_email": "newsletter@acme.com",
    "reply_to": "support@acme.com",
    "email_sending_speed": 100,
    "timezone": "America/New_York",
    "sending_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "start_sending_from": "09:00",
    "send_at": "2026-08-25 09:00:00"
}

Response Example

{
    "success": true,
    "message": "Campaign created successfully.",
    "data": {
        "id": 12,
        "uuid": "5d3b75fa-9e1f-88b7-7a66-c5d4b8f34e73",
        "campaign_type": "regular",
        "campaign_name": "Monthly Newsletter",
        "subject": "Here is what's new in August",
        "status": "pending",
        "created_at": "2026-08-23T10:18:00.000000Z"
    }
}
PUT /campaigns/{uuid}

Updates an existing campaign. Enforces identical validation and resource ownership rules as campaign creation.

URL Parameters

Parameter Type Status Description
uuid String Required UUID or ID of the campaign to edit.

Response Example

{
    "success": true,
    "message": "Campaign updated successfully.",
    "data": {
        "id": 12,
        "uuid": "5d3b75fa-9e1f-88b7-7a66-c5d4b8f34e73",
        "campaign_type": "regular",
        "campaign_name": "Updated Campaign Name",
        "status": "draft"
    }
}
DELETE /campaigns/{uuid}

Permanently deletes a campaign and cleans up associated database records (triggers, options, A/B subjects).

Response Example

{
    "success": true,
    "message": "Campaign deleted successfully.",
    "data": null
}
GET /campaigns

Retrieves a paginated list of all campaigns. Supports filtering by campaign type and status.

Query Parameters

Parameter Type Status Description
campaign_type String Optional Filter by type: regular, autoresponder, ab_testing, or retargeting.
status String Optional Filter by send status: draft, sending, sent, paused, pending.
per_page Integer Optional Number of records per page (Default: 15).
GET /campaigns/{uuid}

Retrieves detailed configuration and metrics context for a specific campaign by its UUID or ID.