---
title: "List Campaigns"
method: GET
path: "/print-mail/v1/campaigns"
tags: ["Campaigns"]
---

# 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 parameters

- `skip` integer
- `limit` integer
- `search` union
  - string
  - string — You can supply a structured search query instead of supplying unstructured text to any list endpoint help refine your search for a resource. For example, let's say you created a series of letters that all had `metadata: { campaignID: 'abc' }`. You could search for all those letters by passing in `{ "metadata.campaignID": "abc" }` into the `search` parameter. Note that this string must be valid JSON.

## Response `200`

A list object containing campaigns.

- CampaignList — A list of campaigns.
  - `object` 'list', required
  - `totalCount` integer, required
  - `skip` integer, required
  - `limit` integer, required
  - `data` Campaign[], required
    - `id` string, required — A unique ID prefixed with campaign_
    - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard.
    - `metadata` object — See the section on Metadata.
    - `live` boolean, required — `true` if this is a live mode resource else `false`.
    - `createdAt` string, date-time, required — The UTC time at which this resource was created.
    - `updatedAt` string, date-time, required — The UTC time at which this resource was last updated.
    - `status` 'drafting' | 'changes_required' | 'creating_orders' | 'draft' | 'ready' | 'printing' | 'processed_for_delivery', required — Status of the campaign lifecycle.
    - `defaultSenderContact` string — The ID of the default sender contact to use for orders if not specified per recipient.
    - `mailingList` string, required — The ID of the mailing list associated with this campaign.
    - `createdCount` integer, required — The number of orders successfully created for this campaign.
    - `letter` CampaignLetterFields — Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
      - `size` 'us_letter' | 'a4' — Enum representing the supported letter sizes.
      - `color` boolean — Whether to print in color.
      - `doubleSided` boolean — Whether to print on both sides of the paper.
      - `envelope` string — The custom envelope ID or `"standard"`.
      - `envelopeType` 'standard_double_window' | 'flat' — The type of envelope used for the letter.
      - `perforatedPage` 1 — Which page number should be perforated (if any).
      - `addressPlacement` 'top_first_page' | 'insert_blank_page' — Enum representing the placement of the address on the letter.
      - `returnEnvelope` string — ID of a return envelope to include.
      - `attachedPDF` AttachedPDF — Model representing an attached PDF.
        - `file` union, required — The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
          - string, uri
          - string, binary — Represents a raw file upload. Sending the actual file requires a `multipart/form-data` request; in `application/json` request bodies, supply a URL instead.
        - `placement` 'before_template' | 'after_template', required — Enum representing the placement of the attached PDF.
      - `template` string — ID of a template for the letter content. Cannot be used with `pdf`.
      - `uploadedPDF` string, uri — A signed URL to the uploaded PDF, if any.
      - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
      - `description` string — An optional description.
      - `metadata` object — Optional key-value metadata.
      - `mergeVariables` object — Default merge variables for the letter.
      - `paper` union
        - 'standard' | 'premium_paper_letter_standard_white_70lb' | 'premium_paper_letter_standard_white_80lb' — Built-in paper IDs for letter products. Actual availability depends on your organization settings.
        - string — Premium paper identifier. `standard` is always accepted. Organizations may also have additional custom `premium_paper_*` IDs beyond the built-in values documented here.
    - `postcard` CampaignPostcardFields — Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
      - `size` '6x4' | '9x6' | '11x6' — Enum representing the supported postcard sizes.
      - `frontTemplate` string — ID of the template for the front side. Cannot be used with `pdf`.
      - `backTemplate` string — ID of the template for the back side. Cannot be used with `pdf`.
      - `uploadedPDF` string, uri — A signed URL to the uploaded PDF, if any.
      - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
      - `paper` union
        - 'standard' | 'premium_paper_heavy_1_glossy' | 'premium_paper_postcard_uv_glossy_ss' | 'premium_paper_postcard_uv_glossy_ss_120lb' | 'premium_paper_postcard_satin_ds' — Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
        - string — Premium paper identifier. `standard` is always accepted. Organizations may also have additional custom `premium_paper_*` IDs beyond the built-in values documented here.
      - `description` string — An optional description.
      - `metadata` object — Optional key-value metadata.
      - `mergeVariables` object — Default merge variables for the postcard.
    - `cheque` CampaignChequeFields — Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
      - `size` 'us_letter' | 'us_legal' — Enum representing the supported cheque sizes.
      - `bankAccount` string — ID of the bank account to use for the cheque.
      - `currencyCode` 'CAD' | 'USD' — Enum representing the supported currency codes.
      - `memo` string — Memo line text for the cheque.
      - `message` string — Message included on the cheque stub.
      - `logo` string, uri — A publicly accessible URL for the logo to print on the cheque.
      - `letterTemplate` string — ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
      - `letterUploadedPDF` string, uri — A signed URL to the attached letter PDF, if any.
      - `envelope` string — The custom envelope ID or `"standard"`.
      - `returnEnvelope` string — ID of a return envelope to include.
      - `letterSettings` object — Settings for the attached letter (e.g., color printing).
        - `color` boolean — Whether to print the attached letter in color.
      - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
      - `description` string — An optional description.
      - `metadata` object — Optional key-value metadata.
      - `mergeVariables` object — Default merge variables for the cheque.
    - `selfMailer` CampaignSelfMailerFields — Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
      - `size` '8.5x11_bifold' | '8.5x11_trifold' | '9.5x16_trifold' — Enum representing the supported self-mailer sizes.
      - `insideTemplate` string — ID of the template for the inside. Cannot be used with `pdf`.
      - `outsideTemplate` string — ID of the template for the outside. Cannot be used with `pdf`.
      - `uploadedPDF` string, uri — A signed URL to the uploaded PDF, if any.
      - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
      - `description` string — An optional description.
      - `metadata` object — Optional key-value metadata.
      - `mergeVariables` object — Default merge variables for the self-mailer.
    - `snapPack` CampaignSnapPackFields — Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
      - `size` '8.5x11_bifold_v' — Enum representing the supported snap pack sizes.
      - `insideTemplate` string — ID of the template for the inside. Cannot be used with `pdf`.
      - `outsideTemplate` string — ID of the template for the outside. Cannot be used with `pdf`.
      - `uploadedPDF` string, uri — A signed URL to the uploaded PDF, if any.
      - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
      - `description` string — An optional description.
      - `metadata` object — Optional key-value metadata.
      - `mergeVariables` object — Default merge variables for the snap pack.
    - `orderPreviewURL` string, uri — A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.
    - `sendDate` string, date-time — The scheduled date and time for the campaign to be sent.
    - `errors` CampaignError[] — A list of processing errors encountered, if any. Present when status is 'changes_required'.
      - `type` 'processing_error' | 'internal_error', required — Type of error encountered during campaign processing.
      - `message` string, required — A human-readable message describing the error.
    - `reportURL` string, uri — A temporary URL to download the processing report, available once the campaign is in the `ready` status.

## Other responses

- `400` — A list object containing campaigns.
- `401` — A list object containing campaigns.
- `429` — A list object containing campaigns.
- `500` — A list object containing campaigns.

---

[API](https://skmtc.net/postgrid/apis/postgrid-address-verification-api.md) · [All operations](https://skmtc.net/postgrid/apis/postgrid-address-verification-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/postgrid/postgrid-address-verification-api/versions/537d2bbc624a/schema)