# Print Mail ## Domain Types ### Contact Create With Company Name - `class ContactCreateWithCompanyName: …` - `address_line1: str` The first line of the contact's address. - `company_name: str` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. ### Contact Create With First Name - `class ContactCreateWithFirstName: …` - `address_line1: str` The first line of the contact's address. - `country_code: str` The ISO 3611-1 country code of the contact's address. - `first_name: str` - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. # Bank Accounts ## Create Bank Account `print_mail.bank_accounts.create(BankAccountCreateParams**kwargs) -> BankAccount` **post** `/print-mail/v1/bank_accounts` Create a bank account. A US bank account is created by setting `bankCountryCode` to `US` and providing `accountNumber` and `routingNumber`. A canadian bank account can be created by specifying `bankCountryCode` as `CA` and setting `accountNumber`, `routeNumber`, and `transitNumber` accordingly. You must specify _either_ `signatureImage` or `signatureText`. The image can be supplied as either a URL or a multipart file upload. ### Parameters - `account_number: str` The account number of the bank account. - `bank_country_code: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bank_name: str` The name of the bank. - `signature_text: str` The signature text of the bank account. - `bank_primary_line: Optional[str]` The primary address line of the bank. - `bank_secondary_line: Optional[str]` The secondary address line of the bank. - `ca_designation_number: Optional[str]` The designation number of the bank account (for CA). - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `route_number: Optional[str]` The route number of the bank account (for CA). - `routing_number: Optional[str]` The routing number of the bank account (for US). - `transit_number: Optional[str]` The transit number of the bank account (for CA). ### Returns - `class BankAccount: …` - `id: str` A unique ID prefixed with bank_account_ - `account_number: str` The account number of the bank account. - `bank_country_code: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bank_name: str` The name of the bank. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["bank_account"]` Always `bank_account`. - `"bank_account"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `bank_primary_line: Optional[str]` The primary address line of the bank. - `bank_secondary_line: Optional[str]` The secondary address line of the bank. - `ca_designation_number: Optional[str]` The designation number of the bank account (for CA). - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `route_number: Optional[str]` The route number of the bank account (for CA). - `routing_number: Optional[str]` The routing number of the bank account (for US). - `signature_image: Optional[str]` A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present. - `signature_text: Optional[str]` The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present. - `transit_number: Optional[str]` The transit number of the bank account (for CA). ### 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 ) bank_account = client.print_mail.bank_accounts.create( account_number="1234567", bank_country_code="US", bank_name="Test Bank", signature_text="Example", bank_primary_line="145 mulberry st", bank_secondary_line="new york ny 10013", routing_number="123456789", ) print(bank_account.id) ``` #### Response ```json { "id": "bank_account_12345", "object": "bank_account", "live": false, "bankName": "Test Bank", "bankPrimaryLine": "145 mulberry st", "bankSecondaryLine": "new york ny 10013", "bankCountryCode": "US", "accountNumber": "1234567", "routingNumber": "123456789", "signatureText": "Signature", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ``` ## List Bank Accounts `print_mail.bank_accounts.list(BankAccountListParams**kwargs) -> SyncSkipLimit[BankAccount]` **get** `/print-mail/v1/bank_accounts` Get a list of bank accounts. ### 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 BankAccount: …` - `id: str` A unique ID prefixed with bank_account_ - `account_number: str` The account number of the bank account. - `bank_country_code: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bank_name: str` The name of the bank. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["bank_account"]` Always `bank_account`. - `"bank_account"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `bank_primary_line: Optional[str]` The primary address line of the bank. - `bank_secondary_line: Optional[str]` The secondary address line of the bank. - `ca_designation_number: Optional[str]` The designation number of the bank account (for CA). - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `route_number: Optional[str]` The route number of the bank account (for CA). - `routing_number: Optional[str]` The routing number of the bank account (for US). - `signature_image: Optional[str]` A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present. - `signature_text: Optional[str]` The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present. - `transit_number: Optional[str]` The transit number of the bank account (for CA). ### 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.bank_accounts.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "bank_account_12345", "object": "bank_account", "live": false, "bankName": "Test Bank", "bankPrimaryLine": "145 mulberry st", "bankSecondaryLine": "new york ny 10013", "bankCountryCode": "US", "accountNumber": "1234567", "routingNumber": "123456789", "signatureText": "Signature", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ] } ``` ## Get Bank Account `print_mail.bank_accounts.retrieve(strid) -> BankAccount` **get** `/print-mail/v1/bank_accounts/{id}` Retrieve a bank account by ID. ### Parameters - `id: str` ### Returns - `class BankAccount: …` - `id: str` A unique ID prefixed with bank_account_ - `account_number: str` The account number of the bank account. - `bank_country_code: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bank_name: str` The name of the bank. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["bank_account"]` Always `bank_account`. - `"bank_account"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `bank_primary_line: Optional[str]` The primary address line of the bank. - `bank_secondary_line: Optional[str]` The secondary address line of the bank. - `ca_designation_number: Optional[str]` The designation number of the bank account (for CA). - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `route_number: Optional[str]` The route number of the bank account (for CA). - `routing_number: Optional[str]` The routing number of the bank account (for US). - `signature_image: Optional[str]` A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present. - `signature_text: Optional[str]` The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present. - `transit_number: Optional[str]` The transit number of the bank account (for CA). ### 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 ) bank_account = client.print_mail.bank_accounts.retrieve( "id", ) print(bank_account.id) ``` #### Response ```json { "id": "bank_account_12345", "object": "bank_account", "live": false, "bankName": "Test Bank", "bankPrimaryLine": "145 mulberry st", "bankSecondaryLine": "new york ny 10013", "bankCountryCode": "US", "accountNumber": "1234567", "routingNumber": "123456789", "signatureText": "Signature", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ``` ## Delete Bank Account `print_mail.bank_accounts.delete(strid) -> BankAccountDeleteResponse` **delete** `/print-mail/v1/bank_accounts/{id}` Delete a bank account by ID. Note that this operation cannot be undone. ### Parameters - `id: str` ### Returns - `class BankAccountDeleteResponse: …` - `id: str` A unique ID prefixed with bank_account_ - `deleted: Literal[true]` - `true` - `object: Literal["bank_account"]` Always `bank_account`. - `"bank_account"` ### 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 ) bank_account = client.print_mail.bank_accounts.delete( "id", ) print(bank_account.id) ``` #### Response ```json { "id": "bank_account_sqF12lZ1VlBb", "deleted": true, "object": "bank_account" } ``` ## Domain Types ### Bank Account - `class BankAccount: …` - `id: str` A unique ID prefixed with bank_account_ - `account_number: str` The account number of the bank account. - `bank_country_code: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bank_name: str` The name of the bank. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["bank_account"]` Always `bank_account`. - `"bank_account"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `bank_primary_line: Optional[str]` The primary address line of the bank. - `bank_secondary_line: Optional[str]` The secondary address line of the bank. - `ca_designation_number: Optional[str]` The designation number of the bank account (for CA). - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `route_number: Optional[str]` The route number of the bank account (for CA). - `routing_number: Optional[str]` The routing number of the bank account (for US). - `signature_image: Optional[str]` A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present. - `signature_text: Optional[str]` The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present. - `transit_number: Optional[str]` The transit number of the bank account (for CA). ### Bank Account Country Code - `Literal["CA", "US"]` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` # Campaigns ## Create Campaign `print_mail.campaigns.create(CampaignCreateParams**kwargs) -> Campaign` **post** `/print-mail/v1/campaigns` Create a new campaign. A campaign links a mailing list with a specific mail piece profile (letter, postcard, cheque, or self-mailer) to send bulk mail. Upon creation, the campaign enters the `drafting` status while assets are validated. ### Parameters - `mailing_list: str` The ID of the mailing list associated with this campaign. - `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. - `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. - `postcard_profile: Optional[str]` The ID of the postcard profile used for this campaign, if applicable. - `self_mailer_profile: Optional[str]` The ID of the self-mailer profile used for this campaign, if applicable. - `send_date: Optional[Union[str, datetime]]` The scheduled date and time for the campaign to be sent. - `idempotency_key: Optional[str]` ### 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_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. - `"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. - `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. - `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. ### 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 ) campaign = client.print_mail.campaigns.create( mailing_list="mailingList", ) print(campaign.id) ``` #### Response ```json { "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" } ``` ## 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_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. - `"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. - `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. - `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. ### 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", "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 } ``` ## Get Campaign `print_mail.campaigns.retrieve(strid) -> Campaign` **get** `/print-mail/v1/campaigns/{id}` Retrieve a specific campaign by its ID. ### Parameters - `id: str` ### 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_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. - `"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. - `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. - `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. ### 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 ) campaign = client.print_mail.campaigns.retrieve( "id", ) print(campaign.id) ``` #### Response ```json { "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" } ``` ## Update Campaign `print_mail.campaigns.update(strid, CampaignUpdateParams**kwargs) -> Campaign` **post** `/print-mail/v1/campaigns/{id}` Update an existing campaign. Campaigns can only be updated if they are in the `draft` or `changes_required` status. Updating a campaign will trigger reprocessing and set its status back to `drafting`. ### Parameters - `id: str` - `cheque_profile: Optional[str]` The ID of the cheque profile to use. Setting this will remove other profile types. Set to `null` to remove. - `default_sender_contact: Optional[str]` The ID of the default sender contact. Set to `null` to remove. - `description: Optional[str]` An optional description for the campaign. Set to `null` to remove the existing description. - `letter_profile: Optional[str]` The ID of the letter profile to use. Setting this will remove other profile types. Set to `null` to remove. - `mailing_list: Optional[str]` The ID of the mailing list to associate with this campaign. - `metadata: Optional[Dict[str, str]]` Optional key-value data associated with the campaign. Set to `null` to remove existing metadata. - `postcard_profile: Optional[str]` The ID of the postcard profile to use. Setting this will remove other profile types. Set to `null` to remove. - `self_mailer_profile: Optional[str]` The ID of the self-mailer profile to use. Setting this will remove other profile types. Set to `null` to remove. ### 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_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. - `"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. - `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. - `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. ### 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 ) campaign = client.print_mail.campaigns.update( id="id", ) print(campaign.id) ``` #### Response ```json { "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" } ``` ## Delete Campaign `print_mail.campaigns.delete(strid) -> CampaignDeleteResponse` **delete** `/print-mail/v1/campaigns/{id}` Delete a campaign. Campaigns can only be deleted if they are in `draft`, `changes_required`, or `ready` status. This also permanently deletes associated resources. This operation cannot be undone. ### Parameters - `id: str` ### Returns - `class CampaignDeleteResponse: …` - `id: str` A unique ID prefixed with campaign_ - `deleted: Literal[true]` - `true` ### 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 ) campaign = client.print_mail.campaigns.delete( "id", ) print(campaign.id) ``` #### Response ```json { "id": "campaign_sqF12lZ1VlBb", "deleted": true } ``` ## Send Campaign `print_mail.campaigns.send(strid, CampaignSendParams**kwargs) -> Campaign` **post** `/print-mail/v1/campaigns/{id}/send` Send a campaign for processing. This action transitions a campaign from the `draft` status to `creating_orders`. You can optionally specify a future `sendDate`. Once sent, the campaign cannot be updated. ### Parameters - `id: str` - `send_date: Optional[Union[Union[str, datetime], str]]` The date and time the campaign should be sent. Must be in the future. If omitted, defaults to the earliest possible processing date. - `Union[str, datetime]` - `str` ### 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_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. - `"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. - `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. - `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. ### 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 ) campaign = client.print_mail.campaigns.send( id="id", ) print(campaign.id) ``` #### Response ```json { "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" } ``` ## Domain Types ### Campaign - `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_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. - `"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. - `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. - `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. # Cheques ## Create Cheque `print_mail.cheques.create(ChequeCreateParams**kwargs) -> Cheque` **post** `/print-mail/v1/cheques` Create a cheque. This endpoint allows you to create a new cheque with the specified details. If you would like to create a digitalOnly cheque, the digitalOnly object with the watermark will need to be passed in. Feature is available on request, e-mail support@postgrid.com for access. Example request body: ```json { "from": "contact_123", "bankAccount": "bank_123", "amount": 1000, "currencyCode": "USD", "number": 123456, "size": "us_letter", "digitalOnly": { "watermark": "VOID" } } ``` ### Parameters - `amount: int` The amount of the cheque in cents. - `bank_account: str` The bank account (ID) associated with the cheque. - `from_: From` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. - `class ContactCreateWithFirstName: …` - `address_line1: str` The first line of the contact's address. - `country_code: str` The ISO 3611-1 country code of the contact's address. - `first_name: str` - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `class ContactCreateWithCompanyName: …` - `address_line1: str` The first line of the contact's address. - `company_name: str` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `str` - `to: To` The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint. - `class ContactCreateWithFirstName: …` - `class ContactCreateWithCompanyName: …` - `str` - `currency_code: Optional[Literal["USD", "CAD"]]` The currency code of the cheque. This will be set to the default currency of the bank account (`USD` for US bank accounts and `CAD` for Canadian bank accounts) if not provided. You can set this value to `USD` if you want to draw USD from a Canadian bank account or vice versa. - `"USD"` - `"CAD"` - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `digital_only: Optional[DigitalOnlyParam]` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: str` Text to be displayed as a watermark on the digital cheque. - `envelope: Optional[Union[Literal["standard"], str]]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `Literal["standard"]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `str` - `logo_url: Optional[str]` An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file). - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` The mailing class of this order. If not provided, automatically set to `first_class`. - `"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]` The memo of the cheque. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `message: Optional[str]` The message of the cheque. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `number: Optional[int]` The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number. - `redirect_to: Optional[RedirectTo]` Providing this inserts a blank page at the start of the cheque with the recipient you provide here. This leaves the cheque that follows intact, which means you can use this to intercept at cheque at the redirected address and then mail it forward to the final recipient yourself. One use case for this is signing cheques at your office before mailing them out yourself. - `class ContactCreateWithFirstName: …` - `class ContactCreateWithCompanyName: …` - `str` - `send_date: Optional[Union[str, datetime]]` This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date. - `size: Optional[ChequeSize]` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` ### Returns - `class Cheque: …` - `id: str` A unique ID prefixed with cheque_ - `amount: int` The amount of the cheque in cents. - `bank_account: str` The bank account (ID) associated with the cheque. - `created_at: datetime` The UTC time at which this resource was created. - `currency_code: Literal["USD", "CAD"]` The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified. - `"USD"` - `"CAD"` - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["cheque"]` Always `cheque`. - `"cheque"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `deposit_ready_pdfurl: Optional[str]` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `digital_only: Optional[DigitalOnly]` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: str` Text to be displayed as a watermark on the digital cheque. - `envelope: Optional[Union[Literal["standard"], str, null]]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `Literal["standard"]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `str` - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logo_url: Optional[str]` An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file). - `memo: Optional[str]` The memo of the cheque. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `message: Optional[str]` The message of the cheque. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `number: Optional[int]` The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) cheque = client.print_mail.cheques.create( amount=1000, bank_account="bank_123", from_="contact_123", to="contact_123", currency_code="USD", number=123456, size="us_letter", ) print(cheque.id) ``` #### Response ```json { "id": "cheque_123456", "object": "cheque", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "bankAccount": "bank_123", "amount": 1000, "currencyCode": "USD", "number": 123456, "size": "us_letter", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ``` ## List Cheques `print_mail.cheques.list(ChequeListParams**kwargs) -> SyncSkipLimit[Cheque]` **get** `/print-mail/v1/cheques` Get a list of cheques. ### 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 Cheque: …` - `id: str` A unique ID prefixed with cheque_ - `amount: int` The amount of the cheque in cents. - `bank_account: str` The bank account (ID) associated with the cheque. - `created_at: datetime` The UTC time at which this resource was created. - `currency_code: Literal["USD", "CAD"]` The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified. - `"USD"` - `"CAD"` - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["cheque"]` Always `cheque`. - `"cheque"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `deposit_ready_pdfurl: Optional[str]` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `digital_only: Optional[DigitalOnly]` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: str` Text to be displayed as a watermark on the digital cheque. - `envelope: Optional[Union[Literal["standard"], str, null]]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `Literal["standard"]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `str` - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logo_url: Optional[str]` An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file). - `memo: Optional[str]` The memo of the cheque. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `message: Optional[str]` The message of the cheque. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `number: Optional[int]` The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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.cheques.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "cheque_123456", "object": "cheque", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "bankAccount": "bank_123", "amount": 1000, "currencyCode": "USD", "number": 123456, "size": "us_letter", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ] } ``` ## Get Cheque `print_mail.cheques.retrieve(strid) -> Cheque` **get** `/print-mail/v1/cheques/{id}` Retrieve a cheque by ID. ### Parameters - `id: str` ### Returns - `class Cheque: …` - `id: str` A unique ID prefixed with cheque_ - `amount: int` The amount of the cheque in cents. - `bank_account: str` The bank account (ID) associated with the cheque. - `created_at: datetime` The UTC time at which this resource was created. - `currency_code: Literal["USD", "CAD"]` The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified. - `"USD"` - `"CAD"` - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["cheque"]` Always `cheque`. - `"cheque"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `deposit_ready_pdfurl: Optional[str]` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `digital_only: Optional[DigitalOnly]` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: str` Text to be displayed as a watermark on the digital cheque. - `envelope: Optional[Union[Literal["standard"], str, null]]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `Literal["standard"]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `str` - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logo_url: Optional[str]` An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file). - `memo: Optional[str]` The memo of the cheque. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `message: Optional[str]` The message of the cheque. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `number: Optional[int]` The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) cheque = client.print_mail.cheques.retrieve( "id", ) print(cheque.id) ``` #### Response ```json { "id": "cheque_123456", "object": "cheque", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "bankAccount": "bank_123", "amount": 1000, "currencyCode": "USD", "number": 123456, "size": "us_letter", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ``` ## Cancel Cheque `print_mail.cheques.delete(strid) -> Cheque` **delete** `/print-mail/v1/cheques/{id}` Cancel a cheque by ID. Note that this operation cannot be undone. ### Parameters - `id: str` ### Returns - `class Cheque: …` - `id: str` A unique ID prefixed with cheque_ - `amount: int` The amount of the cheque in cents. - `bank_account: str` The bank account (ID) associated with the cheque. - `created_at: datetime` The UTC time at which this resource was created. - `currency_code: Literal["USD", "CAD"]` The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified. - `"USD"` - `"CAD"` - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["cheque"]` Always `cheque`. - `"cheque"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `deposit_ready_pdfurl: Optional[str]` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `digital_only: Optional[DigitalOnly]` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: str` Text to be displayed as a watermark on the digital cheque. - `envelope: Optional[Union[Literal["standard"], str, null]]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `Literal["standard"]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `str` - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logo_url: Optional[str]` An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file). - `memo: Optional[str]` The memo of the cheque. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `message: Optional[str]` The message of the cheque. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `number: Optional[int]` The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) cheque = client.print_mail.cheques.delete( "id", ) print(cheque.id) ``` #### Response ```json { "id": "cheque_123456", "object": "cheque", "status": "cancelled", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "bankAccount": "bank_123", "amount": 1000, "currencyCode": "USD", "number": 123456, "size": "us_letter", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ``` ## Get Cheque Preview `print_mail.cheques.retrieve_url(strid) -> ChequeRetrieveURLResponse` **get** `/print-mail/v1/cheques/{id}/url` Retrieve a cheque preview URL. This is only available for customers with our document management addon, which offers document generation and hosting capabilities. This endpoint has a much higher rate limit than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases. ### Parameters - `id: str` ### Returns - `class ChequeRetrieveURLResponse: …` - `id: str` A unique ID prefixed with cheque_ - `object: str` - `url: str` A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call. ### 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 ) response = client.print_mail.cheques.retrieve_url( "id", ) print(response.id) ``` #### Response ```json { "id": "cheque_123456", "object": "cheque_url", "url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/cheque_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D" } ``` ## Retrieve Cheque Deposit-Ready PDF (Digital Only) `print_mail.cheques.retrieve_with_deposit_ready_pdf(strid) -> Cheque` **get** `/print-mail/v1/cheques/{id}/with_deposit_ready_pdf` Retrieve the deposit-ready PDF for a digital-only cheque. The endpoint can only be called by users with 'Admin' role. In test mode, the preview PDF of the digitalOnly cheque and the deposit-ready PDF are the same. In live mode, the deposit-ready will have the full account number. ### Parameters - `id: str` ### Returns - `class Cheque: …` - `id: str` A unique ID prefixed with cheque_ - `amount: int` The amount of the cheque in cents. - `bank_account: str` The bank account (ID) associated with the cheque. - `created_at: datetime` The UTC time at which this resource was created. - `currency_code: Literal["USD", "CAD"]` The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified. - `"USD"` - `"CAD"` - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["cheque"]` Always `cheque`. - `"cheque"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `deposit_ready_pdfurl: Optional[str]` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `digital_only: Optional[DigitalOnly]` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: str` Text to be displayed as a watermark on the digital cheque. - `envelope: Optional[Union[Literal["standard"], str, null]]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `Literal["standard"]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `str` - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logo_url: Optional[str]` An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file). - `memo: Optional[str]` The memo of the cheque. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `message: Optional[str]` The message of the cheque. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `number: Optional[int]` The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) cheque = client.print_mail.cheques.retrieve_with_deposit_ready_pdf( "id", ) print(cheque.id) ``` #### Response ```json { "id": "cheque_123456", "object": "cheque", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "bankAccount": "bank_123", "amount": 1000, "currencyCode": "USD", "number": 123456, "size": "us_letter", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class", "digitalOnly": { "watermark": "TEST" }, "depositReadyPDFURL": "https://example.s3.amazonaws.com/deposit_ready.pdf" } ``` ## Domain Types ### Cheque - `class Cheque: …` - `id: str` A unique ID prefixed with cheque_ - `amount: int` The amount of the cheque in cents. - `bank_account: str` The bank account (ID) associated with the cheque. - `created_at: datetime` The UTC time at which this resource was created. - `currency_code: Literal["USD", "CAD"]` The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified. - `"USD"` - `"CAD"` - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["cheque"]` Always `cheque`. - `"cheque"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `deposit_ready_pdfurl: Optional[str]` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `digital_only: Optional[DigitalOnly]` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: str` Text to be displayed as a watermark on the digital cheque. - `envelope: Optional[Union[Literal["standard"], str, null]]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `Literal["standard"]` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `str` - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logo_url: Optional[str]` An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file). - `memo: Optional[str]` The memo of the cheque. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `message: Optional[str]` The message of the cheque. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `number: Optional[int]` The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### Cheque Size - `Literal["us_letter", "us_legal"]` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` ### Digital Only - `class DigitalOnly: …` - `watermark: str` Text to be displayed as a watermark on the digital cheque. # Contacts ## Create Contact `print_mail.contacts.create(ContactCreateParams**kwargs) -> Contact` **post** `/print-mail/v1/contacts` Creates a contact. This will also verify the contact's address **if you create it using a live API key**. To sucessfully create a contact, either a `firstName`, a `companyName`, or both are required. You can supply both, but you **cannot** supply neither. You have the option to supply the entire address (except for `countryCode`) via `addressLine1`, in which case PostGrid will parse it automatically. However, this is **not guaranteed to be correct**, so we recommend passing along the structured address fields (`city`, `provinceOrState`, etc) if you have them. _Note that if you create a contact that has identical information to another contact, this will simply update the description of the existing contact and return it. This avoids creating duplicate contacts._ ### Parameters - `address_line1: str` The first line of the contact's address. - `country_code: str` The ISO 3611-1 country code of the contact's address. - `first_name: str` - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. ### Returns - `class Contact: …` - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. ### 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 ) contact = client.print_mail.contacts.create( address_line1="90 Canal St Suite 600, Boston MA 90210", country_code="US", first_name="Kevin", company_name="PostGrid", ) print(contact.id) ``` #### Response ```json { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" } ``` ## List Contacts `print_mail.contacts.list(ContactListParams**kwargs) -> SyncSkipLimit[Contact]` **get** `/print-mail/v1/contacts` Get a list of contacts. ### 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 Contact: …` - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. ### 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.contacts.list() page = page.data[0] print(page.id) ``` #### Response ```json { "skip": 0, "limit": 10, "totalCount": 1, "object": "list", "data": [ { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" } ] } ``` ## Get Contact `print_mail.contacts.retrieve(strid) -> Contact` **get** `/print-mail/v1/contacts/{id}` Retrieve a contact. ### Parameters - `id: str` ### Returns - `class Contact: …` - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. ### 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 ) contact = client.print_mail.contacts.retrieve( "id", ) print(contact.id) ``` #### Response ```json { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" } ``` ## Delete Contact `print_mail.contacts.delete(strid) -> ContactDeleteResponse` **delete** `/print-mail/v1/contacts/{id}` Delete a contact. Note that this will not affect orders that were sent to this contact. ### Parameters - `id: str` ### Returns - `class ContactDeleteResponse: …` - `id: str` A unique ID prefixed with contact_ - `deleted: Literal[true]` - `true` - `object: Literal["contact"]` Always `contact`. - `"contact"` ### 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 ) contact = client.print_mail.contacts.delete( "id", ) print(contact.id) ``` #### Response ```json { "id": "contact_sqF12lZ1VlBb", "deleted": true, "object": "contact" } ``` ## Domain Types ### Contact - `class Contact: …` - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. ### Contact Create - `ContactCreate` - `class ContactCreateWithFirstName: …` - `address_line1: str` The first line of the contact's address. - `country_code: str` The ISO 3611-1 country code of the contact's address. - `first_name: str` - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `class ContactCreateWithCompanyName: …` - `address_line1: str` The first line of the contact's address. - `company_name: str` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. # Letters ## Create Letter `print_mail.letters.create(LetterCreateParams**kwargs) -> Letter` **post** `/print-mail/v1/letters` Create a letter. Note that you can supply one of the following: - HTML content for the letter - A template ID for the letter - A URL or file for a PDF for the letter - Upload the aforementioned PDF file via a multipart form upload request ### Parameters - `from_: LetterCreateWithHTMLFrom` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. - `class ContactCreateWithFirstName: …` - `address_line1: str` The first line of the contact's address. - `country_code: str` The ISO 3611-1 country code of the contact's address. - `first_name: str` - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `class ContactCreateWithCompanyName: …` - `address_line1: str` The first line of the contact's address. - `company_name: str` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `str` - `html: str` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `to: LetterCreateWithHTMLTo` The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint. - `class ContactCreateWithFirstName: …` - `class ContactCreateWithCompanyName: …` - `str` - `address_placement: Optional[AddressPlacement]` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attached_pdf: Optional[AttachedPdfParam]` 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]` Indicates if the letter is in color. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `double_sided: Optional[bool]` Indicates if the letter is double-sided. - `envelope: Optional[str]` The envelope (ID) for the letter. You can either specify a custom envelope ID or use the default `standard` envelope. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` The mailing class of this order. If not provided, automatically set to `first_class`. - `"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]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `perforated_page: Optional[Literal[1]]` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plastic_card: Optional[PlasticCardParam]` Model representing a plastic card. - `size: Literal["standard"]` Enum representing the size of the plastic card. - `"standard"` - `double_sided: Optional[DoubleSided]` Model representing a double-sided plastic card. - `back_html: Optional[str]` The HTML content for the back side of the double-sided plastic card. - `back_template: Optional[str]` The template ID for the back side of the double-sided plastic card. - `front_html: Optional[str]` The HTML content for the front side of the double-sided plastic card. - `front_template: Optional[str]` The template ID for the front side of the double-sided plastic card. - `pdf: Optional[str]` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `single_sided: Optional[SingleSided]` Model representing a single-sided plastic card. - `html: Optional[str]` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: Optional[str]` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: Optional[str]` The template ID for the single-sided plastic card. - `return_envelope: Optional[str]` The return envelope (ID) sent out with the letter, if any. - `send_date: Optional[Union[str, datetime]]` This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date. - `size: Optional[LetterSize]` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` ### Returns - `class Letter: …` - `id: str` A unique ID prefixed with letter_ - `address_placement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: bool` Indicates if the letter is in color. - `created_at: datetime` The UTC time at which this resource was created. - `double_sided: bool` Indicates if the letter is double-sided. - `envelope: str` The envelope (ID) for the letter or the default `standard` envelope. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["letter"]` Always `letter`. - `"letter"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `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"` - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `pdf_workflow_run: Optional[str]` The ID of the PDF workflow run that created the letter, if any. - `perforated_page: Optional[Literal[1]]` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plastic_card: Optional[PlasticCard]` Model representing a plastic card. - `size: Literal["standard"]` Enum representing the size of the plastic card. - `"standard"` - `double_sided: Optional[DoubleSided]` Model representing a double-sided plastic card. - `back_html: Optional[str]` The HTML content for the back side of the double-sided plastic card. - `back_template: Optional[str]` The template ID for the back side of the double-sided plastic card. - `front_html: Optional[str]` The HTML content for the front side of the double-sided plastic card. - `front_template: Optional[str]` The template ID for the front side of the double-sided plastic card. - `pdf: Optional[str]` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `single_sided: Optional[SingleSided]` Model representing a single-sided plastic card. - `html: Optional[str]` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: Optional[str]` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: Optional[str]` The template ID for the single-sided plastic card. - `return_envelope: Optional[str]` The return envelope (ID) sent out with the letter, if any. - `template: Optional[str]` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploaded_pdf: Optional[str]` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) letter = client.print_mail.letters.create( from_="contact_123", html="Content", to="contact_123", ) print(letter.id) ``` #### Response ```json { "id": "letter_123456", "object": "letter", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "us_letter", "doubleSided": true, "color": false, "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class", "envelope": "standard", "addressPlacement": "top_first_page", "html": "Content" } ``` ## List Letters `print_mail.letters.list(LetterListParams**kwargs) -> SyncSkipLimit[Letter]` **get** `/print-mail/v1/letters` Get a list of letters. ### 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 Letter: …` - `id: str` A unique ID prefixed with letter_ - `address_placement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: bool` Indicates if the letter is in color. - `created_at: datetime` The UTC time at which this resource was created. - `double_sided: bool` Indicates if the letter is double-sided. - `envelope: str` The envelope (ID) for the letter or the default `standard` envelope. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["letter"]` Always `letter`. - `"letter"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `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"` - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `pdf_workflow_run: Optional[str]` The ID of the PDF workflow run that created the letter, if any. - `perforated_page: Optional[Literal[1]]` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plastic_card: Optional[PlasticCard]` Model representing a plastic card. - `size: Literal["standard"]` Enum representing the size of the plastic card. - `"standard"` - `double_sided: Optional[DoubleSided]` Model representing a double-sided plastic card. - `back_html: Optional[str]` The HTML content for the back side of the double-sided plastic card. - `back_template: Optional[str]` The template ID for the back side of the double-sided plastic card. - `front_html: Optional[str]` The HTML content for the front side of the double-sided plastic card. - `front_template: Optional[str]` The template ID for the front side of the double-sided plastic card. - `pdf: Optional[str]` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `single_sided: Optional[SingleSided]` Model representing a single-sided plastic card. - `html: Optional[str]` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: Optional[str]` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: Optional[str]` The template ID for the single-sided plastic card. - `return_envelope: Optional[str]` The return envelope (ID) sent out with the letter, if any. - `template: Optional[str]` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploaded_pdf: Optional[str]` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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.letters.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "letter_123456", "object": "letter", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "us_letter", "doubleSided": true, "color": false, "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class", "envelope": "standard", "addressPlacement": "top_first_page", "html": "Content" } ] } ``` ## Get Letter `print_mail.letters.retrieve(strid) -> Letter` **get** `/print-mail/v1/letters/{id}` Retrieve a letter by ID. ### Parameters - `id: str` ### Returns - `class Letter: …` - `id: str` A unique ID prefixed with letter_ - `address_placement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: bool` Indicates if the letter is in color. - `created_at: datetime` The UTC time at which this resource was created. - `double_sided: bool` Indicates if the letter is double-sided. - `envelope: str` The envelope (ID) for the letter or the default `standard` envelope. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["letter"]` Always `letter`. - `"letter"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `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"` - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `pdf_workflow_run: Optional[str]` The ID of the PDF workflow run that created the letter, if any. - `perforated_page: Optional[Literal[1]]` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plastic_card: Optional[PlasticCard]` Model representing a plastic card. - `size: Literal["standard"]` Enum representing the size of the plastic card. - `"standard"` - `double_sided: Optional[DoubleSided]` Model representing a double-sided plastic card. - `back_html: Optional[str]` The HTML content for the back side of the double-sided plastic card. - `back_template: Optional[str]` The template ID for the back side of the double-sided plastic card. - `front_html: Optional[str]` The HTML content for the front side of the double-sided plastic card. - `front_template: Optional[str]` The template ID for the front side of the double-sided plastic card. - `pdf: Optional[str]` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `single_sided: Optional[SingleSided]` Model representing a single-sided plastic card. - `html: Optional[str]` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: Optional[str]` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: Optional[str]` The template ID for the single-sided plastic card. - `return_envelope: Optional[str]` The return envelope (ID) sent out with the letter, if any. - `template: Optional[str]` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploaded_pdf: Optional[str]` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) letter = client.print_mail.letters.retrieve( "id", ) print(letter.id) ``` #### Response ```json { "id": "letter_123456", "object": "letter", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "us_letter", "doubleSided": true, "color": false, "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class", "envelope": "standard", "addressPlacement": "top_first_page", "html": "Content" } ``` ## Cancel Letter `print_mail.letters.delete(strid) -> Letter` **delete** `/print-mail/v1/letters/{id}` Cancel a letter by ID. Note that this operation cannot be undone. ### Parameters - `id: str` ### Returns - `class Letter: …` - `id: str` A unique ID prefixed with letter_ - `address_placement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: bool` Indicates if the letter is in color. - `created_at: datetime` The UTC time at which this resource was created. - `double_sided: bool` Indicates if the letter is double-sided. - `envelope: str` The envelope (ID) for the letter or the default `standard` envelope. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["letter"]` Always `letter`. - `"letter"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `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"` - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `pdf_workflow_run: Optional[str]` The ID of the PDF workflow run that created the letter, if any. - `perforated_page: Optional[Literal[1]]` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plastic_card: Optional[PlasticCard]` Model representing a plastic card. - `size: Literal["standard"]` Enum representing the size of the plastic card. - `"standard"` - `double_sided: Optional[DoubleSided]` Model representing a double-sided plastic card. - `back_html: Optional[str]` The HTML content for the back side of the double-sided plastic card. - `back_template: Optional[str]` The template ID for the back side of the double-sided plastic card. - `front_html: Optional[str]` The HTML content for the front side of the double-sided plastic card. - `front_template: Optional[str]` The template ID for the front side of the double-sided plastic card. - `pdf: Optional[str]` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `single_sided: Optional[SingleSided]` Model representing a single-sided plastic card. - `html: Optional[str]` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: Optional[str]` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: Optional[str]` The template ID for the single-sided plastic card. - `return_envelope: Optional[str]` The return envelope (ID) sent out with the letter, if any. - `template: Optional[str]` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploaded_pdf: Optional[str]` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) letter = client.print_mail.letters.delete( "id", ) print(letter.id) ``` #### Response ```json { "id": "letter_123456", "object": "letter", "status": "cancelled", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "us_letter", "doubleSided": true, "color": false, "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class", "envelope": "standard", "addressPlacement": "top_first_page", "html": "Content" } ``` ## Get Letter Preview `print_mail.letters.retrieve_url(strid) -> LetterRetrieveURLResponse` **get** `/print-mail/v1/letters/{id}/url` Retrieve a letter preview URL. This is only available for customers with our document management addon, which offers document generation and hosting capabilities. This endpoint has a much higher rate limit than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases. ### Parameters - `id: str` ### Returns - `class LetterRetrieveURLResponse: …` - `id: str` A unique ID prefixed with letter_ - `object: str` - `url: str` A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call. ### 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 ) response = client.print_mail.letters.retrieve_url( "id", ) print(response.id) ``` #### Response ```json { "id": "letter_123456", "object": "letter_url", "url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/letter_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D" } ``` ## Domain Types ### Address Placement - `Literal["top_first_page", "insert_blank_page"]` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` ### Attached Pdf - `class 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"` ### Letter - `class Letter: …` - `id: str` A unique ID prefixed with letter_ - `address_placement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: bool` Indicates if the letter is in color. - `created_at: datetime` The UTC time at which this resource was created. - `double_sided: bool` Indicates if the letter is double-sided. - `envelope: str` The envelope (ID) for the letter or the default `standard` envelope. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["letter"]` Always `letter`. - `"letter"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `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"` - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `pdf_workflow_run: Optional[str]` The ID of the PDF workflow run that created the letter, if any. - `perforated_page: Optional[Literal[1]]` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plastic_card: Optional[PlasticCard]` Model representing a plastic card. - `size: Literal["standard"]` Enum representing the size of the plastic card. - `"standard"` - `double_sided: Optional[DoubleSided]` Model representing a double-sided plastic card. - `back_html: Optional[str]` The HTML content for the back side of the double-sided plastic card. - `back_template: Optional[str]` The template ID for the back side of the double-sided plastic card. - `front_html: Optional[str]` The HTML content for the front side of the double-sided plastic card. - `front_template: Optional[str]` The template ID for the front side of the double-sided plastic card. - `pdf: Optional[str]` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `single_sided: Optional[SingleSided]` Model representing a single-sided plastic card. - `html: Optional[str]` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: Optional[str]` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: Optional[str]` The template ID for the single-sided plastic card. - `return_envelope: Optional[str]` The return envelope (ID) sent out with the letter, if any. - `template: Optional[str]` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploaded_pdf: Optional[str]` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### Letter Size - `Literal["us_letter", "a4"]` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` ### Plastic Card - `class PlasticCard: …` Model representing a plastic card. - `size: Literal["standard"]` Enum representing the size of the plastic card. - `"standard"` - `double_sided: Optional[DoubleSided]` Model representing a double-sided plastic card. - `back_html: Optional[str]` The HTML content for the back side of the double-sided plastic card. - `back_template: Optional[str]` The template ID for the back side of the double-sided plastic card. - `front_html: Optional[str]` The HTML content for the front side of the double-sided plastic card. - `front_template: Optional[str]` The template ID for the front side of the double-sided plastic card. - `pdf: Optional[str]` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `single_sided: Optional[SingleSided]` Model representing a single-sided plastic card. - `html: Optional[str]` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: Optional[str]` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: Optional[str]` The template ID for the single-sided plastic card. # Mailing List Imports ## Create Mailing List Import `print_mail.mailing_list_imports.create(MailingListImportCreateParams**kwargs) -> MailingListImportResponse` **post** `/print-mail/v1/mailing_list_imports` Create a new mailing list import. Initiates the import process for a contact list file. The import enters the `validating` status while contacts are processed and verified. ### Parameters - `file: str` The CSV file for this import. - `file_type: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiver_address_mapping: Dict[str, str]` Mapping of columns for receiver addresses. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `receiver_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for receiver merge variables. - `sender_address_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender addresses. If this is present, then all receivers should have a corresponding sender. - `sender_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender merge variables. - `idempotency_key: Optional[str]` ### Returns - `class MailingListImportResponse: …` Read-only view of a MailingListImport - `id: str` A unique ID prefixed with mailing_list_import_ - `created_at: datetime` The UTC time at which this resource was created. - `errors: 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["no_valid_contacts_error", "multiple_countries_error", "invalid_contact_count_error", "internal_service_error"]` Type of error encountered during import processing. - `"no_valid_contacts_error"` - `"multiple_countries_error"` - `"invalid_contact_count_error"` - `"internal_service_error"` - `file: File` The file object your controller returns: all the mappings plus a signed URL. - `file_type: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiver_address_mapping: Dict[str, str]` Mapping of columns for receiver addresses. Contact fields to file columns. Possible Contact fields: - description - firstName - lastName - email - phoneNumber - companyName - addressLine1 - addressLine2 - jobTitle - city - postalOrZip - provinceOrState - countryCode - `url: str` The signed URL your controller generates. - `receiver_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for receiver merge variables. - `sender_address_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender addresses. - `sender_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender merge variables. - `invalid_row_count: int` Number of invalid rows found in the file. - `live: bool` `true` if this is a live mode resource else `false`. - `notes: List[Note]` Additional notes about the import process. - `message: str` A human-readable message describing the note. - `type: Literal["truncated_test_file", "skipped_invalid_contacts"]` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: str` The organization that owns this import. - `receiver_status_count: VerificationStatusCount` Count of contact verification statuses. - `corrected_count: int` Number of contacts that were corrected during verification. - `failed_count: int` Number of contacts that failed verification. - `verified_count: int` Number of contacts that were verified without changes. - `status: Literal["validating", "completed", "changes_required"]` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `valid_row_count: int` Number of valid rows processed from the file. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `report_url: Optional[str]` A temporary URL to download the processing report, available once the import is completed. - `sender_status_count: Optional[VerificationStatusCount]` Count of contact verification statuses. ### 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 ) mailing_list_import_response = client.print_mail.mailing_list_imports.create( file="https://signed-upload-url.csv", file_type="csv", receiver_address_mapping={ "description": "Description", "firstName": "First Name", "lastName": "Last Name", "email": "Email", "addressLine1": "Address", "city": "City", "postalOrZip": "Postal Code", "provinceOrState": "State", "countryCode": "Country", }, ) print(mailing_list_import_response.id) ``` #### Response ```json { "id": "mailing_list_import_123", "live": false, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:05:00Z", "status": "completed", "reportURL": "https://signed-report-url.csv", "errors": [], "notes": [], "validRowCount": 100, "invalidRowCount": 0, "receiverStatusCount": { "verifiedCount": 100, "correctedCount": 0, "failedCount": 0 }, "senderStatusCount": { "verifiedCount": 100, "correctedCount": 0, "failedCount": 0 }, "organization": "org_123", "file": { "fileType": "csv", "receiverAddressMapping": { "description": "Description", "firstName": "First Name", "lastName": "Last Name", "email": "Email", "addressLine1": "Address", "addressLine2": "Address Line 2", "city": "City", "postalOrZip": "Postal Code", "provinceOrState": "Province", "countryCode": "Country" }, "url": "https://signed.url/import_123.csv" } } ``` ## List Mailing List Imports `print_mail.mailing_list_imports.list(MailingListImportListParams**kwargs) -> SyncSkipLimit[MailingListImportResponse]` **get** `/print-mail/v1/mailing_list_imports` Retrieve a list of mailing list imports. Returns a paginated list of imports 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 MailingListImportResponse: …` Read-only view of a MailingListImport - `id: str` A unique ID prefixed with mailing_list_import_ - `created_at: datetime` The UTC time at which this resource was created. - `errors: 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["no_valid_contacts_error", "multiple_countries_error", "invalid_contact_count_error", "internal_service_error"]` Type of error encountered during import processing. - `"no_valid_contacts_error"` - `"multiple_countries_error"` - `"invalid_contact_count_error"` - `"internal_service_error"` - `file: File` The file object your controller returns: all the mappings plus a signed URL. - `file_type: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiver_address_mapping: Dict[str, str]` Mapping of columns for receiver addresses. Contact fields to file columns. Possible Contact fields: - description - firstName - lastName - email - phoneNumber - companyName - addressLine1 - addressLine2 - jobTitle - city - postalOrZip - provinceOrState - countryCode - `url: str` The signed URL your controller generates. - `receiver_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for receiver merge variables. - `sender_address_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender addresses. - `sender_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender merge variables. - `invalid_row_count: int` Number of invalid rows found in the file. - `live: bool` `true` if this is a live mode resource else `false`. - `notes: List[Note]` Additional notes about the import process. - `message: str` A human-readable message describing the note. - `type: Literal["truncated_test_file", "skipped_invalid_contacts"]` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: str` The organization that owns this import. - `receiver_status_count: VerificationStatusCount` Count of contact verification statuses. - `corrected_count: int` Number of contacts that were corrected during verification. - `failed_count: int` Number of contacts that failed verification. - `verified_count: int` Number of contacts that were verified without changes. - `status: Literal["validating", "completed", "changes_required"]` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `valid_row_count: int` Number of valid rows processed from the file. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `report_url: Optional[str]` A temporary URL to download the processing report, available once the import is completed. - `sender_status_count: Optional[VerificationStatusCount]` Count of contact verification statuses. ### 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.mailing_list_imports.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "totalCount": 1, "skip": 0, "limit": 10, "data": [ { "id": "mailing_list_import_123", "live": false, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:05:00Z", "status": "completed", "reportURL": "https://signed-report-url.csv", "errors": [], "notes": [], "validRowCount": 100, "invalidRowCount": 0, "receiverStatusCount": { "verifiedCount": 100, "correctedCount": 0, "failedCount": 0 }, "senderStatusCount": { "verifiedCount": 100, "correctedCount": 0, "failedCount": 0 }, "organization": "org_123", "file": { "fileType": "csv", "receiverAddressMapping": { "description": "Description", "firstName": "First Name", "lastName": "Last Name", "email": "Email", "addressLine1": "Address", "addressLine2": "Address Line 2", "city": "City", "postalOrZip": "Postal Code", "provinceOrState": "Province", "countryCode": "Country" }, "url": "https://signed.url/import_123.csv" } } ] } ``` ## Update Mailing List Import `print_mail.mailing_list_imports.update(strid, MailingListImportUpdateParams**kwargs) -> MailingListImportResponse` **post** `/print-mail/v1/mailing_list_imports/{id}` Update an existing mailing list import. ### Parameters - `id: str` - `description: Optional[str]` An optional description for the import. Set to `null` to remove the existing description. - `metadata: Optional[Dict[str, str]]` Optional key-value data associated with the import. Set to `null` to remove existing metadata. ### Returns - `class MailingListImportResponse: …` Read-only view of a MailingListImport - `id: str` A unique ID prefixed with mailing_list_import_ - `created_at: datetime` The UTC time at which this resource was created. - `errors: 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["no_valid_contacts_error", "multiple_countries_error", "invalid_contact_count_error", "internal_service_error"]` Type of error encountered during import processing. - `"no_valid_contacts_error"` - `"multiple_countries_error"` - `"invalid_contact_count_error"` - `"internal_service_error"` - `file: File` The file object your controller returns: all the mappings plus a signed URL. - `file_type: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiver_address_mapping: Dict[str, str]` Mapping of columns for receiver addresses. Contact fields to file columns. Possible Contact fields: - description - firstName - lastName - email - phoneNumber - companyName - addressLine1 - addressLine2 - jobTitle - city - postalOrZip - provinceOrState - countryCode - `url: str` The signed URL your controller generates. - `receiver_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for receiver merge variables. - `sender_address_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender addresses. - `sender_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender merge variables. - `invalid_row_count: int` Number of invalid rows found in the file. - `live: bool` `true` if this is a live mode resource else `false`. - `notes: List[Note]` Additional notes about the import process. - `message: str` A human-readable message describing the note. - `type: Literal["truncated_test_file", "skipped_invalid_contacts"]` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: str` The organization that owns this import. - `receiver_status_count: VerificationStatusCount` Count of contact verification statuses. - `corrected_count: int` Number of contacts that were corrected during verification. - `failed_count: int` Number of contacts that failed verification. - `verified_count: int` Number of contacts that were verified without changes. - `status: Literal["validating", "completed", "changes_required"]` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `valid_row_count: int` Number of valid rows processed from the file. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `report_url: Optional[str]` A temporary URL to download the processing report, available once the import is completed. - `sender_status_count: Optional[VerificationStatusCount]` Count of contact verification statuses. ### 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 ) mailing_list_import_response = client.print_mail.mailing_list_imports.update( id="id", description="Corrected description", metadata={ "batch": "spring_sale" }, ) print(mailing_list_import_response.id) ``` #### Response ```json { "id": "mailing_list_import_123", "live": false, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:05:00Z", "status": "completed", "reportURL": "https://signed-report-url.csv", "errors": [], "notes": [], "validRowCount": 100, "invalidRowCount": 0, "receiverStatusCount": { "verifiedCount": 100, "correctedCount": 0, "failedCount": 0 }, "senderStatusCount": { "verifiedCount": 100, "correctedCount": 0, "failedCount": 0 }, "organization": "org_123", "file": { "fileType": "csv", "receiverAddressMapping": { "description": "Description", "firstName": "First Name", "lastName": "Last Name", "email": "Email", "addressLine1": "Address", "addressLine2": "Address Line 2", "city": "City", "postalOrZip": "Postal Code", "provinceOrState": "Province", "countryCode": "Country" }, "url": "https://signed.url/import_123.csv" } } ``` ## Get Mailing List Import `print_mail.mailing_list_imports.retrieve(strid) -> MailingListImportResponse` **get** `/print-mail/v1/mailing_list_imports/{id}` Retrieve a specific mailing list import by its ID. ### Parameters - `id: str` ### Returns - `class MailingListImportResponse: …` Read-only view of a MailingListImport - `id: str` A unique ID prefixed with mailing_list_import_ - `created_at: datetime` The UTC time at which this resource was created. - `errors: 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["no_valid_contacts_error", "multiple_countries_error", "invalid_contact_count_error", "internal_service_error"]` Type of error encountered during import processing. - `"no_valid_contacts_error"` - `"multiple_countries_error"` - `"invalid_contact_count_error"` - `"internal_service_error"` - `file: File` The file object your controller returns: all the mappings plus a signed URL. - `file_type: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiver_address_mapping: Dict[str, str]` Mapping of columns for receiver addresses. Contact fields to file columns. Possible Contact fields: - description - firstName - lastName - email - phoneNumber - companyName - addressLine1 - addressLine2 - jobTitle - city - postalOrZip - provinceOrState - countryCode - `url: str` The signed URL your controller generates. - `receiver_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for receiver merge variables. - `sender_address_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender addresses. - `sender_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender merge variables. - `invalid_row_count: int` Number of invalid rows found in the file. - `live: bool` `true` if this is a live mode resource else `false`. - `notes: List[Note]` Additional notes about the import process. - `message: str` A human-readable message describing the note. - `type: Literal["truncated_test_file", "skipped_invalid_contacts"]` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: str` The organization that owns this import. - `receiver_status_count: VerificationStatusCount` Count of contact verification statuses. - `corrected_count: int` Number of contacts that were corrected during verification. - `failed_count: int` Number of contacts that failed verification. - `verified_count: int` Number of contacts that were verified without changes. - `status: Literal["validating", "completed", "changes_required"]` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `valid_row_count: int` Number of valid rows processed from the file. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `report_url: Optional[str]` A temporary URL to download the processing report, available once the import is completed. - `sender_status_count: Optional[VerificationStatusCount]` Count of contact verification statuses. ### 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 ) mailing_list_import_response = client.print_mail.mailing_list_imports.retrieve( "id", ) print(mailing_list_import_response.id) ``` #### Response ```json { "id": "mailing_list_import_123", "live": false, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:05:00Z", "status": "completed", "reportURL": "https://signed-report-url.csv", "errors": [], "notes": [], "validRowCount": 100, "invalidRowCount": 0, "receiverStatusCount": { "verifiedCount": 100, "correctedCount": 0, "failedCount": 0 }, "senderStatusCount": { "verifiedCount": 100, "correctedCount": 0, "failedCount": 0 }, "organization": "org_123", "file": { "fileType": "csv", "receiverAddressMapping": { "description": "Description", "firstName": "First Name", "lastName": "Last Name", "email": "Email", "addressLine1": "Address", "addressLine2": "Address Line 2", "city": "City", "postalOrZip": "Postal Code", "provinceOrState": "Province", "countryCode": "Country" }, "url": "https://signed.url/import_123.csv" } } ``` ## Delete Mailing List Import `print_mail.mailing_list_imports.delete(strid) -> MailingListImportDeleteResponse` **delete** `/print-mail/v1/mailing_list_imports/{id}` Delete a mailing list import. This permanently deletes the import and its associated resources. This operation cannot be undone. ### Parameters - `id: str` ### Returns - `class MailingListImportDeleteResponse: …` - `id: str` A unique ID prefixed with mailing_list_import_ - `deleted: Literal[true]` - `true` ### 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 ) mailing_list_import = client.print_mail.mailing_list_imports.delete( "id", ) print(mailing_list_import.id) ``` #### Response ```json { "id": "mailing_list_import_123", "deleted": true } ``` ## Domain Types ### File Type - `Literal["csv"]` Type of file supported for mailing list imports. - `"csv"` ### Mailing List Import Response - `class MailingListImportResponse: …` Read-only view of a MailingListImport - `id: str` A unique ID prefixed with mailing_list_import_ - `created_at: datetime` The UTC time at which this resource was created. - `errors: 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["no_valid_contacts_error", "multiple_countries_error", "invalid_contact_count_error", "internal_service_error"]` Type of error encountered during import processing. - `"no_valid_contacts_error"` - `"multiple_countries_error"` - `"invalid_contact_count_error"` - `"internal_service_error"` - `file: File` The file object your controller returns: all the mappings plus a signed URL. - `file_type: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiver_address_mapping: Dict[str, str]` Mapping of columns for receiver addresses. Contact fields to file columns. Possible Contact fields: - description - firstName - lastName - email - phoneNumber - companyName - addressLine1 - addressLine2 - jobTitle - city - postalOrZip - provinceOrState - countryCode - `url: str` The signed URL your controller generates. - `receiver_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for receiver merge variables. - `sender_address_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender addresses. - `sender_merge_variable_mapping: Optional[Dict[str, str]]` Optional mapping of columns for sender merge variables. - `invalid_row_count: int` Number of invalid rows found in the file. - `live: bool` `true` if this is a live mode resource else `false`. - `notes: List[Note]` Additional notes about the import process. - `message: str` A human-readable message describing the note. - `type: Literal["truncated_test_file", "skipped_invalid_contacts"]` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: str` The organization that owns this import. - `receiver_status_count: VerificationStatusCount` Count of contact verification statuses. - `corrected_count: int` Number of contacts that were corrected during verification. - `failed_count: int` Number of contacts that failed verification. - `verified_count: int` Number of contacts that were verified without changes. - `status: Literal["validating", "completed", "changes_required"]` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `valid_row_count: int` Number of valid rows processed from the file. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `report_url: Optional[str]` A temporary URL to download the processing report, available once the import is completed. - `sender_status_count: Optional[VerificationStatusCount]` Count of contact verification statuses. ### Verification Status Count - `class VerificationStatusCount: …` Count of contact verification statuses. - `corrected_count: int` Number of contacts that were corrected during verification. - `failed_count: int` Number of contacts that failed verification. - `verified_count: int` Number of contacts that were verified without changes. # Mailing Lists ## Create Mailing List `print_mail.mailing_lists.create(MailingListCreateParams**kwargs) -> MailingList` **post** `/print-mail/v1/mailing_lists` Create a new mailing list. ### Parameters - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `idempotency_key: Optional[str]` ### Returns - `class MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `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. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "internal_service_error"]` Type of error encountered during mailing list processing. - `"mailing_list_imports_not_found_error"` - `"download_file_error"` - `"operational_error"` - `"internal_service_error"` - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### 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 ) mailing_list = client.print_mail.mailing_lists.create( description="Test Mailing List", metadata={ "campaign": "launch" }, ) print(mailing_list.id) ``` #### Response ```json { "id": "mailing_list_123", "live": false, "description": "Test Mailing List", "metadata": { "campaign": "launch" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z", "status": "completed", "errors": [] } ``` ## List Mailing Lists `print_mail.mailing_lists.list(MailingListListParams**kwargs) -> SyncSkipLimit[MailingList]` **get** `/print-mail/v1/mailing_lists` Retrieve a list of mailing lists. Returns a paginated list of mailing lists 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 MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `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. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "internal_service_error"]` Type of error encountered during mailing list processing. - `"mailing_list_imports_not_found_error"` - `"download_file_error"` - `"operational_error"` - `"internal_service_error"` - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### 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.mailing_lists.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "totalCount": 1, "skip": 0, "limit": 10, "data": [ { "id": "mailing_list_123", "live": false, "description": "Test Mailing List", "metadata": { "campaign": "launch" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z", "status": "completed", "errors": [] } ] } ``` ## Get Mailing List `print_mail.mailing_lists.retrieve(strid) -> MailingList` **get** `/print-mail/v1/mailing_lists/{id}` Retrieve a specific mailing list by its ID. ### Parameters - `id: str` ### Returns - `class MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `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. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "internal_service_error"]` Type of error encountered during mailing list processing. - `"mailing_list_imports_not_found_error"` - `"download_file_error"` - `"operational_error"` - `"internal_service_error"` - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### 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 ) mailing_list = client.print_mail.mailing_lists.retrieve( "id", ) print(mailing_list.id) ``` #### Response ```json { "id": "mailing_list_123", "live": false, "description": "Test Mailing List", "metadata": { "campaign": "launch" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z", "status": "completed", "errors": [] } ``` ## Update Mailing List `print_mail.mailing_lists.update(strid, MailingListUpdateParams**kwargs) -> MailingListUpdate` **post** `/print-mail/v1/mailing_lists/{id}` Update an existing mailing list. ### Parameters - `id: str` - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Returns - `class MailingListUpdate: …` Parameters for updating an existing mailing list. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### 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 ) mailing_list_update = client.print_mail.mailing_lists.update( id="id", description="Updated Mailing List Description", ) print(mailing_list_update.description) ``` #### Response ```json { "description": "Test Mailing List", "metadata": { "campaign": "launch" } } ``` ## Delete Mailing List `print_mail.mailing_lists.delete(strid) -> MailingListDeleteResponse` **delete** `/print-mail/v1/mailing_lists/{id}` Delete a mailing list. This permanently deletes the mailing list and its associations. This operation cannot be undone. ### Parameters - `id: str` ### Returns - `class MailingListDeleteResponse: …` - `id: str` A unique ID prefixed with mailing_list_ - `deleted: Literal[true]` - `true` ### 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 ) mailing_list = client.print_mail.mailing_lists.delete( "id", ) print(mailing_list.id) ``` #### Response ```json { "id": "mailing_list_sqF12lZ1VlBb", "deleted": true } ``` ## Submit a Mailing List Job `print_mail.mailing_lists.jobs(strid, MailingListJobsParams**kwargs) -> MailingList` **post** `/print-mail/v1/mailing_lists/{id}/jobs` Runs a mailing list job. Mailing list jobs allow you to add or remove contacts to your mailing list from mailing list imports or directly with contact IDs. Only one job can be ran at a time and jobs are only able to be ran while the mailing list has a `status` of "completed". Once a job as successfully been kicked off, the mailing list will have a `status` of either `creating_contacts` or `removing_contacts` depending on which job was ran. After the job has finished, the mailing list will go back into the `completed` state where more jobs can be ran. If there are any errors while running a job, the `errors` field on the mailing list will contain a list of error objects which describe the errors. ### Parameters - `id: str` - `add_contacts: Optional[SequenceNotStr[str]]` List of contact IDs to add to the mailing list. Cannot be used with other operations. - `add_mailing_list_imports: Optional[SequenceNotStr[str]]` List of mailing list import IDs to add to the mailing list. Cannot be used with other operations. - `remove_contacts: Optional[SequenceNotStr[str]]` List of contact IDs to remove from the mailing list. Cannot be used with other operations. - `remove_mailing_list_imports: Optional[SequenceNotStr[str]]` List of mailing list import IDs to remove from the mailing list. Cannot be used with other operations. ### Returns - `class MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `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. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "internal_service_error"]` Type of error encountered during mailing list processing. - `"mailing_list_imports_not_found_error"` - `"download_file_error"` - `"operational_error"` - `"internal_service_error"` - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### 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 ) mailing_list = client.print_mail.mailing_lists.jobs( id="id", remove_mailing_list_imports=["mailing_list_import_123", "mailing_list_import_456"], ) print(mailing_list.id) ``` #### Response ```json { "id": "mailing_list_123", "live": false, "description": "Test Mailing List", "metadata": { "campaign": "launch" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z", "status": "completed", "errors": [] } ``` ## Domain Types ### Mailing List - `class MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `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. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "internal_service_error"]` Type of error encountered during mailing list processing. - `"mailing_list_imports_not_found_error"` - `"download_file_error"` - `"operational_error"` - `"internal_service_error"` - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Mailing List Update - `class MailingListUpdate: …` Parameters for updating an existing mailing list. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. # Order Profiles # Cheques ## Create Cheque Profile `print_mail.order_profiles.cheques.create(ChequeCreateParams**kwargs) -> ChequeProfile` **post** `/print-mail/v1/order_profiles/cheques` Creates a new Cheque Profile. Requires a `bankAccount` ID. Can optionally include an attached letter via `letterHTML`, `letterTemplate`, or `letterPDF`. If providing `letterPDF` or `logo` (if logo needs upload, though schema suggests URL), use `multipart/form-data`. ### Parameters - `bank_account: str` ID of the bank account to use for the cheque. Required for creation. - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. - `currency_code: Optional[CurrencyCode]` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `letter_pdf: Optional[Union[str, Base64FileInput]]` PDF file for an optional attached letter. Cannot be used with `letterHTML` or `letterTemplate`. Input only. - `letter_template: Optional[str]` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `logo: Optional[str]` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. Generally must be first class (or equivalent for destination country) for cheques. - `"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. Set to `null` to remove during update. - `merge_variables: Optional[Dict[str, object]]` Default merge variables for orders created using this profile. - `message: Optional[str]` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. ### Returns - `class ChequeProfile: …` - `id: str` Unique identifier for the order profile. - `bank_account: str` ID of the bank account to use for the cheque. Required for creation. - `created_at: datetime` Timestamp when the profile was created. - `currency_code: CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["cheque_profile"]` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `letter_template: Optional[str]` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letter_uploaded_pdf: Optional[str]` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: Optional[str]` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. Generally must be first class (or equivalent for destination country) for cheques. - `"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. Set to `null` to remove during update. - `merge_variables: Optional[Dict[str, object]]` Default merge variables for orders created using this profile. - `message: Optional[str]` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. ### 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 ) cheque_profile = client.print_mail.order_profiles.cheques.create( bank_account="bankAccount", size="us_letter", ) print(cheque_profile.id) ``` #### Response ```json { "id": "cheque_profile_789", "object": "cheque_profile", "live": true, "description": "Vendor Payment Profile", "size": "us_letter", "bankAccount": "bank_acct_xyz", "currencyCode": "USD", "memo": "Invoice #12345", "mailingClass": "first_class", "createdAt": "2023-03-20T12:00:00Z", "updatedAt": "2023-03-20T12:00:00Z" } ``` ## List Cheque Profiles `print_mail.order_profiles.cheques.list(ChequeListParams**kwargs) -> SyncSkipLimit[ChequeListResponse]` **get** `/print-mail/v1/order_profiles/cheques` Retrieves a list of Cheque Profiles. ### 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 ChequeListResponse: …` - `id: str` Unique identifier for the order profile. - `bank_account: str` ID of the bank account to use for the cheque. Required for creation. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["cheque_profile"]` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `letter_template: Optional[str]` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letter_uploaded_pdf: Optional[str]` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: Optional[str]` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. Generally must be first class (or equivalent for destination country) for cheques. - `"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. Set to `null` to remove during update. - `merge_variables: Optional[Dict[str, object]]` Default merge variables for orders created using this profile. - `message: Optional[str]` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. ### 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.order_profiles.cheques.list() page = page.data[0] print(page.id) ``` #### Response ```json { "data": [ { "id": "cheque_profile_789", "object": "cheque_profile", "live": true, "description": "Vendor Payment Profile", "size": "us_letter", "bankAccount": "bank_acct_xyz", "currencyCode": "USD", "memo": "Invoice #12345", "mailingClass": "first_class", "createdAt": "2023-03-20T12:00:00Z", "updatedAt": "2023-03-20T12:00:00Z" } ], "object": "list", "totalCount": 1, "limit": 1, "skip": 0 } ``` ## Retrieve Cheque Profile `print_mail.order_profiles.cheques.retrieve(strid, ChequeRetrieveParams**kwargs) -> ChequeProfile` **get** `/print-mail/v1/order_profiles/cheques/{id}` Retrieves the details of a specific Cheque Profile. ### Parameters - `id: str` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. ### Returns - `class ChequeProfile: …` - `id: str` Unique identifier for the order profile. - `bank_account: str` ID of the bank account to use for the cheque. Required for creation. - `created_at: datetime` Timestamp when the profile was created. - `currency_code: CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["cheque_profile"]` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `letter_template: Optional[str]` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letter_uploaded_pdf: Optional[str]` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: Optional[str]` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. Generally must be first class (or equivalent for destination country) for cheques. - `"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. Set to `null` to remove during update. - `merge_variables: Optional[Dict[str, object]]` Default merge variables for orders created using this profile. - `message: Optional[str]` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. ### 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 ) cheque_profile = client.print_mail.order_profiles.cheques.retrieve( id="id", ) print(cheque_profile.id) ``` #### Response ```json { "id": "cheque_profile_789", "object": "cheque_profile", "live": true, "description": "Vendor Payment Profile", "size": "us_letter", "bankAccount": "bank_acct_xyz", "currencyCode": "USD", "memo": "Invoice #12345", "mailingClass": "first_class", "createdAt": "2023-03-20T12:00:00Z", "updatedAt": "2023-03-20T12:00:00Z" } ``` ## Update Cheque Profile `print_mail.order_profiles.cheques.update(strid, ChequeUpdateParams**kwargs) -> ChequeProfile` **post** `/print-mail/v1/order_profiles/cheques/{id}` Updates specific fields of an existing Cheque Profile. If providing `letterPDF` or `logo`, use `multipart/form-data`. ### Parameters - `id: str` - `bank_account: str` ID of the bank account to use for the cheque. Required for creation. - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. - `currency_code: Optional[CurrencyCode]` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `letter_pdf: Optional[Union[str, Base64FileInput]]` PDF file for an optional attached letter. Cannot be used with `letterHTML` or `letterTemplate`. Input only. - `letter_template: Optional[str]` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `logo: Optional[str]` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. Generally must be first class (or equivalent for destination country) for cheques. - `"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. Set to `null` to remove during update. - `merge_variables: Optional[Dict[str, object]]` Default merge variables for orders created using this profile. - `message: Optional[str]` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. ### Returns - `class ChequeProfile: …` - `id: str` Unique identifier for the order profile. - `bank_account: str` ID of the bank account to use for the cheque. Required for creation. - `created_at: datetime` Timestamp when the profile was created. - `currency_code: CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["cheque_profile"]` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `letter_template: Optional[str]` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letter_uploaded_pdf: Optional[str]` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: Optional[str]` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. Generally must be first class (or equivalent for destination country) for cheques. - `"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. Set to `null` to remove during update. - `merge_variables: Optional[Dict[str, object]]` Default merge variables for orders created using this profile. - `message: Optional[str]` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. ### 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 ) cheque_profile = client.print_mail.order_profiles.cheques.update( id="id", bank_account="bankAccount", size="us_letter", ) print(cheque_profile.id) ``` #### Response ```json { "id": "cheque_profile_789", "object": "cheque_profile", "live": true, "description": "Vendor Payment Profile", "size": "us_letter", "bankAccount": "bank_acct_xyz", "currencyCode": "USD", "memo": "Invoice #12345", "mailingClass": "first_class", "createdAt": "2023-03-20T12:00:00Z", "updatedAt": "2023-03-20T12:00:00Z" } ``` ## Delete Cheque Profile `print_mail.order_profiles.cheques.delete(strid) -> ChequeDeleteResponse` **delete** `/print-mail/v1/order_profiles/cheques/{id}` Deletes a Cheque Profile. ### Parameters - `id: str` ### Returns - `class ChequeDeleteResponse: …` - `id: str` Unique identifier for the order profile. - `deleted: Literal[true]` - `true` - `object: Literal["cheque_profile"]` Always `cheque_profile`. - `"cheque_profile"` ### 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 ) cheque = client.print_mail.order_profiles.cheques.delete( "id", ) print(cheque.id) ``` #### Response ```json { "id": "cheque_profile_789", "object": "cheque_profile", "deleted": true } ``` ## Domain Types ### Cheque Profile - `class ChequeProfile: …` - `id: str` Unique identifier for the order profile. - `bank_account: str` ID of the bank account to use for the cheque. Required for creation. - `created_at: datetime` Timestamp when the profile was created. - `currency_code: CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["cheque_profile"]` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `letter_template: Optional[str]` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letter_uploaded_pdf: Optional[str]` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: Optional[str]` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. Generally must be first class (or equivalent for destination country) for cheques. - `"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. Set to `null` to remove during update. - `merge_variables: Optional[Dict[str, object]]` Default merge variables for orders created using this profile. - `message: Optional[str]` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. ### Currency Code - `Literal["CAD", "USD"]` Enum representing the supported currency codes. - `"CAD"` - `"USD"` # Letters ## Create Letter Profile `print_mail.order_profiles.letters.create(LetterCreateParams**kwargs) -> LetterProfile` **post** `/print-mail/v1/order_profiles/letters` Creates a new Letter Profile. You must provide either a `template` ID or upload a `pdf` file for the content. If providing PDF files (`pdf` or `attachedPDFFile`), the request `Content-Type` must be `multipart/form-data`. ### Parameters - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. - `address_placement: Optional[AddressPlacement]` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attached_pdf: Optional[AttachedPdfParam]` 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]` Specifies whether to print in color (true) or black and white (false). - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `double_sided: Optional[bool]` Specifies whether to print on both sides of the paper. - `envelope: Optional[str]` ID of a custom envelope to use. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `pdf: Optional[str]` A PDF file containing the letter content. Cannot be used with `template`. - `perforated_page: Optional[Literal[1]]` Specifies which page number should be perforated (if any). - `1` - `return_envelope: Optional[str]` ID of a return envelope to include. - `template: Optional[str]` ID of a template to use for the letter content. Cannot be used with `pdf`. ### Returns - `class LetterProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["letter_profile"]` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updated_at: datetime` Timestamp when the profile was last updated. - `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]` Specifies whether to print in color (true) or black and white (false). - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `double_sided: Optional[bool]` Specifies whether to print on both sides of the paper. - `envelope: Optional[str]` ID of a custom envelope to use. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `perforated_page: Optional[Literal[1]]` Specifies which page number should be perforated (if any). - `1` - `template: Optional[str]` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view 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 ) letter_profile = client.print_mail.order_profiles.letters.create( size="us_letter", color=True, description="Monthly Newsletter Profile", mailing_class="first_class", merge_variables={ "salutation": "Valued Customer" }, metadata={ "campaign": "Q1 Newsletter" }, template="template_abc", ) print(letter_profile.id) ``` #### Response ```json { "id": "letter_profile_123", "object": "letter_profile", "live": false, "description": "Monthly Newsletter Profile", "metadata": { "campaign": "Q1 Newsletter" }, "mailingClass": "first_class", "mergeVariables": { "salutation": "Valued Customer" }, "size": "us_letter", "color": true, "doubleSided": true, "envelope": "standard", "addressPlacement": "top_first_page", "template": "template_123", "createdAt": "2023-01-10T10:00:00Z", "updatedAt": "2023-01-10T10:00:00Z" } ``` ## List Letter Profiles `print_mail.order_profiles.letters.list(LetterListParams**kwargs) -> SyncSkipLimit[LetterProfile]` **get** `/print-mail/v1/order_profiles/letters` Retrieves a list of Letter Profiles. The profiles are returned sorted by creation date, with the most recent appearing first. ### 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 LetterProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["letter_profile"]` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updated_at: datetime` Timestamp when the profile was last updated. - `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]` Specifies whether to print in color (true) or black and white (false). - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `double_sided: Optional[bool]` Specifies whether to print on both sides of the paper. - `envelope: Optional[str]` ID of a custom envelope to use. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `perforated_page: Optional[Literal[1]]` Specifies which page number should be perforated (if any). - `1` - `template: Optional[str]` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view 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.order_profiles.letters.list() page = page.data[0] print(page.id) ``` #### Response ```json { "data": [ { "id": "letter_profile_123", "object": "letter_profile", "live": false, "description": "Monthly Newsletter Profile", "metadata": { "campaign": "Q1 Newsletter" }, "mailingClass": "first_class", "mergeVariables": { "salutation": "Valued Customer" }, "size": "us_letter", "color": true, "doubleSided": true, "envelope": "standard", "addressPlacement": "top_first_page", "template": "template_123", "createdAt": "2023-01-10T10:00:00Z", "updatedAt": "2023-01-10T10:00:00Z" } ], "object": "list", "totalCount": 1, "limit": 1, "skip": 0 } ``` ## Retrieve Letter Profile `print_mail.order_profiles.letters.retrieve(strid, LetterRetrieveParams**kwargs) -> LetterProfile` **get** `/print-mail/v1/order_profiles/letters/{id}` Retrieves the details of a specific Letter Profile by its ID. ### Parameters - `id: str` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. ### Returns - `class LetterProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["letter_profile"]` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updated_at: datetime` Timestamp when the profile was last updated. - `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]` Specifies whether to print in color (true) or black and white (false). - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `double_sided: Optional[bool]` Specifies whether to print on both sides of the paper. - `envelope: Optional[str]` ID of a custom envelope to use. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `perforated_page: Optional[Literal[1]]` Specifies which page number should be perforated (if any). - `1` - `template: Optional[str]` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view 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 ) letter_profile = client.print_mail.order_profiles.letters.retrieve( id="id", ) print(letter_profile.id) ``` #### Response ```json { "id": "letter_profile_123", "object": "letter_profile", "live": false, "description": "Monthly Newsletter Profile", "metadata": { "campaign": "Q1 Newsletter" }, "mailingClass": "first_class", "mergeVariables": { "salutation": "Valued Customer" }, "size": "us_letter", "color": true, "doubleSided": true, "envelope": "standard", "addressPlacement": "top_first_page", "template": "template_123", "createdAt": "2023-01-10T10:00:00Z", "updatedAt": "2023-01-10T10:00:00Z" } ``` ## Update Letter Profile `print_mail.order_profiles.letters.update(strid, LetterUpdateParams**kwargs) -> LetterProfile` **post** `/print-mail/v1/order_profiles/letters/{id}` Updates specific fields of an existing Letter Profile. Only the fields provided in the request body will be updated. If providing PDF files (`pdf` or `attachedPDFFile`), the request `Content-Type` must be `multipart/form-data`. ### Parameters - `id: str` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. - `address_placement: Optional[AddressPlacement]` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attached_pdf: Optional[AttachedPdfParam]` 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]` Specifies whether to print in color (true) or black and white (false). - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `double_sided: Optional[bool]` Specifies whether to print on both sides of the paper. - `envelope: Optional[str]` ID of a custom envelope to use. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `pdf: Optional[str]` A PDF file containing the letter content. Cannot be used with `template`. - `perforated_page: Optional[Literal[1]]` Specifies which page number should be perforated (if any). - `1` - `return_envelope: Optional[str]` ID of a return envelope to include. - `template: Optional[str]` ID of a template to use for the letter content. Cannot be used with `pdf`. ### Returns - `class LetterProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["letter_profile"]` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updated_at: datetime` Timestamp when the profile was last updated. - `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]` Specifies whether to print in color (true) or black and white (false). - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `double_sided: Optional[bool]` Specifies whether to print on both sides of the paper. - `envelope: Optional[str]` ID of a custom envelope to use. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `perforated_page: Optional[Literal[1]]` Specifies which page number should be perforated (if any). - `1` - `template: Optional[str]` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view 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 ) letter_profile = client.print_mail.order_profiles.letters.update( id="id", color=False, description="Updated Newsletter Profile", ) print(letter_profile.id) ``` #### Response ```json { "id": "letter_profile_123", "object": "letter_profile", "live": false, "description": "Monthly Newsletter Profile", "metadata": { "campaign": "Q1 Newsletter" }, "mailingClass": "first_class", "mergeVariables": { "salutation": "Valued Customer" }, "size": "us_letter", "color": true, "doubleSided": true, "envelope": "standard", "addressPlacement": "top_first_page", "template": "template_123", "createdAt": "2023-01-10T10:00:00Z", "updatedAt": "2023-01-10T10:00:00Z" } ``` ## Delete Letter Profile `print_mail.order_profiles.letters.delete(strid) -> LetterDeleteResponse` **delete** `/print-mail/v1/order_profiles/letters/{id}` Deletes a Letter Profile. This action cannot be undone. Orders previously created using this profile are not affected. ### Parameters - `id: str` ### Returns - `class LetterDeleteResponse: …` - `id: str` Unique identifier for the order profile. - `deleted: Literal[true]` - `true` - `object: Literal["letter_profile"]` Always `letter_profile`. - `"letter_profile"` ### 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 ) letter = client.print_mail.order_profiles.letters.delete( "id", ) print(letter.id) ``` #### Response ```json { "id": "letter_profile_123", "object": "letter_profile", "deleted": true } ``` ## Domain Types ### Letter Profile - `class LetterProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["letter_profile"]` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updated_at: datetime` Timestamp when the profile was last updated. - `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]` Specifies whether to print in color (true) or black and white (false). - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `double_sided: Optional[bool]` Specifies whether to print on both sides of the paper. - `envelope: Optional[str]` ID of a custom envelope to use. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class. - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `perforated_page: Optional[Literal[1]]` Specifies which page number should be perforated (if any). - `1` - `template: Optional[str]` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view the uploaded PDF, if any. # Postcards ## Create Postcard Profile `print_mail.order_profiles.postcards.create(PostcardCreateParams**kwargs) -> PostcardProfile` **post** `/print-mail/v1/order_profiles/postcards` Creates a new Postcard Profile. Provide either `frontTemplate` and `backTemplate` IDs, or upload a 2-page `pdf`. If providing a `pdf`, the request `Content-Type` must be `multipart/form-data`. ### Parameters - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. - `back_template: Optional[str]` ID of the template for the back side. Required unless `pdf` is provided. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `front_template: Optional[str]` ID of the template for the front side. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services like `certified` or `registered` for postcards, though). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `pdf: Optional[str]` A 2-page PDF file containing the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`. ### Returns - `class PostcardProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["postcard_profile"]` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updated_at: datetime` Timestamp when the profile was last updated. - `back_template: Optional[str]` ID of the template for the back side. Required unless `pdf` is provided. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `front_template: Optional[str]` ID of the template for the front side. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services like `certified` or `registered` for postcards, though). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view the uploaded PDF content, 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 ) postcard_profile = client.print_mail.order_profiles.postcards.create( size="6x4", ) print(postcard_profile.id) ``` #### Response ```json { "id": "postcard_profile_456", "object": "postcard_profile", "live": false, "description": "Promo Postcard", "size": "6x4", "frontTemplate": "template_abc", "backTemplate": "template_abc", "mailingClass": "standard_class", "createdAt": "2023-02-15T11:00:00Z", "updatedAt": "2023-02-15T11:00:00Z" } ``` ## List Postcard Profiles `print_mail.order_profiles.postcards.list(PostcardListParams**kwargs) -> SyncSkipLimit[PostcardProfile]` **get** `/print-mail/v1/order_profiles/postcards` Retrieves a list of Postcard Profiles. ### 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 PostcardProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["postcard_profile"]` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updated_at: datetime` Timestamp when the profile was last updated. - `back_template: Optional[str]` ID of the template for the back side. Required unless `pdf` is provided. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `front_template: Optional[str]` ID of the template for the front side. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services like `certified` or `registered` for postcards, though). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view the uploaded PDF content, 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.order_profiles.postcards.list() page = page.data[0] print(page.id) ``` #### Response ```json { "data": [ { "id": "postcard_profile_456", "object": "postcard_profile", "live": false, "description": "Promo Postcard", "size": "6x4", "frontTemplate": "template_abc", "backTemplate": "template_abc", "mailingClass": "standard_class", "createdAt": "2023-02-15T11:00:00Z", "updatedAt": "2023-02-15T11:00:00Z" } ], "object": "list", "totalCount": 1, "limit": 1, "skip": 0 } ``` ## Retrieve Postcard Profile `print_mail.order_profiles.postcards.retrieve(strid, PostcardRetrieveParams**kwargs) -> PostcardProfile` **get** `/print-mail/v1/order_profiles/postcards/{id}` Retrieves the details of a specific Postcard Profile. ### Parameters - `id: str` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. ### Returns - `class PostcardProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["postcard_profile"]` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updated_at: datetime` Timestamp when the profile was last updated. - `back_template: Optional[str]` ID of the template for the back side. Required unless `pdf` is provided. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `front_template: Optional[str]` ID of the template for the front side. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services like `certified` or `registered` for postcards, though). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view the uploaded PDF content, 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 ) postcard_profile = client.print_mail.order_profiles.postcards.retrieve( id="id", ) print(postcard_profile.id) ``` #### Response ```json { "id": "postcard_profile_456", "object": "postcard_profile", "live": false, "description": "Promo Postcard", "size": "6x4", "frontTemplate": "template_abc", "backTemplate": "template_abc", "mailingClass": "standard_class", "createdAt": "2023-02-15T11:00:00Z", "updatedAt": "2023-02-15T11:00:00Z" } ``` ## Update Postcard Profile `print_mail.order_profiles.postcards.update(strid, PostcardUpdateParams**kwargs) -> PostcardProfile` **post** `/print-mail/v1/order_profiles/postcards/{id}` Updates specific fields of an existing Postcard Profile. If providing a `pdf`, the request `Content-Type` must be `multipart/form-data`. ### Parameters - `id: str` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. - `back_template: Optional[str]` ID of the template for the back side. Required unless `pdf` is provided. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `front_template: Optional[str]` ID of the template for the front side. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services like `certified` or `registered` for postcards, though). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `pdf: Optional[str]` A 2-page PDF file containing the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`. ### Returns - `class PostcardProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["postcard_profile"]` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updated_at: datetime` Timestamp when the profile was last updated. - `back_template: Optional[str]` ID of the template for the back side. Required unless `pdf` is provided. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `front_template: Optional[str]` ID of the template for the front side. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services like `certified` or `registered` for postcards, though). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view the uploaded PDF content, 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 ) postcard_profile = client.print_mail.order_profiles.postcards.update( id="id", ) print(postcard_profile.id) ``` #### Response ```json { "id": "postcard_profile_456", "object": "postcard_profile", "live": false, "description": "Promo Postcard", "size": "6x4", "frontTemplate": "template_abc", "backTemplate": "template_abc", "mailingClass": "standard_class", "createdAt": "2023-02-15T11:00:00Z", "updatedAt": "2023-02-15T11:00:00Z" } ``` ## Delete Postcard Profile `print_mail.order_profiles.postcards.delete(strid) -> PostcardDeleteResponse` **delete** `/print-mail/v1/order_profiles/postcards/{id}` Deletes a Postcard Profile. ### Parameters - `id: str` ### Returns - `class PostcardDeleteResponse: …` - `id: str` Unique identifier for the order profile. - `deleted: Literal[true]` - `true` - `object: Literal["postcard_profile"]` Always `postcard_profile`. - `"postcard_profile"` ### 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 ) postcard = client.print_mail.order_profiles.postcards.delete( "id", ) print(postcard.id) ``` #### Response ```json { "id": "postcard_profile_456", "object": "postcard_profile", "deleted": true } ``` ## Domain Types ### Postcard Profile - `class PostcardProfile: …` - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["postcard_profile"]` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updated_at: datetime` Timestamp when the profile was last updated. - `back_template: Optional[str]` ID of the template for the back side. Required unless `pdf` is provided. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `front_template: Optional[str]` ID of the template for the front side. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services like `certified` or `registered` for postcards, though). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view the uploaded PDF content, if any. ### Postcard Size - `Literal["6x4", "9x6", "11x6"]` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` # Self Mailers ## Create Self-Mailer Profile `print_mail.order_profiles.self_mailers.create(SelfMailerCreateParams**kwargs) -> SelfMailerProfile` **post** `/print-mail/v1/order_profiles/self_mailers` Creates a new Self-Mailer Profile. Provide either `insideTemplate` and `outsideTemplate` IDs, or upload a 2-page `pdf`. If providing a `pdf`, the request `Content-Type` must be `multipart/form-data`. ### Parameters - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `inside_template: Optional[str]` ID of the template for the inside. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services for self-mailers). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `outside_template: Optional[str]` ID of the template for the outside. Required unless `pdf` is provided. - `pdf: Optional[str]` A 2-page PDF file containing the self-mailer content (inside and outside). Cannot be used with `insideTemplate`/`outsideTemplate`. ### Returns - `class SelfMailerProfile: …` Represents a Self-Mailer Profile resource. - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["self_mailer_profile"]` Always `self_mailer_profile`. - `"self_mailer_profile"` - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `inside_template: Optional[str]` ID of the template for the inside. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services for self-mailers). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `outside_template: Optional[str]` ID of the template for the outside. Required unless `pdf` is provided. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view 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 ) self_mailer_profile = client.print_mail.order_profiles.self_mailers.create( size="8.5x11_bifold", ) print(self_mailer_profile.id) ``` #### Response ```json { "id": "self_mailer_profile_101", "object": "self_mailer_profile", "live": false, "description": "Marketing Self-Mailer", "size": "8.5x11_bifold", "insideTemplate": "template_123", "outsideTemplate": "template_456", "mailingClass": "standard_class", "createdAt": "2023-04-25T13:00:00Z", "updatedAt": "2023-04-25T13:00:00Z" } ``` ## List Self-Mailer Profiles `print_mail.order_profiles.self_mailers.list(SelfMailerListParams**kwargs) -> SyncSkipLimit[SelfMailerProfile]` **get** `/print-mail/v1/order_profiles/self_mailers` Retrieves a list of Self-Mailer Profiles. ### 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 SelfMailerProfile: …` Represents a Self-Mailer Profile resource. - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["self_mailer_profile"]` Always `self_mailer_profile`. - `"self_mailer_profile"` - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `inside_template: Optional[str]` ID of the template for the inside. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services for self-mailers). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `outside_template: Optional[str]` ID of the template for the outside. Required unless `pdf` is provided. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view 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.order_profiles.self_mailers.list() page = page.data[0] print(page.id) ``` #### Response ```json { "data": [ { "id": "self_mailer_profile_101", "object": "self_mailer_profile", "live": false, "description": "Marketing Self-Mailer", "size": "8.5x11_bifold", "insideTemplate": "template_123", "outsideTemplate": "template_456", "mailingClass": "standard_class", "createdAt": "2023-04-25T13:00:00Z", "updatedAt": "2023-04-25T13:00:00Z" } ], "object": "list", "totalCount": 1, "limit": 1, "skip": 0 } ``` ## Retrieve Self-Mailer Profile `print_mail.order_profiles.self_mailers.retrieve(strid, SelfMailerRetrieveParams**kwargs) -> SelfMailerProfile` **get** `/print-mail/v1/order_profiles/self_mailers/{id}` Retrieves the details of a specific Self-Mailer Profile. ### Parameters - `id: str` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. ### Returns - `class SelfMailerProfile: …` Represents a Self-Mailer Profile resource. - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["self_mailer_profile"]` Always `self_mailer_profile`. - `"self_mailer_profile"` - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `inside_template: Optional[str]` ID of the template for the inside. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services for self-mailers). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `outside_template: Optional[str]` ID of the template for the outside. Required unless `pdf` is provided. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view 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 ) self_mailer_profile = client.print_mail.order_profiles.self_mailers.retrieve( id="id", ) print(self_mailer_profile.id) ``` #### Response ```json { "id": "self_mailer_profile_101", "object": "self_mailer_profile", "live": false, "description": "Marketing Self-Mailer", "size": "8.5x11_bifold", "insideTemplate": "template_123", "outsideTemplate": "template_456", "mailingClass": "standard_class", "createdAt": "2023-04-25T13:00:00Z", "updatedAt": "2023-04-25T13:00:00Z" } ``` ## Update Self-Mailer Profile `print_mail.order_profiles.self_mailers.update(strid, SelfMailerUpdateParams**kwargs) -> SelfMailerProfile` **post** `/print-mail/v1/order_profiles/self_mailers/{id}` Updates specific fields of an existing Self-Mailer Profile. If providing a `pdf`, the request `Content-Type` must be `multipart/form-data`. ### Parameters - `id: str` - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `expand: Optional[SequenceNotStr[str]]` Optional list of related resources to expand in the response. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `inside_template: Optional[str]` ID of the template for the inside. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services for self-mailers). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `outside_template: Optional[str]` ID of the template for the outside. Required unless `pdf` is provided. - `pdf: Optional[str]` A 2-page PDF file containing the self-mailer content (inside and outside). Cannot be used with `insideTemplate`/`outsideTemplate`. ### Returns - `class SelfMailerProfile: …` Represents a Self-Mailer Profile resource. - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["self_mailer_profile"]` Always `self_mailer_profile`. - `"self_mailer_profile"` - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `inside_template: Optional[str]` ID of the template for the inside. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services for self-mailers). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `outside_template: Optional[str]` ID of the template for the outside. Required unless `pdf` is provided. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view 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 ) self_mailer_profile = client.print_mail.order_profiles.self_mailers.update( id="id", size="8.5x11_bifold", ) print(self_mailer_profile.id) ``` #### Response ```json { "id": "self_mailer_profile_101", "object": "self_mailer_profile", "live": false, "description": "Marketing Self-Mailer", "size": "8.5x11_bifold", "insideTemplate": "template_123", "outsideTemplate": "template_456", "mailingClass": "standard_class", "createdAt": "2023-04-25T13:00:00Z", "updatedAt": "2023-04-25T13:00:00Z" } ``` ## Delete Self-Mailer Profile `print_mail.order_profiles.self_mailers.delete(strid) -> SelfMailerDeleteResponse` **delete** `/print-mail/v1/order_profiles/self_mailers/{id}` Deletes a Self-Mailer Profile. ### Parameters - `id: str` ### Returns - `class SelfMailerDeleteResponse: …` - `id: str` Unique identifier for the order profile. - `deleted: Literal[true]` - `true` - `object: Literal["self_mailer_profile"]` Always `self_mailer_profile`. - `"self_mailer_profile"` ### 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 ) self_mailer = client.print_mail.order_profiles.self_mailers.delete( "id", ) print(self_mailer.id) ``` #### Response ```json { "id": "self_mailer_profile_101", "object": "self_mailer_profile", "deleted": true } ``` ## Domain Types ### Self Mailer Profile - `class SelfMailerProfile: …` Represents a Self-Mailer Profile resource. - `id: str` Unique identifier for the order profile. - `created_at: datetime` Timestamp when the profile was created. - `live: bool` Indicates if the profile is associated with the live or test environment. - `object: Literal["self_mailer_profile"]` Always `self_mailer_profile`. - `"self_mailer_profile"` - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `updated_at: datetime` Timestamp when the profile was last updated. - `description: Optional[str]` An optional description for the profile. Set to `null` to remove during update. - `inside_template: Optional[str]` ID of the template for the inside. Required unless `pdf` is provided. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` Mailing class (cannot include extra services for self-mailers). - `"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 orders created using this profile. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata. - `outside_template: Optional[str]` ID of the template for the outside. Required unless `pdf` is provided. - `uploaded_pdf: Optional[str]` A temporary, signed URL to view the uploaded PDF, if any. ### Self Mailer Size - `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"` # Postcards ## Create Postcard `print_mail.postcards.create(PostcardCreateParams**kwargs) -> Postcard` **post** `/print-mail/v1/postcards` Create a postcard. Note that you can supply one of the following: - HTML content for the front and back of the postcard - A template ID for the front and back of the postcard - A URL or file for a 2 page PDF where the first page is the front of the postcard and the second page is the back - Upload the aforementioned PDF file via a multipart form upload request ### Parameters - `back_html: str` The HTML content for the back of the postcard. You can supply _either_ this or `backTemplate` but not both. - `front_html: str` The HTML content for the front of the postcard. You can supply _either_ this or `frontTemplate` but not both. - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `to: PostcardCreateWithHTMLTo` The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint. - `class ContactCreateWithFirstName: …` - `address_line1: str` The first line of the contact's address. - `country_code: str` The ISO 3611-1 country code of the contact's address. - `first_name: str` - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `class ContactCreateWithCompanyName: …` - `address_line1: str` The first line of the contact's address. - `company_name: str` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `str` - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `from_: Optional[PostcardCreateWithHTMLFrom]` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. Unlike other order types, the sender address is optional for postcards. - `class ContactCreateWithFirstName: …` - `class ContactCreateWithCompanyName: …` - `str` - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` The mailing class of this order. If not provided, automatically set to `first_class`. - `"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]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `send_date: Optional[Union[str, datetime]]` This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date. ### Returns - `class Postcard: …` - `id: str` A unique ID prefixed with postcard_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["postcard"]` Always `postcard`. - `"postcard"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `from_: Optional[Contact]` The contact information of the sender. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) postcard = client.print_mail.postcards.create( back_html="Back", front_html="Front", size="6x4", to="contact_456", from_="contact_123", ) print(postcard.id) ``` #### Response ```json { "id": "postcard_123456", "object": "postcard", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "6x4", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ``` ## List Postcards `print_mail.postcards.list(PostcardListParams**kwargs) -> SyncSkipLimit[Postcard]` **get** `/print-mail/v1/postcards` Get a list of postcards. ### 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 Postcard: …` - `id: str` A unique ID prefixed with postcard_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["postcard"]` Always `postcard`. - `"postcard"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `from_: Optional[Contact]` The contact information of the sender. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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.postcards.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "postcard_123456", "object": "postcard", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "6x4", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ] } ``` ## Get Postcard `print_mail.postcards.retrieve(strid) -> Postcard` **get** `/print-mail/v1/postcards/{id}` Retrieve a postcard by ID. ### Parameters - `id: str` ### Returns - `class Postcard: …` - `id: str` A unique ID prefixed with postcard_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["postcard"]` Always `postcard`. - `"postcard"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `from_: Optional[Contact]` The contact information of the sender. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) postcard = client.print_mail.postcards.retrieve( "id", ) print(postcard.id) ``` #### Response ```json { "id": "postcard_123456", "object": "postcard", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "6x4", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ``` ## Cancel Postcard `print_mail.postcards.delete(strid) -> Postcard` **delete** `/print-mail/v1/postcards/{id}` Cancel a postcard by ID. Note that this operation cannot be undone. ### Parameters - `id: str` ### Returns - `class Postcard: …` - `id: str` A unique ID prefixed with postcard_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["postcard"]` Always `postcard`. - `"postcard"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `from_: Optional[Contact]` The contact information of the sender. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) postcard = client.print_mail.postcards.delete( "id", ) print(postcard.id) ``` #### Response ```json { "id": "postcard_123456", "object": "postcard", "status": "cancelled", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "6x4", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ``` ## Get Postcard Preview `print_mail.postcards.retrieve_url(strid) -> PostcardRetrieveURLResponse` **get** `/print-mail/v1/postcards/{id}/url` Retrieve a postcard preview URL. This is only available for customers with our document management addon, which offers document generation and hosting capabilities. This endpoint has a much higher rate limit than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases. ### Parameters - `id: str` ### Returns - `class PostcardRetrieveURLResponse: …` - `id: str` A unique ID prefixed with postcard_ - `object: str` - `url: str` A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call. ### 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 ) response = client.print_mail.postcards.retrieve_url( "id", ) print(response.id) ``` #### Response ```json { "id": "postcard_123456", "object": "postcard_url", "url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/postcard_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D" } ``` ## Domain Types ### Postcard - `class Postcard: …` - `id: str` A unique ID prefixed with postcard_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["postcard"]` Always `postcard`. - `"postcard"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `from_: Optional[Contact]` The contact information of the sender. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. # Reports ## Create Saved Report `print_mail.reports.create(ReportCreateParams**kwargs) -> Report` **post** `/print-mail/v1/reports` Create a new saved report definition. Saved reports are SQL queries that can be executed later to generate full exports or samples. If you just want to do ad-hoc queries, you should use the `/reports/samples` endpoint. ### Parameters - `sql_query: str` The SQL query defining the report. - `description: Optional[str]` An optional user-friendly description for the report. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the report. ### Returns - `class Report: …` Represents a saved Report definition. - `id: str` Unique identifier for the report. - `created_at: datetime` Timestamp when the report was created. - `live: bool` Indicates if the report is associated with the live or test environment. - `object: Literal["report"]` Always `report`. - `"report"` - `sql_query: str` The SQL query defining the report. - `updated_at: datetime` Timestamp when the report was last updated. - `description: Optional[str]` An optional user-friendly description for the report. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the report. ### 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 ) report = client.print_mail.reports.create( sql_query="SELECT id, status FROM orders WHERE created_at > ?", description="Recent Orders", metadata={ "team": "Sales" }, ) print(report.id) ``` #### Response ```json { "id": "report_123", "object": "report", "live": false, "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?", "description": "Recent Orders", "metadata": { "team": "Sales" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z" } ``` ## Run Ad-hoc Query `print_mail.reports.sample(ReportSampleParams**kwargs) -> ReportSample` **post** `/print-mail/v1/reports/samples` Run an ad-hoc SQL query against your data lake and get a sample of the results. This is useful for quickly testing queries without saving them as a report. The query execution time and result size are limited. ### Parameters - `sql_query: str` The SQL query to execute for the sample. - `limit: Optional[int]` Maximum number of rows to return in the sample. - `params: Optional[SequenceNotStr[str]]` Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1). ### Returns - `class ReportSample: …` Represents the result of a report sample query. - `id: str` Unique identifier for the sample query result. - `records: List[Dict[str, object]]` The actual data records returned by the sample query. - `report: Optional[str]` The ID of the report this sample was generated from, or null for ad-hoc samples. ### 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 ) report_sample = client.print_mail.reports.sample( sql_query="SELECT id FROM contacts LIMIT 5", limit=5, params=[], ) print(report_sample.id) ``` #### Response ```json { "id": "sample_abc", "report": "report_123", "records": [ { "id": "order_1" }, { "id": "order_2" } ] } ``` ## Update Report `print_mail.reports.update(strid, ReportUpdateParams**kwargs) -> Report` **post** `/print-mail/v1/reports/{id}` Update an existing saved report definition. You can change the query, description, or metadata. ### Parameters - `id: str` - `description: Optional[str]` An optional user-friendly description for the report. Set to null to remove. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the report. Set to null to remove. - `sql_query: Optional[str]` The SQL query defining the report. ### Returns - `class Report: …` Represents a saved Report definition. - `id: str` Unique identifier for the report. - `created_at: datetime` Timestamp when the report was created. - `live: bool` Indicates if the report is associated with the live or test environment. - `object: Literal["report"]` Always `report`. - `"report"` - `sql_query: str` The SQL query defining the report. - `updated_at: datetime` Timestamp when the report was last updated. - `description: Optional[str]` An optional user-friendly description for the report. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the report. ### 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 ) report = client.print_mail.reports.update( id="id", description="Recent Orders (Updated)", ) print(report.id) ``` #### Response ```json { "id": "report_123", "object": "report", "live": false, "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?", "description": "Recent Orders", "metadata": { "team": "Sales" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z" } ``` ## List Saved Reports `print_mail.reports.list(ReportListParams**kwargs) -> SyncSkipLimit[Report]` **get** `/print-mail/v1/reports` Retrieve a list of saved reports for your organization. ### 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 Report: …` Represents a saved Report definition. - `id: str` Unique identifier for the report. - `created_at: datetime` Timestamp when the report was created. - `live: bool` Indicates if the report is associated with the live or test environment. - `object: Literal["report"]` Always `report`. - `"report"` - `sql_query: str` The SQL query defining the report. - `updated_at: datetime` Timestamp when the report was last updated. - `description: Optional[str]` An optional user-friendly description for the report. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the report. ### 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.reports.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "report_123", "object": "report", "live": false, "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?", "description": "Recent Orders", "metadata": { "team": "Sales" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z" } ] } ``` ## Retrieve Saved Report `print_mail.reports.retrieve(strid) -> Report` **get** `/print-mail/v1/reports/{id}` Retrieve the details of a specific saved report by its ID. ### Parameters - `id: str` ### Returns - `class Report: …` Represents a saved Report definition. - `id: str` Unique identifier for the report. - `created_at: datetime` Timestamp when the report was created. - `live: bool` Indicates if the report is associated with the live or test environment. - `object: Literal["report"]` Always `report`. - `"report"` - `sql_query: str` The SQL query defining the report. - `updated_at: datetime` Timestamp when the report was last updated. - `description: Optional[str]` An optional user-friendly description for the report. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the report. ### 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 ) report = client.print_mail.reports.retrieve( "id", ) print(report.id) ``` #### Response ```json { "id": "report_123", "object": "report", "live": false, "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?", "description": "Recent Orders", "metadata": { "team": "Sales" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z" } ``` ## Delete Saved Report `print_mail.reports.delete(strid) -> DeletedResponse` **delete** `/print-mail/v1/reports/{id}` Delete a saved report definition. This action cannot be undone. Associated exports are not automatically deleted. ### Parameters - `id: str` ### Returns - `class DeletedResponse: …` Generic response for delete operations. - `id: str` The ID of the deleted resource. - `deleted: Literal[true]` Indicates the resource was successfully deleted. - `true` ### 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 ) deleted_response = client.print_mail.reports.delete( "id", ) print(deleted_response.id) ``` #### Response ```json { "id": "report_123", "deleted": true } ``` ## Domain Types ### Deleted Response - `class DeletedResponse: …` Generic response for delete operations. - `id: str` The ID of the deleted resource. - `deleted: Literal[true]` Indicates the resource was successfully deleted. - `true` ### Report - `class Report: …` Represents a saved Report definition. - `id: str` Unique identifier for the report. - `created_at: datetime` Timestamp when the report was created. - `live: bool` Indicates if the report is associated with the live or test environment. - `object: Literal["report"]` Always `report`. - `"report"` - `sql_query: str` The SQL query defining the report. - `updated_at: datetime` Timestamp when the report was last updated. - `description: Optional[str]` An optional user-friendly description for the report. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the report. # Samples ## Sample a Saved Report `print_mail.reports.samples.create(strid, SampleCreateParams**kwargs) -> ReportSample` **post** `/print-mail/v1/reports/{id}/samples` Run the query associated with a saved report and get a sample of the results. This allows getting up to 1000 rows of resutls but the runtime of the query is limited to 30 seconds. If you need more rows or longer runtime, you should create an export from this report. ### Parameters - `id: str` - `limit: Optional[int]` Maximum number of rows to return in the sample. - `params: Optional[SequenceNotStr[str]]` Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1). ### Returns - `class ReportSample: …` Represents the result of a report sample query. - `id: str` Unique identifier for the sample query result. - `records: List[Dict[str, object]]` The actual data records returned by the sample query. - `report: Optional[str]` The ID of the report this sample was generated from, or null for ad-hoc samples. ### 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 ) report_sample = client.print_mail.reports.samples.create( id="id", limit=10, params=["2023-10-01T00:00:00Z"], ) print(report_sample.id) ``` #### Response ```json { "id": "sample_abc", "report": "report_123", "records": [ { "id": "order_1" }, { "id": "order_2" } ] } ``` ## Domain Types ### Report Sample - `class ReportSample: …` Represents the result of a report sample query. - `id: str` Unique identifier for the sample query result. - `records: List[Dict[str, object]]` The actual data records returned by the sample query. - `report: Optional[str]` The ID of the report this sample was generated from, or null for ad-hoc samples. ### Report Sample Create Base - `class ReportSampleCreateBase: …` Base properties for creating a report sample. - `limit: Optional[int]` Maximum number of rows to return in the sample. - `params: Optional[List[str]]` Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1). # Exports ## Create a Report Export `print_mail.reports.exports.create(strreport_id, ExportCreateParams**kwargs) -> ReportExport` **post** `/print-mail/v1/reports/{reportID}/exports` Create a new export job for a saved report. This runs the report's query asynchronously and generates a downloadable CSV file with the full results. Your queries can run for up to 13 minutes the resulting file can be up to 100mb large. ### Parameters - `report_id: str` - `description: Optional[str]` An optional user-friendly description for the export. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the export. - `params: Optional[SequenceNotStr[str]]` Optional parameters to bind to the SQL query of the associated report. ### Returns - `class ReportExport: …` Represents a report export job and its results. - `id: str` Unique identifier for the report export. - `created_at: datetime` Timestamp when the export was created. - `live: bool` Indicates if the export is associated with the live or test environment. - `object: Literal["report_export"]` Always `report_export`. - `"report_export"` - `report: Report` Details of the report this export was generated from. - `id: str` The ID of the report. - `sql_query: str` The SQL query used for this export (snapshotted at creation time). - `updated_at: datetime` Timestamp when the export was last updated (e.g., finished generation). - `description: Optional[str]` An optional user-friendly description for the export. - `failure_message: Optional[str]` If export generation failed, this contains the error message. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the export. - `output_url: Optional[str]` A signed URL to download the exported data (CSV format). Available when generation is complete and successful. - `params: Optional[List[str]]` Optional parameters to bind to the SQL query of the associated report. - `row_count: Optional[int]` The number of rows in the exported data. - `size_in_bytes: Optional[int]` The size of the generated export file in bytes. - `truncated_to_bytes: Optional[int]` If the output was truncated, indicates the byte limit reached. ### 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 ) report_export = client.print_mail.reports.exports.create( report_id="reportID", description="October Orders Export", params=["2023-10-01T00:00:00Z"], ) print(report_export.id) ``` #### Response ```json { "id": "report_export_123", "object": "report_export", "live": false, "report": { "id": "report_123", "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?" }, "params": [ "2023-10-01T00:00:00Z" ], "description": "October Orders Export", "outputURL": "https://s3.amazonaws.com/...", "sizeInBytes": 1024, "rowCount": 50, "createdAt": "2023-10-27T11:00:00Z", "updatedAt": "2023-10-27T11:05:00Z" } ``` ## Get Report Export `print_mail.reports.exports.retrieve(strexport_id, ExportRetrieveParams**kwargs) -> ReportExport` **get** `/print-mail/v1/reports/{reportID}/exports/{exportID}` Retrieve the status and details of a specific report export job. Check the `outputURL` property for the download link once generation is complete. ### Parameters - `report_id: str` - `export_id: str` ### Returns - `class ReportExport: …` Represents a report export job and its results. - `id: str` Unique identifier for the report export. - `created_at: datetime` Timestamp when the export was created. - `live: bool` Indicates if the export is associated with the live or test environment. - `object: Literal["report_export"]` Always `report_export`. - `"report_export"` - `report: Report` Details of the report this export was generated from. - `id: str` The ID of the report. - `sql_query: str` The SQL query used for this export (snapshotted at creation time). - `updated_at: datetime` Timestamp when the export was last updated (e.g., finished generation). - `description: Optional[str]` An optional user-friendly description for the export. - `failure_message: Optional[str]` If export generation failed, this contains the error message. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the export. - `output_url: Optional[str]` A signed URL to download the exported data (CSV format). Available when generation is complete and successful. - `params: Optional[List[str]]` Optional parameters to bind to the SQL query of the associated report. - `row_count: Optional[int]` The number of rows in the exported data. - `size_in_bytes: Optional[int]` The size of the generated export file in bytes. - `truncated_to_bytes: Optional[int]` If the output was truncated, indicates the byte limit reached. ### 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 ) report_export = client.print_mail.reports.exports.retrieve( export_id="exportID", report_id="reportID", ) print(report_export.id) ``` #### Response ```json { "id": "report_export_123", "object": "report_export", "live": false, "report": { "id": "report_123", "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?" }, "params": [ "2023-10-01T00:00:00Z" ], "description": "October Orders Export", "outputURL": "https://s3.amazonaws.com/...", "sizeInBytes": 1024, "rowCount": 50, "createdAt": "2023-10-27T11:00:00Z", "updatedAt": "2023-10-27T11:05:00Z" } ``` ## Delete Report Export `print_mail.reports.exports.delete(strexport_id, ExportDeleteParams**kwargs) -> DeletedResponse` **delete** `/print-mail/v1/reports/{reportID}/exports/{exportID}` Delete a completed or failed report export job and its associated output file (if any). This action cannot be undone. You cannot delete an export that is still generating. ### Parameters - `report_id: str` - `export_id: str` ### Returns - `class DeletedResponse: …` Generic response for delete operations. - `id: str` The ID of the deleted resource. - `deleted: Literal[true]` Indicates the resource was successfully deleted. - `true` ### 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 ) deleted_response = client.print_mail.reports.exports.delete( export_id="exportID", report_id="reportID", ) print(deleted_response.id) ``` #### Response ```json { "id": "report_export_123", "deleted": true } ``` ## Domain Types ### Report Export - `class ReportExport: …` Represents a report export job and its results. - `id: str` Unique identifier for the report export. - `created_at: datetime` Timestamp when the export was created. - `live: bool` Indicates if the export is associated with the live or test environment. - `object: Literal["report_export"]` Always `report_export`. - `"report_export"` - `report: Report` Details of the report this export was generated from. - `id: str` The ID of the report. - `sql_query: str` The SQL query used for this export (snapshotted at creation time). - `updated_at: datetime` Timestamp when the export was last updated (e.g., finished generation). - `description: Optional[str]` An optional user-friendly description for the export. - `failure_message: Optional[str]` If export generation failed, this contains the error message. - `metadata: Optional[Dict[str, str]]` Optional key-value metadata associated with the export. - `output_url: Optional[str]` A signed URL to download the exported data (CSV format). Available when generation is complete and successful. - `params: Optional[List[str]]` Optional parameters to bind to the SQL query of the associated report. - `row_count: Optional[int]` The number of rows in the exported data. - `size_in_bytes: Optional[int]` The size of the generated export file in bytes. - `truncated_to_bytes: Optional[int]` If the output was truncated, indicates the byte limit reached. # Self Mailers ## Create Self Mailer `print_mail.self_mailers.create(SelfMailerCreateParams**kwargs) -> SelfMailer` **post** `/print-mail/v1/self_mailers` Create a self-mailer. Note that you can supply one of the following: - HTML content for the inside and outside of the self-mailer - A template ID for the inside and outside of the self-mailer - A URL or file for a 2 page PDF where the first page is the outside of the self-mailer and the second page is the inside - Upload the aforementioned PDF file via a multipart form upload request ### Parameters - `from_: SelfMailerCreateWithHTMLFrom` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. - `class ContactCreateWithFirstName: …` - `address_line1: str` The first line of the contact's address. - `country_code: str` The ISO 3611-1 country code of the contact's address. - `first_name: str` - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `class ContactCreateWithCompanyName: …` - `address_line1: str` The first line of the contact's address. - `company_name: str` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `str` - `inside_html: str` The HTML content for the inside of the self-mailer. You can supply _either_ this or `insideTemplate` but not both. - `outside_html: str` The HTML content for the outside of the self-mailer. You can supply _either_ this or `outsideTemplate` but not both. - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `to: SelfMailerCreateWithHTMLTo` The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint. - `class ContactCreateWithFirstName: …` - `class ContactCreateWithCompanyName: …` - `str` - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]` The mailing class of this order. If not provided, automatically set to `first_class`. - `"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]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `send_date: Optional[Union[str, datetime]]` This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date. ### Returns - `class SelfMailer: …` - `id: str` A unique ID prefixed with self_mailer_ - `created_at: datetime` The UTC time at which this resource was created. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["self_mailer"]` Always `self_mailer`. - `"self_mailer"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) self_mailer = client.print_mail.self_mailers.create( from_="contact_123", inside_html="Inside", outside_html="Outside", size="8.5x11_bifold", to="contact_456", ) print(self_mailer.id) ``` #### Response ```json { "id": "self_mailer_123456", "object": "self_mailer", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "8.5x11_bifold", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ``` ## List Self Mailers `print_mail.self_mailers.list(SelfMailerListParams**kwargs) -> SyncSkipLimit[SelfMailer]` **get** `/print-mail/v1/self_mailers` Get a list of self-mailers. ### 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 SelfMailer: …` - `id: str` A unique ID prefixed with self_mailer_ - `created_at: datetime` The UTC time at which this resource was created. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["self_mailer"]` Always `self_mailer`. - `"self_mailer"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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.self_mailers.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "self_mailer_123456", "object": "self_mailer", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "8.5x11_bifold", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ] } ``` ## Get Self Mailer `print_mail.self_mailers.retrieve(strid) -> SelfMailer` **get** `/print-mail/v1/self_mailers/{id}` Retrieve a self-mailer by ID. ### Parameters - `id: str` ### Returns - `class SelfMailer: …` - `id: str` A unique ID prefixed with self_mailer_ - `created_at: datetime` The UTC time at which this resource was created. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["self_mailer"]` Always `self_mailer`. - `"self_mailer"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) self_mailer = client.print_mail.self_mailers.retrieve( "id", ) print(self_mailer.id) ``` #### Response ```json { "id": "self_mailer_123456", "object": "self_mailer", "status": "ready", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "8.5x11_bifold", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ``` ## Cancel Self Mailer `print_mail.self_mailers.delete(strid) -> SelfMailer` **delete** `/print-mail/v1/self_mailers/{id}` Cancel a self-mailer by ID. Note that this operation cannot be undone. ### Parameters - `id: str` ### Returns - `class SelfMailer: …` - `id: str` A unique ID prefixed with self_mailer_ - `created_at: datetime` The UTC time at which this resource was created. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["self_mailer"]` Always `self_mailer`. - `"self_mailer"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. ### 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 ) self_mailer = client.print_mail.self_mailers.delete( "id", ) print(self_mailer.id) ``` #### Response ```json { "id": "self_mailer_123456", "object": "self_mailer", "status": "cancelled", "live": false, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "from": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "object": "contact", "live": false, "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "skipVerification": false, "forceVerifiedStatus": false, "addressStatus": "verified", "createdAt": "2022-02-16T15:08:41.052Z", "updatedAt": "2022-02-16T15:08:41.052Z" }, "size": "8.5x11_bifold", "sendDate": "2020-11-12T23:23:47.974Z", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z", "mailingClass": "first_class" } ``` ## Get Self Mailer Preview `print_mail.self_mailers.retrieve_url(strid) -> SelfMailerRetrieveURLResponse` **get** `/print-mail/v1/self_mailers/{id}/url` Retrieve a self-mailer preview URL. This is only available for customers with our document management addon, which offers document generation and hosting capabilities. This endpoint has a much higher rate limit than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases. ### Parameters - `id: str` ### Returns - `class SelfMailerRetrieveURLResponse: …` - `id: str` A unique ID prefixed with self_mailer_ - `object: str` - `url: str` A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call. ### 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 ) response = client.print_mail.self_mailers.retrieve_url( "id", ) print(response.id) ``` #### Response ```json { "id": "self_mailer_123456", "object": "self_mailer_url", "url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/self_mailer_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D" } ``` ## Domain Types ### Self Mailer - `class SelfMailer: …` - `id: str` A unique ID prefixed with self_mailer_ - `created_at: datetime` The UTC time at which this resource was created. - `from_: Contact` The contact information of the sender. - `id: str` A unique ID prefixed with contact_ - `address_line1: str` The first line of the contact's address. - `address_status: Literal["verified", "corrected", "failed"]` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `address_errors: Optional[str]` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `company_name: Optional[str]` Company name of the contact. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: Optional[str]` Email of the contact. - `first_name: Optional[str]` First name of the contact. - `force_verified_status: Optional[bool]` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `job_title: Optional[str]` Job title of the contact. - `last_name: Optional[str]` Last name of the contact. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `phone_number: Optional[str]` Phone number of the contact. - `postal_or_zip: Optional[str]` The postal or ZIP code of the contact's address. - `province_or_state: Optional[str]` Province or state of the contact's address. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: bool` `true` if this is a live mode resource else `false`. - `mailing_class: Literal["first_class", "standard_class", "express", 23 more]` The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details. - `"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"` - `object: Literal["self_mailer"]` Always `self_mailer`. - `"self_mailer"` - `send_date: datetime` This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time. - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `status: Literal["ready", "printing", "processed_for_delivery", 2 more]` See `OrderStatus` for more details on the status of this order. - `"ready"` - `"printing"` - `"processed_for_delivery"` - `"completed"` - `"cancelled"` - `to: Contact` The recipient of this order. This will be provided even if you delete the underlying contact. - `updated_at: datetime` The UTC time at which this resource was last updated. - `cancellation: Optional[Cancellation]` The cancellation details of this order. Populated if the order has been cancelled. - `reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelled_by_user: Optional[str]` The user ID who cancelled the order. - `note: Optional[str]` An optional note provided by the user who cancelled the order. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `imb_date: Optional[datetime]` The last date that the IMB status was updated. See `imbStatus` for more details. - `imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "returned_to_sender"]]` The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders. - `"entered_mail_stream"` - `"out_for_delivery"` - `"returned_to_sender"` - `imb_zip_code: Optional[str]` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `merge_variables: Optional[Dict[str, object]]` These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `tracking_number: Optional[str]` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: Optional[str]` PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order. This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again. # Sub Organizations ## Create a sub-organization. `print_mail.sub_organizations.update(SubOrganizationUpdateParams**kwargs) -> SubOrganizationUpdateResponse` **post** `/print-mail/v1/sub_organizations` When creating a user through the API, the verifiedEmail field will automatically be set to true. However, if public signups are used, the email will need to be verified by the user. ### Parameters - `country_code: str` The country code of the sub-organization. - `email: str` The email of the user to be created alongside the sub-organization. - `name: str` The name of the user to be created alongside the sub-organization. - `organization_name: str` The name of the sub-organization. - `password: str` The password of the user to be created alongside the sub-organization. - `phone_number: Optional[str]` The phone number of the user to be created alongside the sub-organization. ### Returns - `class SubOrganizationUpdateResponse: …` - `sub_organization: SubOrganization` The Sub-Organization object. - `id: str` A unique ID prefixed with `sub_org_`. - `country_code: str` The country code of the sub-organization. - `created_at: datetime` The UTC time at which this resource was created. - `limit: int` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: str` The name of the sub-organization. - `object: Literal["sub_org"]` Always `sub_org`. - `"sub_org"` - `spend: int` The current rolling charge for the sub-organization for the month, in cents. - `updated_at: datetime` The UTC time at which this resource was last update. - `usage: int` The amount of mail the sub-organization has sent out this month. - `user: User` The user object. - `id: str` A unique ID prefixed with `user_`. - `api_keys: List[UserAPIKey]` The user's API keys. Contains live and test mode API keys. - `value: str` The value of the API key. - `active_until: Optional[datetime]` An optional date which the API key is active until. After this date, the API key will no longer be valid. - `email: str` The email of the user. - `name: str` The name of the user. - `organization: str` A unique ID prefixed with `user_`. - `pending_invite: bool` Indicates if the user has a pending invite. - `roles: List[str]` The roles given to the user. Roles can be used to restrict access for users. - `verified_email: bool` Indicates if the user has a verified email or not. - `email_preferences: Optional[EmailPreferences]` A set of preferences for how a user should receive emails. - `order_preview_send_preference: Optional[Literal["do_not_send", "send_live_only", "send_live_and_test"]]` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` - `last_login_time: Optional[datetime]` The date and time at which the user last logged in. - `phone_number: Optional[str]` The phone number of the user. - `previous_emails: Optional[List[str]]` A list of emails the user has previously had. If a user has changed their email before, this list will be populated with all of the emails they once had. ### 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 ) sub_organization = client.print_mail.sub_organizations.update( country_code="CA", email="suborg@postgrid.com", name="Calvin", organization_name="PostGrid", password="very-strong-password", phone_number="9059059059", ) print(sub_organization.sub_organization) ``` #### Response ```json { "user": { "id": "user_abc123def456ghi6789", "pendingInvite": false, "organization": "org_abc123def456ghi6789", "email": "user@postgrid.com", "name": "Calvin", "apiKeys": [ { "value": "live_abcdefg" }, { "value": "test_abcdefg" } ], "verifiedEmail": true, "roles": [ "role_abc123def456ghi6789" ] }, "subOrganization": { "usage": 0, "limit": 500, "spend": 0, "name": "PostGrid", "countryCode": "CA", "id": "sub_org_abc123def456ghi6789", "object": "sub_org", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } } ``` ## List sub-organizations. `print_mail.sub_organizations.list(SubOrganizationListParams**kwargs) -> SyncSkipLimit[SubOrganization]` **get** `/print-mail/v1/sub_organizations` List sub-organizations. ### 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 SubOrganization: …` The Sub-Organization object. - `id: str` A unique ID prefixed with `sub_org_`. - `country_code: str` The country code of the sub-organization. - `created_at: datetime` The UTC time at which this resource was created. - `limit: int` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: str` The name of the sub-organization. - `object: Literal["sub_org"]` Always `sub_org`. - `"sub_org"` - `spend: int` The current rolling charge for the sub-organization for the month, in cents. - `updated_at: datetime` The UTC time at which this resource was last update. - `usage: int` The amount of mail the sub-organization has sent out this month. ### 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.sub_organizations.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "usage": 0, "limit": 500, "spend": 0, "name": "PostGrid", "countryCode": "CA", "id": "sub_org_abc123def456ghi6789", "object": "sub_org", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ] } ``` ## Get a sub-organization. `print_mail.sub_organizations.retrieve(strid) -> SubOrganization` **get** `/print-mail/v1/sub_organizations/{id}` Get a sub-organization. ### Parameters - `id: str` ### Returns - `class SubOrganization: …` The Sub-Organization object. - `id: str` A unique ID prefixed with `sub_org_`. - `country_code: str` The country code of the sub-organization. - `created_at: datetime` The UTC time at which this resource was created. - `limit: int` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: str` The name of the sub-organization. - `object: Literal["sub_org"]` Always `sub_org`. - `"sub_org"` - `spend: int` The current rolling charge for the sub-organization for the month, in cents. - `updated_at: datetime` The UTC time at which this resource was last update. - `usage: int` The amount of mail the sub-organization has sent out this month. ### 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 ) sub_organization = client.print_mail.sub_organizations.retrieve( "id", ) print(sub_organization.id) ``` #### Response ```json { "usage": 0, "limit": 500, "spend": 0, "name": "PostGrid", "countryCode": "CA", "id": "sub_org_abc123def456ghi6789", "object": "sub_org", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ``` ## List users for a sub-organization. `print_mail.sub_organizations.retrieve_users(strid, SubOrganizationRetrieveUsersParams**kwargs) -> SubOrganizationRetrieveUsersResponse` **get** `/print-mail/v1/sub_organizations/{id}/users` List users for a sub-organization. ### Parameters - `id: str` - `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 - `List[SubOrganizationRetrieveUsersResponseItem]` - `id: str` A unique ID prefixed with `user_`. - `email: str` The email of the user. - `name: str` The name of the user. - `organization: str` A unique ID prefixed with `user_`. - `pending_invite: bool` Indicates if the user has a pending invite. - `roles: List[str]` The roles given to the user. Roles can be used to restrict access for users. - `verified_email: bool` Indicates if the user has a verified email or not. - `email_preferences: Optional[EmailPreferences]` A set of preferences for how a user should receive emails. - `order_preview_send_preference: Optional[Literal["do_not_send", "send_live_only", "send_live_and_test"]]` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` - `last_login_time: Optional[datetime]` The date and time at which the user last logged in. - `phone_number: Optional[str]` The phone number of the user. - `previous_emails: Optional[List[str]]` A list of emails the user has previously had. If a user has changed their email before, this list will be populated with all of the emails they once had. ### 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 ) response = client.print_mail.sub_organizations.retrieve_users( id="id", ) print(response) ``` #### Response ```json [ { "id": "user_abc123def456ghi6789", "pendingInvite": false, "organization": "org_abc123def456ghi6789", "email": "user@postgrid.com", "name": "Calvin", "verifiedEmail": true, "roles": [ "role_abc123def456ghi6789" ] } ] ``` ## Domain Types ### Email Preferences - `class EmailPreferences: …` A set of preferences for how a user should receive emails. - `order_preview_send_preference: Optional[Literal["do_not_send", "send_live_only", "send_live_and_test"]]` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` ### Sub Organization - `class SubOrganization: …` The Sub-Organization object. - `id: str` A unique ID prefixed with `sub_org_`. - `country_code: str` The country code of the sub-organization. - `created_at: datetime` The UTC time at which this resource was created. - `limit: int` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: str` The name of the sub-organization. - `object: Literal["sub_org"]` Always `sub_org`. - `"sub_org"` - `spend: int` The current rolling charge for the sub-organization for the month, in cents. - `updated_at: datetime` The UTC time at which this resource was last update. - `usage: int` The amount of mail the sub-organization has sent out this month. # Templates ## Create Template `print_mail.templates.create(TemplateCreateParams**kwargs) -> Template` **post** `/print-mail/v1/templates` Create a template. Note that if you want to create a template that works with our template editor, you must use our dashboard. ### Parameters - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content of this template. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Returns - `class Template: …` - `id: str` A unique ID prefixed with template_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["template"]` Always `template`. - `"template"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content of this template. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### 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 ) template = client.print_mail.templates.create( description="Test", html="Hello {{to.firstName}}", ) print(template.id) ``` #### Response ```json { "id": "template_tBnVEzz878mXLbHQaz86j8", "object": "template", "live": false, "description": "Test", "html": "Hello {{to.firstName}}!", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ``` ## List Templates `print_mail.templates.list(TemplateListParams**kwargs) -> SyncSkipLimit[Template]` **get** `/print-mail/v1/templates` Get a list of templates. ### 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 Template: …` - `id: str` A unique ID prefixed with template_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["template"]` Always `template`. - `"template"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content of this template. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### 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.templates.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "template_tBnVEzz878mXLbHQaz86j8", "object": "template", "live": false, "description": "Test", "html": "Hello {{to.firstName}}!", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ] } ``` ## Get Template `print_mail.templates.retrieve(strid) -> Template` **get** `/print-mail/v1/templates/{id}` Retrieve a template by ID. ### Parameters - `id: str` ### Returns - `class Template: …` - `id: str` A unique ID prefixed with template_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["template"]` Always `template`. - `"template"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content of this template. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### 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 ) template = client.print_mail.templates.retrieve( "id", ) print(template.id) ``` #### Response ```json { "id": "template_tBnVEzz878mXLbHQaz86j8", "object": "template", "live": false, "description": "Test", "html": "Hello {{to.firstName}}!", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ``` ## Update Template `print_mail.templates.update(strid, TemplateUpdateParams**kwargs) -> Template` **post** `/print-mail/v1/templates/{id}` Update a template by ID. ### Parameters - `id: str` - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content of this template. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Returns - `class Template: …` - `id: str` A unique ID prefixed with template_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["template"]` Always `template`. - `"template"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content of this template. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### 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 ) template = client.print_mail.templates.update( id="id", description="Test", html="Hello {{to.firstName}}!", ) print(template.id) ``` #### Response ```json { "id": "template_tBnVEzz878mXLbHQaz86j8", "object": "template", "live": false, "description": "Test", "html": "Hello {{to.firstName}}!", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ``` ## Delete Template `print_mail.templates.delete(strid) -> TemplateDeleteResponse` **delete** `/print-mail/v1/templates/{id}` Delete a template by ID. Note that this operation cannot be undone. ### Parameters - `id: str` ### Returns - `class TemplateDeleteResponse: …` - `id: str` A unique ID prefixed with template_ - `deleted: Literal[true]` - `true` - `object: Literal["template"]` Always `template`. - `"template"` ### 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 ) template = client.print_mail.templates.delete( "id", ) print(template.id) ``` #### Response ```json { "id": "template_sqF12lZ1VlBb", "deleted": true, "object": "template" } ``` ## Domain Types ### Template - `class Template: …` - `id: str` A unique ID prefixed with template_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["template"]` Always `template`. - `"template"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: Optional[str]` The HTML content of this template. - `metadata: Optional[Dict[str, object]]` See the section on Metadata.