API Reference

Print Mail

Campaigns

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List Campaigns

print_mail.campaigns.list(CampaignListParams**kwargs) -> SyncSkipLimit[Campaign]

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.

ParametersExpand Collapse

limit: Optional[int]

formatint32

search: Optional[str]

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[int]

formatint32

ReturnsExpand Collapse

class Campaign: …

Represents a bulk mail campaign.

id: str

A unique ID prefixed with campaign_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

created_count: int

The number of orders successfully created for this campaign.

formatint32

live: bool

true if this is a live mode resource else false.

mailing_list: str

The ID of the mailing list associated with this campaign.

status: Literal["drafting", "changes_required", "creating_orders", 4 more]

Status of the campaign lifecycle.

One of the following:

"drafting"

"changes_required"

"creating_orders"

"draft"

"ready"

"printing"

"processed_for_delivery"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

cheque_profile: Optional[str]

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

default_sender_contact: Optional[str]

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

description: Optional[str]

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

errors: Optional[List[Error]]

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

message: str

A human-readable message describing the error.

type: Literal["processing_error", "internal_error"]

Type of error encountered during campaign processing.

One of the following:

"processing_error"

"internal_error"

letter_profile: Optional[str]

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

metadata: Optional[Dict[str, object]]

See the section on Metadata.

order_preview_url: Optional[str]

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

formaturi

postcard_profile: Optional[str]

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

report_url: Optional[str]

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

formaturi

self_mailer_profile: Optional[str]

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

send_date: Optional[datetime]

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

formatdate-time

List Campaigns

Python

HTTP

TypeScript

Python

import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
page = client.print_mail.campaigns.list()
page = page.data[0]
print(page.id)

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
}