API Reference

Print Mail

Campaigns

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List Campaigns

GET/print-mail/v1/campaigns

Retrieve a list of campaigns.

Returns a paginated list of campaigns associated with the authenticated organization, filterable by various parameters.

Query ParametersExpand Collapse

limit: optional number

formatint32

search: optional string

You can supply any string to help narrow down the list of resources. For example, if you pass "New York" (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on StructuredSearchQuery for more details.

skip: optional number

formatint32

ReturnsExpand Collapse

data: array of Campaign { id, createdAt, createdCount, 15 more }

id: string

A unique ID prefixed with campaign_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

createdCount: number

The number of orders successfully created for this campaign.

formatint32

live: boolean

true if this is a live mode resource else false.

mailingList: string

The ID of the mailing list associated with this campaign.

status: "drafting" or "changes_required" or "creating_orders" or 4 more

Status of the campaign lifecycle.

One of the following:

"drafting"

"changes_required"

"creating_orders"

"draft"

"ready"

"printing"

"processed_for_delivery"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

chequeProfile: optional string

The ID of the cheque profile used for this campaign, if applicable.

defaultSenderContact: optional string

The ID of the default sender contact to use for orders if not specified per recipient.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: optional array of object { message, type }

A list of processing errors encountered, if any. Present when status is 'changes_required'.

message: string

A human-readable message describing the error.

type: "processing_error" or "internal_error"

Type of error encountered during campaign processing.

One of the following:

"processing_error"

"internal_error"

letterProfile: optional string

The ID of the letter profile used for this campaign, if applicable.

metadata: optional map[unknown]

See the section on Metadata.

orderPreviewURL: optional string

A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.

formaturi

postcardProfile: optional string

The ID of the postcard profile used for this campaign, if applicable.

reportURL: optional string

A temporary URL to download the processing report, available once the campaign is in the ready status.

formaturi

selfMailerProfile: optional string

The ID of the self-mailer profile used for this campaign, if applicable.

sendDate: optional string

The scheduled date and time for the campaign to be sent.

formatdate-time

limit: number

formatint32

object: "list"

skip: number

formatint32

totalCount: number

formatint32

List Campaigns

HTTP

HTTP

TypeScript

Python

curl https://api.postgrid.com/print-mail/v1/campaigns \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"

200 example

{
  "data": [
    {
      "id": "campaign_sqF12lZ1VlBb",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "createdCount": 0,
      "live": true,
      "mailingList": "mailingList",
      "status": "drafting",
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "chequeProfile": "chequeProfile",
      "defaultSenderContact": "defaultSenderContact",
      "description": "description",
      "errors": [
        {
          "message": "message",
          "type": "processing_error"
        }
      ],
      "letterProfile": "letterProfile",
      "metadata": {
        "foo": "bar"
      },
      "orderPreviewURL": "https://example.com",
      "postcardProfile": "postcardProfile",
      "reportURL": "https://example.com",
      "selfMailerProfile": "selfMailerProfile",
      "sendDate": "2019-12-27T18:11:19.117Z"
    }
  ],
  "limit": 0,
  "object": "list",
  "skip": 0,
  "totalCount": 0
}

Returns Examples

200 example

{
  "data": [
    {
      "id": "campaign_sqF12lZ1VlBb",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "createdCount": 0,
      "live": true,
      "mailingList": "mailingList",
      "status": "drafting",
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "chequeProfile": "chequeProfile",
      "defaultSenderContact": "defaultSenderContact",
      "description": "description",
      "errors": [
        {
          "message": "message",
          "type": "processing_error"
        }
      ],
      "letterProfile": "letterProfile",
      "metadata": {
        "foo": "bar"
      },
      "orderPreviewURL": "https://example.com",
      "postcardProfile": "postcardProfile",
      "reportURL": "https://example.com",
      "selfMailerProfile": "selfMailerProfile",
      "sendDate": "2019-12-27T18:11:19.117Z"
    }
  ],
  "limit": 0,
  "object": "list",
  "skip": 0,
  "totalCount": 0
}