Marketing Campaigns API

Overview

The Marketing Campaigns API provides comprehensive management of marketing campaigns within Stack9 Experience. This API enables you to create, manage, and track coordinated marketing efforts across multiple channels, with built-in support for email marketing, engagement tracking, UTM parameter management, and campaign analytics.

Resource Description

Marketing campaigns in Stack9 represent coordinated series of marketing activities designed to promote products, services, or brands through one or more channels. Each campaign consists of:

Campaign Configuration: Core campaign metadata including name, timeline, goals, and audience targeting
Campaign Emails: Associated marketing emails sent as part of the campaign
Engagement Tracking: Comprehensive tracking of subscriber interactions with campaign content
Analytics & Metrics: Performance measurement including open rates, click rates, conversions, and engagement scores
UTM Integration: Built-in UTM parameter tracking for cross-channel attribution

Key Features

Campaign Lifecycle Management: Plan, execute, and analyze campaigns from start to finish
Color-Coded Organization: Visual organization system for marketing calendars
Business Unit Segmentation: Support for multi-brand or department-specific campaigns
Goal Setting: Define and track campaign objectives (lead generation, sales, brand awareness)
Audience Targeting: Specify and manage target audience segments
Email Campaign Integration: Create and manage multiple emails within a campaign
Engagement Analytics: Track subscriber interactions across all campaign touchpoints
Performance Metrics: Comprehensive analytics for campaign effectiveness

Authentication

All endpoints require API key authentication:

X-API-Key: your-api-key-here

Campaign Management

Create Campaign

Create a new marketing campaign with defined goals, timeline, and target audience.

POST /api/campaigns

Parameters

Parameter	Type	Required	Description
`code`	string	Yes	Unique campaign code (uppercase, alphanumeric with hyphens/underscores). Used for UTM tracking
`name`	string	Yes	Display name for the campaign
`colour`	string	Yes	Hex color code for visual organization in marketing calendar
`business_unit`	string	No	Business unit or department owning the campaign
`start_date`	string	Yes	Campaign start date (ISO 8601 format)
`end_date`	string	No	Campaign end date (ISO 8601 format)
`goal`	string	No	Campaign objectives (e.g., lead generation, sales, brand awareness)
`audience`	string	Yes	Target audience description and segmentation criteria

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/campaigns \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "SUMMER-SALE-2024",
    "name": "Summer Sale Campaign 2024",
    "colour": "#FF5733",
    "business_unit": "E-commerce",
    "start_date": "2024-06-01T00:00:00Z",
    "end_date": "2024-08-31T23:59:59Z",
    "goal": "Drive 30% increase in summer product sales through targeted email marketing and promotional offers",
    "audience": "Active customers aged 25-45 interested in outdoor and summer activities"
  }'

Example Response

{
  "code": "SUMMER-SALE-2024",
  "id": "camp_abc123def456",
  "created_at": "2024-03-20T10:30:00Z"
}

Error Responses

400 Bad Request

{
  "message": "Invalid campaign configuration",
  "code": "INVALID_CAMPAIGN",
  "issues": [
    {
      "message": "Campaign code must be uppercase alphanumeric with hyphens or underscores only"
    }
  ]
}

409 Conflict

{
  "message": "Campaign with this code already exists",
  "code": "DUPLICATE_CAMPAIGN_CODE"
}

List Campaigns

Retrieve a paginated list of marketing campaigns with optional filtering and search capabilities.

POST /api/campaigns/list

Parameters

Parameter	Type	Required	Description
`page`	integer	Yes	Page number (1-based)
`limit`	integer	Yes	Items per page (max: 100)
`search`	string	No	Search text to filter campaigns
`filters`	object	No	Advanced filtering options
`filters.name`	object	No	Filter by campaign name
`filters.business_unit`	object	No	Filter by business unit
`filters.start_date`	object	No	Filter by start date range
`filters.end_date`	object	No	Filter by end date range
`filters.audience`	object	No	Filter by audience criteria

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/campaigns/list \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "page": 1,
    "limit": 20,
    "search": "summer",
    "filters": {
      "business_unit": {
        "equals": "E-commerce"
      },
      "start_date": {
        "gte": "2024-06-01T00:00:00Z"
      }
    }
  }'

Example Response

{
  "results": [
    {
      "code": "SUMMER-SALE-2024",
      "name": "Summer Sale Campaign 2024",
      "colour": "#FF5733",
      "business_unit": "E-commerce",
      "start_date": "2024-06-01T00:00:00Z",
      "end_date": "2024-08-31T23:59:59Z",
      "goal": "Drive 30% increase in summer product sales",
      "audience": "Active customers aged 25-45",
      "audience_name": "Summer Shoppers Segment",
      "created_at": "2024-03-20T10:30:00Z",
      "updated_at": "2024-03-25T14:15:00Z"
    },
    {
      "code": "BACK-TO-SCHOOL-2024",
      "name": "Back to School Campaign 2024",
      "colour": "#4CAF50",
      "business_unit": "E-commerce",
      "start_date": "2024-07-15T00:00:00Z",
      "end_date": "2024-09-15T23:59:59Z",
      "goal": "Target parents and students with school supplies promotions",
      "audience": "Parents with school-age children",
      "created_at": "2024-03-18T09:00:00Z"
    }
  ],
  "metadata": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "total_pages": 3
  }
}

Get Campaign by Code

Retrieve detailed information about a specific marketing campaign.

GET /api/campaigns/{code}

Parameters

Parameter	Type	Required	Description
`code`	string	Yes	Campaign code (path parameter)

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024 \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "code": "SUMMER-SALE-2024",
  "name": "Summer Sale Campaign 2024",
  "colour": "#FF5733",
  "business_unit": "E-commerce",
  "start_date": "2024-06-01T00:00:00Z",
  "end_date": "2024-08-31T23:59:59Z",
  "goal": "Drive 30% increase in summer product sales through targeted email marketing and promotional offers",
  "audience": "Active customers aged 25-45 interested in outdoor and summer activities",
  "created_at": "2024-03-20T10:30:00Z",
  "updated_at": "2024-03-25T14:15:00Z",
  "metrics": {
    "total_emails_sent": 5,
    "total_subscribers_reached": 15000,
    "average_open_rate": 0.245,
    "average_click_rate": 0.087,
    "total_conversions": 450,
    "revenue_generated": 67500.00
  }
}

Error Responses

404 Not Found

{
  "message": "Campaign not found",
  "code": "CAMPAIGN_NOT_FOUND"
}

Update Campaign

Update an existing marketing campaign's configuration.

PUT /api/campaigns/{code}

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Display name for the campaign
`colour`	string	Yes	Hex color code for visual organization
`business_unit`	string	No	Business unit or department
`start_date`	string	Yes	Campaign start date (ISO 8601)
`end_date`	string	No	Campaign end date (ISO 8601)
`goal`	string	No	Campaign objectives
`audience`	string	Yes	Target audience description

Example Request

curl -X PUT \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024 \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Extended Summer Sale Campaign 2024",
    "colour": "#FF5733",
    "business_unit": "E-commerce",
    "start_date": "2024-06-01T00:00:00Z",
    "end_date": "2024-09-15T23:59:59Z",
    "goal": "Drive 35% increase in summer product sales with extended timeline",
    "audience": "Active customers aged 25-45 interested in outdoor and summer activities"
  }'

Example Response

{
  "code": "SUMMER-SALE-2024",
  "updated_at": "2024-04-01T10:00:00Z"
}

Delete Campaign

Permanently delete a marketing campaign and its associated data.

DELETE /api/campaigns/{code}

Parameters

Parameter	Type	Required	Description
`code`	string	Yes	Campaign code (path parameter)

Example Request

curl -X DELETE \
  https://apis.app.stack9.co/api/campaigns/OLD-CAMPAIGN-2023 \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "code": "OLD-CAMPAIGN-2023",
  "deleted": true
}

Error Responses

400 Bad Request

{
  "message": "Cannot delete campaign with active emails",
  "code": "CAMPAIGN_HAS_ACTIVE_EMAILS"
}

Campaign Emails

Create Campaign Email

Create a new marketing email within a campaign.

POST /api/campaigns/{campaign_code}/emails

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Display name for the email
`description`	string	No	Email description and purpose
`subject`	string	Yes	Email subject line
`target_subscribers_count`	number	No	Number of targeted subscribers
`status`	string	No	Email status (Draft, Ready, Scheduled, Sending, Sent, Cancelled)
`sent_date`	string	No	Scheduled or actual send date (ISO 8601)

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/emails \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Summer Sale Launch Email",
    "description": "Initial announcement of summer sale with early bird offers",
    "subject": "🌞 Summer Sale Starts Now - Up to 50% Off!",
    "target_subscribers_count": 15000,
    "status": "Draft"
  }'

Example Response

{
  "id": "email_xyz789ghi012",
  "campaign_code": "SUMMER-SALE-2024",
  "created_at": "2024-05-15T10:00:00Z"
}

List Campaign Emails

Retrieve all marketing emails associated with a campaign.

GET /api/campaigns/{campaign_code}/emails

Parameters

Parameter	Type	Required	Description
`campaign_code`	string	Yes	Campaign code (path parameter)

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/emails \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "results": [
    {
      "id": "email_xyz789ghi012",
      "name": "Summer Sale Launch Email",
      "description": "Initial announcement of summer sale",
      "subject": "🌞 Summer Sale Starts Now - Up to 50% Off!",
      "target_subscribers_count": 15000,
      "status": "Sent",
      "sent_date": "2024-06-01T09:00:00Z",
      "metrics": {
        "delivered": 14850,
        "opened": 3640,
        "clicked": 1305,
        "unsubscribed": 45,
        "bounced": 150
      }
    },
    {
      "id": "email_abc456def789",
      "name": "Summer Sale Reminder",
      "description": "Mid-campaign reminder with featured products",
      "subject": "Don't Miss Out - Summer Sale Ends Soon!",
      "target_subscribers_count": 14500,
      "status": "Scheduled",
      "sent_date": "2024-07-15T09:00:00Z"
    }
  ],
  "total": 5
}

Get Campaign Email

Retrieve detailed information about a specific campaign email.

GET /api/campaigns/{campaign_code}/emails/{id}

Parameters

Parameter	Type	Required	Description
`campaign_code`	string	Yes	Campaign code (path parameter)
`id`	string	Yes	Email ID (path parameter)

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/emails/email_xyz789ghi012 \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "id": "email_xyz789ghi012",
  "campaign_code": "SUMMER-SALE-2024",
  "name": "Summer Sale Launch Email",
  "description": "Initial announcement of summer sale with early bird offers",
  "subject": "🌞 Summer Sale Starts Now - Up to 50% Off!",
  "status": "Sent",
  "sent_date": "2024-06-01T09:00:00Z",
  "target_subscribers_count": 15000,
  "content": {
    "html": "<html>...</html>",
    "text": "Summer sale content...",
    "template_id": "tmpl_summer_sale_2024"
  },
  "metrics": {
    "delivered": 14850,
    "opened": 3640,
    "clicked": 1305,
    "unsubscribed": 45,
    "bounced": 150,
    "open_rate": 0.245,
    "click_rate": 0.088,
    "unsubscribe_rate": 0.003
  },
  "created_at": "2024-05-15T10:00:00Z",
  "updated_at": "2024-06-01T08:55:00Z"
}

Process Campaign Email

Send or schedule a campaign email for delivery.

GET /api/campaigns/{campaign_code}/emails/{id}/process

Parameters

Parameter	Type	Required	Description
`campaign_code`	string	Yes	Campaign code (path parameter)
`id`	string	Yes	Email ID (path parameter)

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/emails/email_abc456def789/process \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "id": "email_abc456def789",
  "status": "Sending",
  "job_id": "job_send_123456",
  "estimated_completion": "2024-06-01T09:30:00Z"
}

Clone Campaign Email

Create a duplicate of an existing campaign email.

POST /api/campaigns/{campaign_code}/emails/{marketing_email_id}/clone

Parameters

Parameter	Type	Required	Description
`target_campaign_code`	string	Yes	Destination campaign code for the cloned email

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/emails/email_xyz789ghi012/clone \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "target_campaign_code": "FALL-SALE-2024"
  }'

Example Response

{
  "id": "email_new123abc456",
  "campaign_code": "FALL-SALE-2024",
  "name": "Summer Sale Launch Email (Copy)",
  "status": "Draft",
  "created_at": "2024-07-01T10:00:00Z"
}

Convert Email to Draft

Revert a scheduled or ready email back to draft status.

GET /api/campaigns/{campaign_code}/emails/{id}/convert-to-draft

Parameters

Parameter	Type	Required	Description
`campaign_code`	string	Yes	Campaign code (path parameter)
`id`	string	Yes	Email ID (path parameter)

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/emails/email_abc456def789/convert-to-draft \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "id": "email_abc456def789",
  "status": "Draft",
  "previous_status": "Scheduled",
  "updated_at": "2024-06-15T11:00:00Z"
}

Campaign Analytics

Get Campaign Email Metrics

Retrieve detailed metrics for a specific campaign email.

POST /api/campaigns/{campaign_code}/emails/{marketing_email_id}/metrics

Parameters

Parameter	Type	Required	Description
`query`	object	Yes	Metrics query configuration
`query.name`	string	Yes	Query type (getMarketingEmailOpenRate, getMarketingEmailClickRate, etc.)

Available Query Types

getMarketingEmailOpenRate: Calculate email open rate
getMarketingEmailClickRate: Calculate click-through rate
getMarketingEmailUnsubscribeRate: Calculate unsubscribe rate
getMarketingEmailBounceRate: Calculate bounce rate
getMarketingEmailConversionRate: Calculate conversion rate

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/emails/email_xyz789ghi012/metrics \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "name": "getMarketingEmailOpenRate"
    }
  }'

Example Response

{
  "queryName": "getMarketingEmailOpenRate",
  "result": {
    "open_rate": 0.245,
    "unique_opens": 3640,
    "total_opens": 5832,
    "delivered": 14850,
    "calculation_time": "2024-06-02T10:00:00Z"
  }
}

Bulk Get Email Metrics

Retrieve metrics for multiple campaign emails simultaneously.

POST /api/campaigns/{campaign_code}/emails/metrics

Parameters

Parameter	Type	Required	Description
`marketing_email_ids`	array	Yes	List of email IDs to retrieve metrics for

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/emails/metrics \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "marketing_email_ids": [
      "email_xyz789ghi012",
      "email_abc456def789",
      "email_qrs123tuv456"
    ]
  }'

Example Response

{
  "metricsByEmailId": {
    "email_xyz789ghi012": {
      "delivered": 14850,
      "opened": 3640,
      "clicked": 1305,
      "unsubscribed": 45,
      "bounced": 150,
      "open_rate": 0.245,
      "click_rate": 0.088,
      "unsubscribe_rate": 0.003,
      "bounce_rate": 0.010
    },
    "email_abc456def789": {
      "delivered": 14500,
      "opened": 3190,
      "clicked": 1015,
      "unsubscribed": 38,
      "bounced": 125,
      "open_rate": 0.220,
      "click_rate": 0.070,
      "unsubscribe_rate": 0.003,
      "bounce_rate": 0.009
    },
    "email_qrs123tuv456": {
      "delivered": 14200,
      "opened": 2840,
      "clicked": 852,
      "unsubscribed": 42,
      "bounced": 110,
      "open_rate": 0.200,
      "click_rate": 0.060,
      "unsubscribe_rate": 0.003,
      "bounce_rate": 0.008
    }
  }
}

Get Clicked Links Data

Retrieve analytics data for links clicked within a campaign email.

GET /api/campaigns/{campaign_code}/emails/{marketing_email_id}/clicked-links-data

Parameters

Parameter	Type	Required	Description
`campaign_code`	string	Yes	Campaign code (path parameter)
`marketing_email_id`	string	Yes	Email ID (path parameter)

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/emails/email_xyz789ghi012/clicked-links-data \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "links": [
    {
      "url": "https://example.com/summer-sale?utm_source=email&utm_medium=campaign&utm_campaign=SUMMER-SALE-2024",
      "clicks": 450,
      "unique_clicks": 380,
      "first_click": "2024-06-01T09:15:00Z",
      "last_click": "2024-06-10T22:30:00Z",
      "click_rate": 0.026
    },
    {
      "url": "https://example.com/products/category/outdoor?utm_campaign=SUMMER-SALE-2024",
      "clicks": 320,
      "unique_clicks": 280,
      "first_click": "2024-06-01T09:20:00Z",
      "last_click": "2024-06-08T18:45:00Z",
      "click_rate": 0.019
    }
  ],
  "total_clicks": 1305,
  "total_unique_clicks": 1015
}

Campaign Engagements

Get Campaign Engagements

Retrieve detailed engagement data for campaign interactions.

POST /api/campaigns/{campaignCode}/engagements

Parameters

Parameter	Type	Required	Description
`page`	number	Yes	Page number (1-based)
`limit`	number	Yes	Items per page (max: 100)
`filters`	object	No	Engagement filters
`filters.subscriberId`	string	No	Filter by subscriber ID
`filters.marketingEmailId`	string	No	Filter by email ID
`filters.hasClickedLinks`	boolean	No	Filter for subscribers who clicked links

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/campaigns/SUMMER-SALE-2024/engagements \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "page": 1,
    "limit": 50,
    "filters": {
      "hasClickedLinks": true,
      "marketingEmailId": "email_xyz789ghi012"
    }
  }'

Example Response

{
  "results": [
    {
      "subscriber_id": "sub_123456",
      "campaign_code": "SUMMER-SALE-2024",
      "marketing_email_id": "email_xyz789ghi012",
      "delivery_status": "delivered",
      "email_sent_at": "2024-06-01T09:00:00Z",
      "email_delivered_at": "2024-06-01T09:00:15Z",
      "email_opened_at": "2024-06-01T10:30:00Z",
      "email_clicked_at": "2024-06-01T10:31:00Z",
      "email_unsubscribed_at": null,
      "first_page_view_at": "2024-06-01T10:31:05Z",
      "last_page_view_at": "2024-06-01T10:45:00Z",
      "page_view_count": 8,
      "total_engagement_time_seconds": 840,
      "first_purchase_at": "2024-06-01T10:42:00Z",
      "last_purchase_at": "2024-06-01T10:42:00Z",
      "purchase_count": 1,
      "total_purchase_amount": 149.99,
      "engagement_score": 85.5,
      "updated_at": "2024-06-01T23:59:59Z",
      "campaign_metadata": {
        "send_date": "2024-06-01T09:00:00Z",
        "subscription_type": "promotional",
        "subject_line": "🌞 Summer Sale Starts Now - Up to 50% Off!"
      }
    }
  ],
  "metadata": {
    "page": 1,
    "limit": 50,
    "total": 1015,
    "total_pages": 21
  }
}

Engagement Fields

Field	Type	Description
`subscriber_id`	string	Unique subscriber identifier
`campaign_code`	string	Campaign code
`marketing_email_id`	string	Associated email ID
`delivery_status`	string	Email delivery status
`email_sent_at`	string	Email send timestamp
`email_delivered_at`	string	Email delivery timestamp
`email_opened_at`	string	First email open timestamp
`email_clicked_at`	string	First link click timestamp
`email_unsubscribed_at`	string	Unsubscribe timestamp (if applicable)
`first_page_view_at`	string	First website visit from campaign
`last_page_view_at`	string	Most recent website visit
`page_view_count`	integer	Total page views from campaign
`total_engagement_time_seconds`	integer	Total time spent on site
`first_purchase_at`	string	First purchase timestamp
`last_purchase_at`	string	Most recent purchase timestamp
`purchase_count`	integer	Total purchases attributed to campaign
`total_purchase_amount`	number	Total revenue from campaign
`engagement_score`	number	Calculated engagement score (0-100)

UTM Tracking Integration

Stack9 Marketing Campaigns automatically integrate with UTM parameters for comprehensive cross-channel tracking. When creating campaigns, the campaign code is automatically used as the utm_campaign parameter.

UTM Parameter Structure

All campaign emails automatically include UTM parameters in links:

utm_source: Automatically set to "email"
utm_medium: Automatically set to "campaign"
utm_campaign: Uses the campaign code
utm_content: Can be customized per email or link
utm_term: Can be added for keyword tracking

Example UTM-Tagged URL

https://example.com/products?utm_source=email&utm_medium=campaign&utm_campaign=SUMMER-SALE-2024&utm_content=hero-banner

Tracking Attribution

Campaign engagements automatically track:

Direct conversions from email clicks
Multi-touch attribution across channels
Time-decay attribution models
First-click and last-click attribution

Best Practices

Campaign Planning

Use Meaningful Campaign Codes: Create descriptive, consistent campaign codes that follow a naming convention (e.g., SEASON-TYPE-YEAR)
Set Clear Goals: Define measurable objectives for each campaign
Plan Timeline: Set appropriate start and end dates that align with business objectives
Color Coding: Use consistent color schemes for campaign types (e.g., red for sales, blue for informational)

Audience Targeting

Define Target Segments: Clearly specify audience demographics and behaviors
Use Existing Audiences: Leverage pre-built audience segments from the Audiences API
Test Segments: A/B test different audience segments for optimization
Monitor Engagement: Track engagement scores to refine targeting

Email Campaign Management

Create Email Series: Design multi-touch email sequences within campaigns
Optimize Send Times: Schedule emails based on audience behavior patterns
Test Subject Lines: A/B test different subject lines for better open rates
Monitor Metrics: Track key metrics throughout the campaign lifecycle

Performance Optimization

Real-Time Monitoring: Track campaign performance as it happens
Engagement Scoring: Use engagement scores to identify high-value subscribers
Link Tracking: Monitor which links drive the most engagement
Attribution Analysis: Understand the full customer journey

Data Management

Regular Cleanup: Archive old campaigns to maintain performance
Consistent Naming: Use standardized naming conventions
Document Goals: Keep campaign goals and results documented
Export Analytics: Regularly export campaign data for analysis

Campaign Lifecycle

1. Planning Phase

Define campaign goals and KPIs
Identify target audience segments
Set campaign timeline
Assign to business unit

2. Creation Phase

Create campaign with unique code
Configure visual settings (color)
Set up campaign metadata

3. Content Development

Create email templates
Design email series
Configure UTM tracking
Set up A/B tests

4. Testing Phase

Preview emails
Test rendering across clients
Verify tracking parameters
Validate audience segments

5. Execution Phase

Schedule or send emails
Monitor delivery status
Track real-time engagement
Respond to issues

6. Analysis Phase

Review campaign metrics
Analyze engagement patterns
Calculate ROI
Document learnings

7. Optimization Phase

Apply learnings to future campaigns
Refine audience segments
Update email templates
Improve conversion paths

Error Handling

The Marketing Campaigns API returns standard HTTP status codes and detailed error responses.

Common Error Responses

400 Bad Request

{
  "message": "Invalid request parameters",
  "code": "INVALID_REQUEST",
  "issues": [
    {
      "message": "Campaign code must match pattern ^[A-Z0-9_-]+$"
    }
  ]
}

401 Unauthorized

{
  "message": "Invalid API key",
  "code": "UNAUTHORIZED"
}

404 Not Found

{
  "message": "Campaign not found",
  "code": "CAMPAIGN_NOT_FOUND"
}

409 Conflict

{
  "message": "Campaign code already exists",
  "code": "DUPLICATE_CAMPAIGN"
}

429 Too Many Requests

{
  "message": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

500 Internal Server Error

{
  "message": "An unexpected error occurred",
  "code": "INTERNAL_ERROR"
}

Rate Limits

Marketing Campaigns API endpoints have the following rate limits:

Endpoint Type	Limit	Window
GET endpoints	100 requests	1 minute
POST endpoints	50 requests	1 minute
PUT endpoints	30 requests	1 minute
DELETE endpoints	10 requests	1 minute
Metrics endpoints	20 requests	1 minute

Webhook Events

Configure webhooks to receive real-time notifications for campaign events:

Available Events

Event	Description
`campaign.created`	New campaign created
`campaign.updated`	Campaign configuration updated
`campaign.deleted`	Campaign deleted
`campaign.email.sent`	Campaign email sent
`campaign.email.delivered`	Email successfully delivered
`campaign.email.opened`	Email opened by recipient
`campaign.email.clicked`	Link clicked in email
`campaign.goal.achieved`	Campaign goal reached

Webhook Payload Example

{
  "event": "campaign.email.clicked",
  "timestamp": "2024-06-01T10:31:00Z",
  "campaign_code": "SUMMER-SALE-2024",
  "email_id": "email_xyz789ghi012",
  "subscriber_id": "sub_123456",
  "data": {
    "url": "https://example.com/summer-sale",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "engagement_score": 75.5
  }
}

Advanced Features

Campaign Templates

Create reusable campaign templates for common marketing initiatives:

{
  "template_name": "Seasonal Sale Template",
  "default_settings": {
    "colour": "#FF5733",
    "business_unit": "E-commerce",
    "goal": "Drive seasonal product sales",
    "email_series": [
      {
        "name": "Launch Email",
        "send_offset_days": 0
      },
      {
        "name": "Reminder Email",
        "send_offset_days": 7
      },
      {
        "name": "Last Chance Email",
        "send_offset_days": -2
      }
    ]
  }
}

Multi-Channel Integration

Campaigns can integrate with multiple marketing channels:

Email: Primary channel with full tracking
SMS: Text message campaigns (via integration)
Social Media: Coordinated social posts
Web Push: Browser notifications
In-App Messages: Mobile app notifications

Advanced Analytics

Access detailed analytics through specialized queries:

Cohort Analysis: Track subscriber behavior over time
Attribution Modeling: Multi-touch attribution analysis
Predictive Scoring: ML-based engagement predictions
Revenue Attribution: Direct revenue tracking
Customer Lifetime Value: CLV calculations by campaign

A/B Testing

Built-in A/B testing capabilities for campaigns:

{
  "test_groups": [
    {
      "name": "Control",
      "percentage": 50,
      "subject_line": "Summer Sale - Save Big!"
    },
    {
      "name": "Variant A",
      "percentage": 50,
      "subject_line": "🌞 Hot Summer Deals Inside!"
    }
  ],
  "success_metric": "click_rate",
  "minimum_sample_size": 1000
}

Migration Guide

If migrating from another marketing platform:

Export Campaign Data: Extract historical campaign data
Map Campaign Codes: Create mapping between old and new campaign identifiers
Import Audiences: Migrate audience segments first
Create Campaigns: Set up campaigns with proper timelines
Import Email Templates: Migrate email content and templates
Configure Tracking: Set up UTM parameters and tracking
Test Integration: Validate data flow and tracking
Run Parallel: Consider running parallel campaigns initially
Analyze Results: Compare performance metrics
Full Migration: Complete transition to Stack9 campaigns

Compliance Considerations

Ensure proper consent for marketing communications
Honor unsubscribe requests immediately
Provide data portability for campaign engagement data
Support right to erasure for campaign data

CAN-SPAM Compliance

Include valid physical address in all emails
Provide clear unsubscribe mechanism
Use accurate subject lines
Identify messages as advertisements

Data Retention

Campaign data retained according to account settings
Engagement data aggregated after retention period
Personal data removed per privacy policy
Analytics data anonymized for long-term storage

Support and Resources

For additional support with Marketing Campaigns API:

API Reference: Full OpenAPI specification available
SDKs: Available for Python, Node.js, Ruby, and PHP
Support: Contact support@stack9.io
Status Page: monitor.stack9.io for API status
Community: Join our developer community forum

Overview​

Resource Description​

Key Features​

Authentication​

Campaign Management​

Create Campaign​

Parameters​

Example Request​

Example Response​

Error Responses​

400 Bad Request​

409 Conflict​

List Campaigns​

Parameters​

Example Request​

Example Response​

Get Campaign by Code​

Parameters​

Example Request​

Example Response​

Error Responses​

404 Not Found​

Update Campaign​

Parameters​

Example Request​

Example Response​

Delete Campaign​

Parameters​

Example Request​

Example Response​

Error Responses​

400 Bad Request​

Campaign Emails​

Create Campaign Email​

Parameters​

Example Request​

Example Response​

List Campaign Emails​

Parameters​

Example Request​

Example Response​

Get Campaign Email​

Parameters​

Example Request​

Example Response​

Process Campaign Email​

Parameters​

Example Request​

Example Response​

Clone Campaign Email​

Parameters​

Example Request​

Example Response​

Convert Email to Draft​

Parameters​

Example Request​

Example Response​

Campaign Analytics​

Get Campaign Email Metrics​

Parameters​

Available Query Types​

Example Request​

Example Response​

Bulk Get Email Metrics​

Parameters​

Example Request​

Example Response​

Get Clicked Links Data​

Parameters​

Example Request​

Example Response​

Campaign Engagements​

Get Campaign Engagements​

Parameters​

Example Request​

Example Response​

Engagement Fields​

UTM Tracking Integration​

UTM Parameter Structure​

Example UTM-Tagged URL​

Overview

Resource Description

Key Features

Authentication

Campaign Management

Create Campaign

Parameters

Example Request

Example Response

Error Responses

400 Bad Request

409 Conflict

List Campaigns

Parameters

Example Request

Example Response

Get Campaign by Code

Parameters

Example Request

Example Response

Error Responses

404 Not Found

Update Campaign

Parameters

Example Request

Example Response

Delete Campaign

Parameters

Example Request

Example Response

Error Responses

400 Bad Request

Campaign Emails

Create Campaign Email

Parameters

Example Request

Example Response

List Campaign Emails

Parameters

Example Request

Example Response

Get Campaign Email

Parameters

Example Request

Example Response

Process Campaign Email

Parameters

Example Request

Example Response

Clone Campaign Email

Parameters

Example Request

Example Response

Convert Email to Draft

Parameters

Example Request

Example Response

Campaign Analytics

Get Campaign Email Metrics

Parameters

Available Query Types

Example Request

Example Response

Bulk Get Email Metrics

Parameters

Example Request

Example Response

Get Clicked Links Data

Parameters

Example Request

Example Response

Campaign Engagements

Get Campaign Engagements

Parameters

Example Request

Example Response

Engagement Fields

UTM Tracking Integration

UTM Parameter Structure

Example UTM-Tagged URL