Campaigns API

List and retrieve campaign information.

List Campaigns

Get a list of all campaigns in your organization.

Endpoint


GET /api/campaigns

Example Request


curl -X GET NEXT_PUBLIC_BASE_URL/api/campaigns \
  -H "x-api-key: your-api-key"

Response Schema

Field	Type	Description
`campaigns`	`array`	List of campaigns
`campaigns[].id`	`string`	Campaign unique identifier
`campaigns[].name`	`string`	Campaign name
`campaigns[].createdAt`	`string`	ISO 8601 timestamp of creation

Example Response


{
  "campaigns": [
    {
      "id": "clxyz123",
      "name": "Welcome Series",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "clxyz456",
      "name": "Newsletter January",
      "createdAt": "2024-01-10T08:00:00.000Z"
    }
  ]
}

Get Campaign Details

Get detailed information about a specific campaign including all emails.

Endpoint


GET /api/campaigns/:id

Path Parameters

Parameter	Type	Description
`id`	`string`	Campaign ID

Example Request


curl -X GET NEXT_PUBLIC_BASE_URL/api/campaigns/clxyz123 \
  -H "x-api-key: your-api-key"

Response Schema

Field	Type	Description
`id`	`string`	Campaign ID
`name`	`string`	Campaign name
`createdAt`	`string`	ISO 8601 timestamp
`stats`	`object`	Campaign statistics
`stats.totalEmails`	`number`	Total emails in campaign
`stats.totalOpens`	`number`	Total opens across all emails
`stats.totalClicks`	`number`	Total clicks across all emails
`stats.openRate`	`number`	Open rate percentage
`stats.clickRate`	`number`	Click rate percentage
`links`	`array`	Aggregated link statistics
`links[].url`	`string`	Original link URL
`links[].clicks`	`number`	Total clicks on this link
`emails`	`array`	List of emails in the campaign

Example Response


{
  "id": "clxyz123",
  "name": "Welcome Series",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "stats": {
    "totalEmails": 1250,
    "totalOpens": 856,
    "totalClicks": 302,
    "openRate": 68.48,
    "clickRate": 24.16
  },
  "links": [
    {
      "url": "https://example.com/signup",
      "clicks": 156
    },
    {
      "url": "https://example.com/learn-more",
      "clicks": 89
    }
  ],
  "emails": [
    {
      "id": "email123",
      "trackingId": "hE4kJ9",
      "recipient": "[email protected]",
      "subject": "Welcome to our service!",
      "createdAt": "2024-01-15T10:32:00.000Z",
      "opens": 2,
      "clicks": 1
    }
  ]
}

Create Campaign

Create a new campaign in your organization.

Endpoint


POST /api/campaigns

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Campaign name (must be unique within the organization)

Example Request


curl -X POST NEXT_PUBLIC_BASE_URL/api/campaigns \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Welcome Series"}'

Response Schema

Field	Type	Description
`id`	`string`	Campaign unique identifier
`name`	`string`	Campaign name
`createdAt`	`string`	ISO 8601 timestamp of creation

Example Response


{
  "id": "clxyz123",
  "name": "Welcome Series",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Archive Campaign

Archive a campaign. Archived campaigns are excluded from campaign lists and no longer accept new emails.

Endpoint


POST /api/campaigns/:id/archive

Path Parameters

Parameter	Type	Description
`id`	`string`	Campaign ID

Example Request


curl -X POST NEXT_PUBLIC_BASE_URL/api/campaigns/clxyz123/archive \
  -H "x-api-key: your-api-key"

Example Response


{
  "success": true
}

Error Responses

Status	Description
`400 Bad Request`	Missing required fields or campaign already archived
`401 Unauthorized`	Invalid or missing API key
`403 Forbidden`	Campaign limit reached on current plan
`404 Not Found`	Campaign not found or doesn’t belong to your organization
`409 Conflict`	A campaign with this name already exists

Example Error


{
  "error": "Campaign not found"
}