API docs

Appearance

On this page

Campaigns ​

Campaigns are collections of emails within Workshop. They allow you to group emails that belong to a specific topic or goal so that you can track engagement trends over time.

Endpoints ​

GET /v1/campaigns
GET /v1/campaigns/:id
GET /v1/campaigns/:id/emails

List campaigns ​

GET /v1/campaigns

Returns a list of your campaigns. The default sort is by created_at in descending order (newest first).

Parameters ​

NameOptionalDefaultDescriptionOptions
Pagination parametersSee pagination for more information.
sortoptionalcreated_atThe attribute to sort results by.created_at, name, start_date, end_date, emails_count
orderoptionaldescThe order of results based on the sort attribute.desc, asc
statusoptionalnoneFilters results to only include campaigns with the given status.active, completed, upcoming, ongoing

Returns ​

A list response where data is an array of campaign summary objects.

Example response
json
{
  "object": "array",
  "has_more": true,
  "next": "/v1/campaigns?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
    "id": "e76d4cb7-e1e7-4579-ab24-7967377bfdd7",
    "object": "campaign",
    "name": "Weekly Newsletter",
    "status": "active",
    "emails_count": 6,
    "urls": {
      "details": "/v1/campaigns/e76d4cb7-e1e7-4579-ab24-7967377bfdd7",
      "emails": "/v1/campaigns/e76d4cb7-e1e7-4579-ab24-7967377bfdd7/emails",
      },
    },
    {...},
    {...},
    {...},
    {...},
  ],
}

Retrieve a campaign ​

GET /v1/campaigns/:id

Gets the details of a single campaign.

Parameters ​

No parameters

Returns ​

A campaign object with the full object details and properties.

Example response
json
{
  "object": "campaign",
  "id": "e76d4cb7-e1e7-4579-ab24-7967377bfdd7",
  "name": "Weekly Newsletter",
  "status": "active",
  "emails_count": 6,
  "owner": "John Doe",
  "creator": "Jake Workshop",
  "last_editor": "Jane Workshop",
  "created_at": "2021-01-11T00:00:00.000Z",
  "start_date": "2022-01-12T00:00:00.000Z",
  "end_date": null,
  "note": "This is the Weekly Newsletter Campaign",
  "urls": {
    "emails": "/v1/campaigns/e76d4cb7-e1e7-4579-ab24-7967377bfdd7/emails"
  }
}

List emails within a campaign ​

GET /v1/campaigns/:id/emails

Gets a list of emails that are within the given campaign

Parameters ​

NameOptionalDefaultDescriptionOptions
Pagination parametersSee pagination for more information.
sortoptionalcreated_atThe attribute to sort results by.created_at, published_at, recipients_count, opens_count
orderoptionaldescThe order of results based on the sort attribute.desc, asc
stateoptionalnoneFilters results to only include campaigns in the given state.published, scheduled, draft

Returns ​

A list response where data is an array of email summary objects.

Example response
json
{
  "object": "array",
  "has_more": true,
  "next": "/v1/campaigns/e76d4cb7-e1e7-4579-ab24-7967377bfdd7/emails?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "email",
      "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      "title": "Weekly Newsletter - Jan 24",
      "state": "published",
      "owner": "user@example.com",
      "recipients_count": 72,
      "urls": {
        "details": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa",
        "recipients": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/recipients",
        "opens": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/opens",
        "links": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/links",
        "clicks": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/clicks",
      },
    },
    {...},
    {...},
    {...},
    {...},
  ],
}