Routes

📖 Campaign Documentation

Page	Description
Overview	Module overview, workflows, and high-level architecture
Models & Constants	Database models, enums, and default templates
Routes	API endpoints, request/response formats, and examples
Service	Business logic functions and integration points
Schemas	Validation schemas and data structures

This document lists all HTTP endpoints exposed by app/api/campaign/routes.py and explains their purpose, inputs and outputs.
All routes are mounted under the prefix /api/v1/campaign in the main FastAPI application.

Public Utility Routes

Method	Path	Purpose
`GET`	`/content-types`	Return the list of supported `content_type` variants plus their JSON-schema and variable rules.
`GET`	`/default-campaign-names`	Convenience list of all built-in default campaign names.
`GET`	`/create-default`	Creates/updates the default templates for the authenticated merchant. Optional `campaign_names` query-param allows selective creation.
`GET`	`/media/{merchant_id}/{campaign_id}/{file_path}`	Serves media assets (images, pdf, video…) previously uploaded for `twilio/media` or `twilio/card` templates, after verifying the merchant owns the campaign.
`GET`	`/redirect/{token}`	Helper used inside templates to build safe links. `token` is the numeric `CampaignLeadMessage.id`; server resolves it → context[`link`] or fallback URLs, then issues HTTP 302 redirect.

CRUD Routes

Method	Path	Description
`GET`	`/`	List campaigns for the merchant with pagination, search & filtering. Supports `search`, `order_by`, `campaign_ids`, and `campaign_type` filtering. Returns `CampaignSchema` objects.
`POST`	`/create`	Create a new template version. Accepts `multipart/form-data` with `name`, `content_type`, `content_context_json` and optional media `file`. Validates, uploads media, calls `create_message_template()`.
`POST`	`/update/{campaign_id}`	Create a new version of an existing campaign. Preserves history by linking `next_campaign_id`. Uses `update_message_template()`.
`POST`	`/add-leads`	Bulk add or re-activate `CampaignLead` records. Accepts JSON body (`campaign_id`, list of `{phone_number, custom_variables …}`).
`POST`	`/remove-lead`	Soft-deactivate a single lead (`active = False`).
`POST`	`/send`	Send the campaign to all active leads or the provided comma-separated `phone_numbers`. Optional `enable` parameter to enable campaign before sending. Delegates to `send_campaign_messages()`.
`GET`	`/preview`	Hydrates variables for a single `CampaignLead` without actually sending, useful for UI preview.

Campaign State Management Routes

Method	Path	Description
`POST`	`/enable`	Enable a campaign by setting `enabled` timestamp to current time. Enables the campaign for message sending and service automation.
`POST`	`/pause`	Disable a campaign by setting `enabled` field to `NULL`. Pauses scheduled sends and service automation.

Enable/Disable Workflow

Campaigns have an enabled field that controls whether they can send messages:

enabled = NULL: Campaign is disabled/paused
enabled = <timestamp>: Campaign is enabled and can send messages

Marketing Campaigns: Must be manually enabled via /enable or the enable=true parameter in /send

Service Campaigns: - Must be enabled to trigger automatic service messages (order confirmations, etc.) - The /enable endpoint allows merchants to activate/deactivate service automation - When disabled, service campaigns won't send automatic messages even when triggered by events

Query Parameters

GET `/` - List Campaigns

Parameter	Type	Required	Description
`n`	`int`	No	Number of campaigns to retrieve (default: 10, max: determined by backend)
`start`	`int`	No	Starting index for pagination (default: 0)
`order_by`	`str`	No	Sort order. Currently only supports `"created_at"` (default)
`search`	`str`	No	Search query for campaign names and content. Searches name, body, and content_context fields
`campaign_ids`	`str`	No	Comma-separated list of specific campaign IDs to retrieve
`campaign_type`	`str`	No	Filter by campaign type: `"marketing"` or `"service"`. Returns only campaigns of the specified type

Campaign Type Filtering Examples

# Get only marketing campaigns
GET /api/v1/campaign/?campaign_type=marketing

# Get only service campaigns  
GET /api/v1/campaign/?campaign_type=service

# Combine with search
GET /api/v1/campaign/?campaign_type=marketing&search=promotion

# Combine with pagination
GET /api/v1/campaign/?campaign_type=service&n=20&start=0

POST `/send` - Send Campaign

Parameter	Type	Required	Description
`campaign_id`	`int`	Yes	ID of the campaign to send
`phone_numbers`	`str`	No	Comma-separated list of phone numbers to send to (creates leads if needed)
`enable`	`bool`	No	If `true`, enables the campaign before sending (sets `enabled` timestamp)

Authentication & Permissions

All CRUD routes require a valid Merchant access token (verify_access_token).
The token embeds merchant_id, which is used to ensure that merchants can only interact with campaigns they own.

Error Handling Strategy

Validation errors are returned as 400 Bad Request with descriptive messages.
Permission / ownership issues → 403/401.
Missing resources → 404 Not Found.
Invalid campaign_type parameter → 400 Bad Request with message "Invalid campaign_type. Must be 'marketing' or 'service'"
Unexpected failures (DB, Twilio, Supabase, etc.) → 500 Internal Server Error with logged stack trace.

Examples

Creating a Text Campaign

curl -X POST https://api.meetcosmo.ai/api/v1/campaign/create \
     -H "Authorization: Bearer <TOKEN>" \
     -F name="hello_world" \
     -F language="en" \
     -F campaign_type="service" \
     -F content_type="twilio/text" \
     -F content_context_json='{"body": "Hi {{lead_name}}!"}'

Filtering Campaigns by Type

# Get marketing campaigns only
curl -X GET "https://api.meetcosmo.ai/api/v1/campaign/?campaign_type=marketing" \
     -H "Authorization: Bearer <TOKEN>"

# Get service campaigns with search
curl -X GET "https://api.meetcosmo.ai/api/v1/campaign/?campaign_type=service&search=order" \
     -H "Authorization: Bearer <TOKEN>"

Enabling a Service Campaign

# Enable a service campaign for automation
curl -X POST https://api.meetcosmo.ai/api/v1/campaign/enable?campaign_id=123 \
     -H "Authorization: Bearer <TOKEN>"

Sending with Auto-Enable

# Send marketing campaign and enable it in one request
curl -X POST https://api.meetcosmo.ai/api/v1/campaign/send?campaign_id=123 \
     -H "Authorization: Bearer <TOKEN>" \
     -F enable=true

Successful response:

{
  "campaign": {
    "id": 123,
    "status": "approved",
    "enabled": "2024-01-15T10:30:00Z",
    "campaign_type": "marketing",
    "variables": {"1": "lead_name"},
    "content_sid": "CT1234567890abcdef",
    ...
  }
}

See Service for the server-side flow triggered by these requests.