## 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. ### Parameters - `limit: Optional[int]` - `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]` ### Returns - `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. - `created_count: int` The number of orders successfully created for this campaign. - `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. - `"drafting"` - `"changes_required"` - `"creating_orders"` - `"draft"` - `"ready"` - `"printing"` - `"processed_for_delivery"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `cheque: Optional[Cheque]` Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting. - `bank_account: Optional[str]` ID of the bank account to use for the cheque. - `currency_code: Optional[Literal["CAD", "USD"]]` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `description: Optional[str]` An optional description. - `envelope: Optional[str]` The custom envelope ID or `"standard"`. - `letter_settings: Optional[ChequeLetterSettings]` Settings for the attached letter (e.g., color printing). - `color: Optional[bool]` Whether to print the attached letter in color. - `letter_template: Optional[str]` ID of a template for an optional attached letter. Cannot be used with `letterPDF`. - `letter_uploaded_pdf: Optional[str]` A signed URL to the attached letter PDF, if any. - `logo: Optional[str]` A publicly accessible URL for the logo to print on the cheque. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class for the cheque. - `"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"` - `memo: Optional[str]` Memo line text for the cheque. - `merge_variables: Optional[Dict[str, object]]` Default merge variables for the cheque. - `message: Optional[str]` Message included on the cheque stub. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `return_envelope: Optional[str]` ID of a return envelope to include. - `size: Optional[ChequeSize]` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `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. - `"processing_error"` - `"internal_error"` - `letter: Optional[Letter]` Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting. - `address_placement: Optional[AddressPlacement]` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attached_pdf: Optional[AttachedPdf]` Model representing an attached PDF. - `file: str` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: Literal["before_template", "after_template"]` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `color: Optional[bool]` Whether to print in color. - `description: Optional[str]` An optional description. - `double_sided: Optional[bool]` Whether to print on both sides of the paper. - `envelope: Optional[str]` The custom envelope ID or `"standard"`. - `envelope_type: Optional[Literal["standard_double_window", "flat"]]` The type of envelope used for the letter. - `"standard_double_window"` - `"flat"` - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class for the letter. - `"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"` - `merge_variables: Optional[Dict[str, object]]` Default merge variables for the letter. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]` Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard". - `Literal["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. - `"standard"` - `"premium_paper_letter_standard_white_70lb"` - `"premium_paper_letter_standard_white_80lb"` - `str` Premium paper identifier. `standard` is always accepted. Organizations may also have additional custom `premium_paper_*` IDs beyond the built-in values documented here. - `perforated_page: Optional[Literal[1]]` Which page number should be perforated (if any). - `1` - `return_envelope: Optional[str]` ID of a return envelope to include. - `size: Optional[LetterSize]` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `template: Optional[str]` ID of a template for the letter content. Cannot be used with `pdf`. - `uploaded_pdf: Optional[str]` A signed URL to the uploaded PDF, if any. - `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. - `postcard: Optional[Postcard]` Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting. - `back_template: Optional[str]` ID of the template for the back side. Cannot be used with `pdf`. - `description: Optional[str]` An optional description. - `front_template: Optional[str]` ID of the template for the front side. Cannot be used with `pdf`. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class for the postcard. - `"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"` - `merge_variables: Optional[Dict[str, object]]` Default merge variables for the postcard. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]` Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard". - `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]` Built-in paper IDs for postcard products. Actual availability depends on your organization settings. - `"standard"` - `"premium_paper_heavy_1_glossy"` - `"premium_paper_postcard_uv_glossy_ss"` - `"premium_paper_postcard_uv_glossy_ss_120lb"` - `"premium_paper_postcard_satin_ds"` - `str` Premium paper identifier. `standard` is always accepted. Organizations may also have additional custom `premium_paper_*` IDs beyond the built-in values documented here. - `size: Optional[Literal["6x4", "9x6", "11x6"]]` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `uploaded_pdf: Optional[str]` A signed URL to the uploaded PDF, if any. - `report_url: Optional[str]` A temporary URL to download the processing report, available once the campaign is in the `ready` status. - `self_mailer: Optional[SelfMailer]` Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting. - `description: Optional[str]` An optional description. - `inside_template: Optional[str]` ID of the template for the inside. Cannot be used with `pdf`. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class for the self-mailer. - `"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"` - `merge_variables: Optional[Dict[str, object]]` Default merge variables for the self-mailer. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `outside_template: Optional[str]` ID of the template for the outside. Cannot be used with `pdf`. - `size: Optional[Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]]` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `uploaded_pdf: Optional[str]` A signed URL to the uploaded PDF, if any. - `send_date: Optional[datetime]` The scheduled date and time for the campaign to be sent. - `snap_pack: Optional[SnapPack]` Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting. - `description: Optional[str]` An optional description. - `inside_template: Optional[str]` ID of the template for the inside. Cannot be used with `pdf`. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class for the snap pack. - `"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"` - `merge_variables: Optional[Dict[str, object]]` Default merge variables for the snap pack. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `outside_template: Optional[str]` ID of the template for the outside. Cannot be used with `pdf`. - `size: Optional[Literal["8.5x11_bifold_v"]]` Enum representing the supported snap pack sizes. - `"8.5x11_bifold_v"` - `uploaded_pdf: Optional[str]` A signed URL to the uploaded PDF, if any. ### Example ```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) ``` #### Response ```json { "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", "cheque": { "bankAccount": "bankAccount", "currencyCode": "CAD", "description": "description", "envelope": "envelope", "letterSettings": { "color": true }, "letterTemplate": "letterTemplate", "letterUploadedPDF": "https://example.com", "logo": "https://example.com", "mailingClass": "first_class", "memo": "memo", "mergeVariables": { "foo": "bar" }, "message": "message", "metadata": { "foo": "string" }, "returnEnvelope": "returnEnvelope", "size": "us_letter" }, "defaultSenderContact": "defaultSenderContact", "description": "description", "errors": [ { "message": "message", "type": "processing_error" } ], "letter": { "addressPlacement": "top_first_page", "attachedPDF": { "file": "https://example.com", "placement": "before_template" }, "color": true, "description": "description", "doubleSided": true, "envelope": "envelope", "envelopeType": "standard_double_window", "mailingClass": "first_class", "mergeVariables": { "foo": "bar" }, "metadata": { "foo": "string" }, "paper": "standard", "perforatedPage": 1, "returnEnvelope": "returnEnvelope", "size": "us_letter", "template": "template", "uploadedPDF": "https://example.com" }, "metadata": { "foo": "bar" }, "orderPreviewURL": "https://example.com", "postcard": { "backTemplate": "backTemplate", "description": "description", "frontTemplate": "frontTemplate", "mailingClass": "first_class", "mergeVariables": { "foo": "bar" }, "metadata": { "foo": "string" }, "paper": "standard", "size": "6x4", "uploadedPDF": "https://example.com" }, "reportURL": "https://example.com", "selfMailer": { "description": "description", "insideTemplate": "insideTemplate", "mailingClass": "first_class", "mergeVariables": { "foo": "bar" }, "metadata": { "foo": "string" }, "outsideTemplate": "outsideTemplate", "size": "8.5x11_bifold", "uploadedPDF": "https://example.com" }, "sendDate": "2019-12-27T18:11:19.117Z", "snapPack": { "description": "description", "insideTemplate": "insideTemplate", "mailingClass": "first_class", "mergeVariables": { "foo": "bar" }, "metadata": { "foo": "string" }, "outsideTemplate": "outsideTemplate", "size": "8.5x11_bifold_v", "uploadedPDF": "https://example.com" } } ], "limit": 0, "object": "list", "skip": 0, "totalCount": 0 } ```