# Print Mail ## Domain Types ### Contact Create With Company Name - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `addressLine1: string` The first line of the contact's address. - `companyName: string` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. ### Contact Create With First Name - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `addressLine1: string` The first line of the contact's address. - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `firstName: string` - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. # Bank Accounts ## Create Bank Account **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. ### Body Parameters - `body: object { accountNumber, bankCountryCode, bankName, 9 more } or object { accountNumber, bankCountryCode, bankName, 9 more } or object { accountNumber, bankCountryCode, bankName, 9 more }` - `BankAccountCreateSignatureText = object { accountNumber, bankCountryCode, bankName, 9 more }` - `accountNumber: string` The account number of the bank account. - `bankCountryCode: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bankName: string` The name of the bank. - `signatureText: string` The signature text of the bank account. - `bankPrimaryLine: optional string` The primary address line of the bank. - `bankSecondaryLine: optional string` The secondary address line of the bank. - `caDesignationNumber: optional string` The designation number of the bank account (for CA). - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `routeNumber: optional string` The route number of the bank account (for CA). - `routingNumber: optional string` The routing number of the bank account (for US). - `transitNumber: optional string` The transit number of the bank account (for CA). - `BankAccountCreateSignatureImageURL = object { accountNumber, bankCountryCode, bankName, 9 more }` - `accountNumber: string` The account number of the bank account. - `bankCountryCode: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `bankName: string` The name of the bank. - `signatureImage: string` Link to signature image which PostGrid will download and apply to cheques created with this bank account. - `bankPrimaryLine: optional string` The primary address line of the bank. - `bankSecondaryLine: optional string` The secondary address line of the bank. - `caDesignationNumber: optional string` The designation number of the bank account (for CA). - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `routeNumber: optional string` The route number of the bank account (for CA). - `routingNumber: optional string` The routing number of the bank account (for US). - `transitNumber: optional string` The transit number of the bank account (for CA). - `BankAccountCreateSignatureImageFile = object { accountNumber, bankCountryCode, bankName, 9 more }` - `accountNumber: string` The account number of the bank account. - `bankCountryCode: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `bankName: string` The name of the bank. - `signatureImage: string` A PNG or JPEG file which PostGrid will apply to checks created with this bank account. - `bankPrimaryLine: optional string` The primary address line of the bank. - `bankSecondaryLine: optional string` The secondary address line of the bank. - `caDesignationNumber: optional string` The designation number of the bank account (for CA). - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `routeNumber: optional string` The route number of the bank account (for CA). - `routingNumber: optional string` The routing number of the bank account (for US). - `transitNumber: optional string` The transit number of the bank account (for CA). ### Returns - `BankAccount = object { id, accountNumber, bankCountryCode, 15 more }` - `id: string` A unique ID prefixed with bank_account_ - `accountNumber: string` The account number of the bank account. - `bankCountryCode: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bankName: string` The name of the bank. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "bank_account"` Always `bank_account`. - `"bank_account"` - `updatedAt: string` The UTC time at which this resource was last updated. - `bankPrimaryLine: optional string` The primary address line of the bank. - `bankSecondaryLine: optional string` The secondary address line of the bank. - `caDesignationNumber: optional string` The designation number of the bank account (for CA). - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `routeNumber: optional string` The route number of the bank account (for CA). - `routingNumber: optional string` The routing number of the bank account (for US). - `signatureImage: optional string` A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present. - `signatureText: optional string` The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present. - `transitNumber: optional string` The transit number of the bank account (for CA). ### Example ```http curl https://api.postgrid.com/print-mail/v1/bank_accounts \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "accountNumber": "accountNumber", "bankCountryCode": "CA", "bankName": "bankName", "signatureText": "signatureText" }' ``` #### 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 **get** `/print-mail/v1/bank_accounts` Get a list of bank accounts. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of BankAccount` - `id: string` A unique ID prefixed with bank_account_ - `accountNumber: string` The account number of the bank account. - `bankCountryCode: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bankName: string` The name of the bank. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "bank_account"` Always `bank_account`. - `"bank_account"` - `updatedAt: string` The UTC time at which this resource was last updated. - `bankPrimaryLine: optional string` The primary address line of the bank. - `bankSecondaryLine: optional string` The secondary address line of the bank. - `caDesignationNumber: optional string` The designation number of the bank account (for CA). - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `routeNumber: optional string` The route number of the bank account (for CA). - `routingNumber: optional string` The routing number of the bank account (for US). - `signatureImage: optional string` A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present. - `signatureText: optional string` The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present. - `transitNumber: optional string` The transit number of the bank account (for CA). - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/bank_accounts \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/bank_accounts/{id}` Retrieve a bank account by ID. ### Path Parameters - `id: string` ### Returns - `BankAccount = object { id, accountNumber, bankCountryCode, 15 more }` - `id: string` A unique ID prefixed with bank_account_ - `accountNumber: string` The account number of the bank account. - `bankCountryCode: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bankName: string` The name of the bank. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "bank_account"` Always `bank_account`. - `"bank_account"` - `updatedAt: string` The UTC time at which this resource was last updated. - `bankPrimaryLine: optional string` The primary address line of the bank. - `bankSecondaryLine: optional string` The secondary address line of the bank. - `caDesignationNumber: optional string` The designation number of the bank account (for CA). - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `routeNumber: optional string` The route number of the bank account (for CA). - `routingNumber: optional string` The routing number of the bank account (for US). - `signatureImage: optional string` A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present. - `signatureText: optional string` The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present. - `transitNumber: optional string` The transit number of the bank account (for CA). ### Example ```http curl https://api.postgrid.com/print-mail/v1/bank_accounts/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **delete** `/print-mail/v1/bank_accounts/{id}` Delete a bank account by ID. Note that this operation cannot be undone. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with bank_account_ - `deleted: true` - `true` - `object: "bank_account"` Always `bank_account`. - `"bank_account"` ### Example ```http curl https://api.postgrid.com/print-mail/v1/bank_accounts/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "bank_account_sqF12lZ1VlBb", "deleted": true, "object": "bank_account" } ``` ## Domain Types ### Bank Account - `BankAccount = object { id, accountNumber, bankCountryCode, 15 more }` - `id: string` A unique ID prefixed with bank_account_ - `accountNumber: string` The account number of the bank account. - `bankCountryCode: BankAccountCountryCode` Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports. - `"CA"` - `"US"` - `bankName: string` The name of the bank. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "bank_account"` Always `bank_account`. - `"bank_account"` - `updatedAt: string` The UTC time at which this resource was last updated. - `bankPrimaryLine: optional string` The primary address line of the bank. - `bankSecondaryLine: optional string` The secondary address line of the bank. - `caDesignationNumber: optional string` The designation number of the bank account (for CA). - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `routeNumber: optional string` The route number of the bank account (for CA). - `routingNumber: optional string` The routing number of the bank account (for US). - `signatureImage: optional string` A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present. - `signatureText: optional string` The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present. - `transitNumber: optional string` The transit number of the bank account (for CA). ### Bank Account Country Code - `BankAccountCountryCode = "CA" or "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 **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. ### Header Parameters - `"idempotency-key": optional string` ### Body Parameters - `mailingList: string` The ID of the mailing list associated with this campaign. - `chequeProfile: optional string` The ID of the cheque profile used for this campaign, if applicable. - `defaultSenderContact: optional string` The ID of the default sender contact to use for orders if not specified per recipient. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `letterProfile: optional string` The ID of the letter profile used for this campaign, if applicable. - `metadata: optional map[unknown]` See the section on Metadata. - `postcardProfile: optional string` The ID of the postcard profile used for this campaign, if applicable. - `selfMailerProfile: optional string` The ID of the self-mailer profile used for this campaign, if applicable. - `sendDate: optional string` The scheduled date and time for the campaign to be sent. ### Returns - `Campaign = object { id, createdAt, createdCount, 15 more }` Represents a bulk mail campaign. - `id: string` A unique ID prefixed with campaign_ - `createdAt: string` The UTC time at which this resource was created. - `createdCount: number` The number of orders successfully created for this campaign. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingList: string` The ID of the mailing list associated with this campaign. - `status: "drafting" or "changes_required" or "creating_orders" or 4 more` Status of the campaign lifecycle. - `"drafting"` - `"changes_required"` - `"creating_orders"` - `"draft"` - `"ready"` - `"printing"` - `"processed_for_delivery"` - `updatedAt: string` The UTC time at which this resource was last updated. - `chequeProfile: optional string` The ID of the cheque profile used for this campaign, if applicable. - `defaultSenderContact: optional string` The ID of the default sender contact to use for orders if not specified per recipient. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "processing_error" or "internal_error"` Type of error encountered during campaign processing. - `"processing_error"` - `"internal_error"` - `letterProfile: optional string` The ID of the letter profile used for this campaign, if applicable. - `metadata: optional map[unknown]` See the section on Metadata. - `orderPreviewURL: optional string` A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later. - `postcardProfile: optional string` The ID of the postcard profile used for this campaign, if applicable. - `reportURL: optional string` A temporary URL to download the processing report, available once the campaign is in the `ready` status. - `selfMailerProfile: optional string` The ID of the self-mailer profile used for this campaign, if applicable. - `sendDate: optional string` The scheduled date and time for the campaign to be sent. ### Example ```http curl https://api.postgrid.com/print-mail/v1/campaigns \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "mailingList": "mailingList" }' ``` #### 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 **get** `/print-mail/v1/campaigns` Retrieve a list of campaigns. Returns a paginated list of campaigns associated with the authenticated organization, filterable by various parameters. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of Campaign` - `id: string` A unique ID prefixed with campaign_ - `createdAt: string` The UTC time at which this resource was created. - `createdCount: number` The number of orders successfully created for this campaign. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingList: string` The ID of the mailing list associated with this campaign. - `status: "drafting" or "changes_required" or "creating_orders" or 4 more` Status of the campaign lifecycle. - `"drafting"` - `"changes_required"` - `"creating_orders"` - `"draft"` - `"ready"` - `"printing"` - `"processed_for_delivery"` - `updatedAt: string` The UTC time at which this resource was last updated. - `chequeProfile: optional string` The ID of the cheque profile used for this campaign, if applicable. - `defaultSenderContact: optional string` The ID of the default sender contact to use for orders if not specified per recipient. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "processing_error" or "internal_error"` Type of error encountered during campaign processing. - `"processing_error"` - `"internal_error"` - `letterProfile: optional string` The ID of the letter profile used for this campaign, if applicable. - `metadata: optional map[unknown]` See the section on Metadata. - `orderPreviewURL: optional string` A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later. - `postcardProfile: optional string` The ID of the postcard profile used for this campaign, if applicable. - `reportURL: optional string` A temporary URL to download the processing report, available once the campaign is in the `ready` status. - `selfMailerProfile: optional string` The ID of the self-mailer profile used for this campaign, if applicable. - `sendDate: optional string` The scheduled date and time for the campaign to be sent. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/campaigns \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/campaigns/{id}` Retrieve a specific campaign by its ID. ### Path Parameters - `id: string` ### Returns - `Campaign = object { id, createdAt, createdCount, 15 more }` Represents a bulk mail campaign. - `id: string` A unique ID prefixed with campaign_ - `createdAt: string` The UTC time at which this resource was created. - `createdCount: number` The number of orders successfully created for this campaign. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingList: string` The ID of the mailing list associated with this campaign. - `status: "drafting" or "changes_required" or "creating_orders" or 4 more` Status of the campaign lifecycle. - `"drafting"` - `"changes_required"` - `"creating_orders"` - `"draft"` - `"ready"` - `"printing"` - `"processed_for_delivery"` - `updatedAt: string` The UTC time at which this resource was last updated. - `chequeProfile: optional string` The ID of the cheque profile used for this campaign, if applicable. - `defaultSenderContact: optional string` The ID of the default sender contact to use for orders if not specified per recipient. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "processing_error" or "internal_error"` Type of error encountered during campaign processing. - `"processing_error"` - `"internal_error"` - `letterProfile: optional string` The ID of the letter profile used for this campaign, if applicable. - `metadata: optional map[unknown]` See the section on Metadata. - `orderPreviewURL: optional string` A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later. - `postcardProfile: optional string` The ID of the postcard profile used for this campaign, if applicable. - `reportURL: optional string` A temporary URL to download the processing report, available once the campaign is in the `ready` status. - `selfMailerProfile: optional string` The ID of the self-mailer profile used for this campaign, if applicable. - `sendDate: optional string` The scheduled date and time for the campaign to be sent. ### Example ```http curl https://api.postgrid.com/print-mail/v1/campaigns/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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`. ### Path Parameters - `id: string` ### Body Parameters - `chequeProfile: optional string` The ID of the cheque profile to use. Setting this will remove other profile types. Set to `null` to remove. - `defaultSenderContact: optional string` The ID of the default sender contact. Set to `null` to remove. - `description: optional string` An optional description for the campaign. Set to `null` to remove the existing description. - `letterProfile: optional string` The ID of the letter profile to use. Setting this will remove other profile types. Set to `null` to remove. - `mailingList: optional string` The ID of the mailing list to associate with this campaign. - `metadata: optional map[string]` Optional key-value data associated with the campaign. Set to `null` to remove existing metadata. - `postcardProfile: optional string` The ID of the postcard profile to use. Setting this will remove other profile types. Set to `null` to remove. - `selfMailerProfile: optional string` The ID of the self-mailer profile to use. Setting this will remove other profile types. Set to `null` to remove. ### Returns - `Campaign = object { id, createdAt, createdCount, 15 more }` Represents a bulk mail campaign. - `id: string` A unique ID prefixed with campaign_ - `createdAt: string` The UTC time at which this resource was created. - `createdCount: number` The number of orders successfully created for this campaign. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingList: string` The ID of the mailing list associated with this campaign. - `status: "drafting" or "changes_required" or "creating_orders" or 4 more` Status of the campaign lifecycle. - `"drafting"` - `"changes_required"` - `"creating_orders"` - `"draft"` - `"ready"` - `"printing"` - `"processed_for_delivery"` - `updatedAt: string` The UTC time at which this resource was last updated. - `chequeProfile: optional string` The ID of the cheque profile used for this campaign, if applicable. - `defaultSenderContact: optional string` The ID of the default sender contact to use for orders if not specified per recipient. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "processing_error" or "internal_error"` Type of error encountered during campaign processing. - `"processing_error"` - `"internal_error"` - `letterProfile: optional string` The ID of the letter profile used for this campaign, if applicable. - `metadata: optional map[unknown]` See the section on Metadata. - `orderPreviewURL: optional string` A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later. - `postcardProfile: optional string` The ID of the postcard profile used for this campaign, if applicable. - `reportURL: optional string` A temporary URL to download the processing report, available once the campaign is in the `ready` status. - `selfMailerProfile: optional string` The ID of the self-mailer profile used for this campaign, if applicable. - `sendDate: optional string` The scheduled date and time for the campaign to be sent. ### Example ```http curl https://api.postgrid.com/print-mail/v1/campaigns/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 **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. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with campaign_ - `deleted: true` - `true` ### Example ```http curl https://api.postgrid.com/print-mail/v1/campaigns/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "campaign_sqF12lZ1VlBb", "deleted": true } ``` ## Send 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. ### Path Parameters - `id: string` ### Body Parameters - `sendDate: optional string or string` The date and time the campaign should be sent. Must be in the future. If omitted, defaults to the earliest possible processing date. - `string` - `string` ### Returns - `Campaign = object { id, createdAt, createdCount, 15 more }` Represents a bulk mail campaign. - `id: string` A unique ID prefixed with campaign_ - `createdAt: string` The UTC time at which this resource was created. - `createdCount: number` The number of orders successfully created for this campaign. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingList: string` The ID of the mailing list associated with this campaign. - `status: "drafting" or "changes_required" or "creating_orders" or 4 more` Status of the campaign lifecycle. - `"drafting"` - `"changes_required"` - `"creating_orders"` - `"draft"` - `"ready"` - `"printing"` - `"processed_for_delivery"` - `updatedAt: string` The UTC time at which this resource was last updated. - `chequeProfile: optional string` The ID of the cheque profile used for this campaign, if applicable. - `defaultSenderContact: optional string` The ID of the default sender contact to use for orders if not specified per recipient. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "processing_error" or "internal_error"` Type of error encountered during campaign processing. - `"processing_error"` - `"internal_error"` - `letterProfile: optional string` The ID of the letter profile used for this campaign, if applicable. - `metadata: optional map[unknown]` See the section on Metadata. - `orderPreviewURL: optional string` A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later. - `postcardProfile: optional string` The ID of the postcard profile used for this campaign, if applicable. - `reportURL: optional string` A temporary URL to download the processing report, available once the campaign is in the `ready` status. - `selfMailerProfile: optional string` The ID of the self-mailer profile used for this campaign, if applicable. - `sendDate: optional string` The scheduled date and time for the campaign to be sent. ### Example ```http curl https://api.postgrid.com/print-mail/v1/campaigns/$ID/send \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 - `Campaign = object { id, createdAt, createdCount, 15 more }` Represents a bulk mail campaign. - `id: string` A unique ID prefixed with campaign_ - `createdAt: string` The UTC time at which this resource was created. - `createdCount: number` The number of orders successfully created for this campaign. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingList: string` The ID of the mailing list associated with this campaign. - `status: "drafting" or "changes_required" or "creating_orders" or 4 more` Status of the campaign lifecycle. - `"drafting"` - `"changes_required"` - `"creating_orders"` - `"draft"` - `"ready"` - `"printing"` - `"processed_for_delivery"` - `updatedAt: string` The UTC time at which this resource was last updated. - `chequeProfile: optional string` The ID of the cheque profile used for this campaign, if applicable. - `defaultSenderContact: optional string` The ID of the default sender contact to use for orders if not specified per recipient. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "processing_error" or "internal_error"` Type of error encountered during campaign processing. - `"processing_error"` - `"internal_error"` - `letterProfile: optional string` The ID of the letter profile used for this campaign, if applicable. - `metadata: optional map[unknown]` See the section on Metadata. - `orderPreviewURL: optional string` A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later. - `postcardProfile: optional string` The ID of the postcard profile used for this campaign, if applicable. - `reportURL: optional string` A temporary URL to download the processing report, available once the campaign is in the `ready` status. - `selfMailerProfile: optional string` The ID of the self-mailer profile used for this campaign, if applicable. - `sendDate: optional string` The scheduled date and time for the campaign to be sent. # Cheques ## Create 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" } } ``` ### Body Parameters - `amount: number` The amount of the cheque in cents. - `bankAccount: string` The bank account (ID) associated with the cheque. - `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `addressLine1: string` The first line of the contact's address. - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `firstName: string` - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `addressLine1: string` The first line of the contact's address. - `companyName: string` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `string` - `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `currencyCode: optional "USD" or "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 string` An optional string describing this resource. Will be visible in the API and the dashboard. - `digitalOnly: optional DigitalOnly` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: string` Text to be displayed as a watermark on the digital cheque. - `envelope: optional "standard" or string` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `string` - `logoURL: optional string` 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). - `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string` The memo of the cheque. - `mergeVariables: optional map[unknown]` 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 string` The message of the cheque. - `metadata: optional map[unknown]` See the section on Metadata. - `number: optional number` 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. - `redirectTo: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `sendDate: optional string` 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 - `Cheque = object { id, amount, bankAccount, 27 more }` - `id: string` A unique ID prefixed with cheque_ - `amount: number` The amount of the cheque in cents. - `bankAccount: string` The bank account (ID) associated with the cheque. - `createdAt: string` The UTC time at which this resource was created. - `currencyCode: "USD" or "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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "cheque"` Always `cheque`. - `"cheque"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `depositReadyPDFURL: optional string` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `digitalOnly: optional DigitalOnly` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: string` Text to be displayed as a watermark on the digital cheque. - `envelope: optional "standard" or string` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `string` - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logoURL: optional string` 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 string` The memo of the cheque. - `mergeVariables: optional map[unknown]` 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 string` The message of the cheque. - `metadata: optional map[unknown]` See the section on Metadata. - `number: optional number` 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. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/cheques \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "amount": 1000, "bankAccount": "bank_123", "from": "contact_123", "to": "contact_123" }' ``` #### 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 **get** `/print-mail/v1/cheques` Get a list of cheques. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of Cheque` - `id: string` A unique ID prefixed with cheque_ - `amount: number` The amount of the cheque in cents. - `bankAccount: string` The bank account (ID) associated with the cheque. - `createdAt: string` The UTC time at which this resource was created. - `currencyCode: "USD" or "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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "cheque"` Always `cheque`. - `"cheque"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `depositReadyPDFURL: optional string` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `digitalOnly: optional DigitalOnly` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: string` Text to be displayed as a watermark on the digital cheque. - `envelope: optional "standard" or string` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `string` - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logoURL: optional string` 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 string` The memo of the cheque. - `mergeVariables: optional map[unknown]` 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 string` The message of the cheque. - `metadata: optional map[unknown]` See the section on Metadata. - `number: optional number` 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. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/cheques \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/cheques/{id}` Retrieve a cheque by ID. ### Path Parameters - `id: string` ### Returns - `Cheque = object { id, amount, bankAccount, 27 more }` - `id: string` A unique ID prefixed with cheque_ - `amount: number` The amount of the cheque in cents. - `bankAccount: string` The bank account (ID) associated with the cheque. - `createdAt: string` The UTC time at which this resource was created. - `currencyCode: "USD" or "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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "cheque"` Always `cheque`. - `"cheque"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `depositReadyPDFURL: optional string` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `digitalOnly: optional DigitalOnly` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: string` Text to be displayed as a watermark on the digital cheque. - `envelope: optional "standard" or string` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `string` - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logoURL: optional string` 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 string` The memo of the cheque. - `mergeVariables: optional map[unknown]` 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 string` The message of the cheque. - `metadata: optional map[unknown]` See the section on Metadata. - `number: optional number` 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. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/cheques/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **delete** `/print-mail/v1/cheques/{id}` Cancel a cheque by ID. Note that this operation cannot be undone. ### Path Parameters - `id: string` ### Returns - `Cheque = object { id, amount, bankAccount, 27 more }` - `id: string` A unique ID prefixed with cheque_ - `amount: number` The amount of the cheque in cents. - `bankAccount: string` The bank account (ID) associated with the cheque. - `createdAt: string` The UTC time at which this resource was created. - `currencyCode: "USD" or "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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "cheque"` Always `cheque`. - `"cheque"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `depositReadyPDFURL: optional string` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `digitalOnly: optional DigitalOnly` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: string` Text to be displayed as a watermark on the digital cheque. - `envelope: optional "standard" or string` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `string` - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logoURL: optional string` 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 string` The memo of the cheque. - `mergeVariables: optional map[unknown]` 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 string` The message of the cheque. - `metadata: optional map[unknown]` See the section on Metadata. - `number: optional number` 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. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/cheques/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with cheque_ - `object: string` - `url: string` A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call. ### Example ```http curl https://api.postgrid.com/print-mail/v1/cheques/$ID/url \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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) **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. ### Path Parameters - `id: string` ### Returns - `Cheque = object { id, amount, bankAccount, 27 more }` - `id: string` A unique ID prefixed with cheque_ - `amount: number` The amount of the cheque in cents. - `bankAccount: string` The bank account (ID) associated with the cheque. - `createdAt: string` The UTC time at which this resource was created. - `currencyCode: "USD" or "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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "cheque"` Always `cheque`. - `"cheque"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `depositReadyPDFURL: optional string` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `digitalOnly: optional DigitalOnly` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: string` Text to be displayed as a watermark on the digital cheque. - `envelope: optional "standard" or string` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `string` - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logoURL: optional string` 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 string` The memo of the cheque. - `mergeVariables: optional map[unknown]` 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 string` The message of the cheque. - `metadata: optional map[unknown]` See the section on Metadata. - `number: optional number` 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. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/cheques/$ID/with_deposit_ready_pdf \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 - `Cheque = object { id, amount, bankAccount, 27 more }` - `id: string` A unique ID prefixed with cheque_ - `amount: number` The amount of the cheque in cents. - `bankAccount: string` The bank account (ID) associated with the cheque. - `createdAt: string` The UTC time at which this resource was created. - `currencyCode: "USD" or "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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "cheque"` Always `cheque`. - `"cheque"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `depositReadyPDFURL: optional string` A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `digitalOnly: optional DigitalOnly` The digitalOnly object contains data for digital-only cheques. A watermark must be provided. - `watermark: string` Text to be displayed as a watermark on the digital cheque. - `envelope: optional "standard" or string` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`. - `"standard"` - `string` - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `logoURL: optional string` 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 string` The memo of the cheque. - `mergeVariables: optional map[unknown]` 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 string` The message of the cheque. - `metadata: optional map[unknown]` See the section on Metadata. - `number: optional number` 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. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 - `ChequeSize = "us_letter" or "us_legal"` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` ### Digital Only - `DigitalOnly = object { watermark }` - `watermark: string` Text to be displayed as a watermark on the digital cheque. # Contacts ## Create 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._ ### Body Parameters - `contact_create: ContactCreate` - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `addressLine1: string` The first line of the contact's address. - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `firstName: string` - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `addressLine1: string` The first line of the contact's address. - `companyName: string` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. ### Returns - `Contact = object { id, addressLine1, addressStatus, 20 more }` - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. ### Example ```http curl https://api.postgrid.com/print-mail/v1/contacts \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "addressLine1": "addressLine1", "countryCode": "countryCode", "firstName": "firstName" }' ``` #### 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 **get** `/print-mail/v1/contacts` Get a list of contacts. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of Contact` - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/contacts \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/contacts/{id}` Retrieve a contact. ### Path Parameters - `id: string` ### Returns - `Contact = object { id, addressLine1, addressStatus, 20 more }` - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. ### Example ```http curl https://api.postgrid.com/print-mail/v1/contacts/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **delete** `/print-mail/v1/contacts/{id}` Delete a contact. Note that this will not affect orders that were sent to this contact. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with contact_ - `deleted: true` - `true` - `object: "contact"` Always `contact`. - `"contact"` ### Example ```http curl https://api.postgrid.com/print-mail/v1/contacts/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "contact_sqF12lZ1VlBb", "deleted": true, "object": "contact" } ``` ## Domain Types ### Contact - `Contact = object { id, addressLine1, addressStatus, 20 more }` - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. ### Contact Create - `ContactCreate = ContactCreateWithFirstName or ContactCreateWithCompanyName` - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `addressLine1: string` The first line of the contact's address. - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `firstName: string` - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `addressLine1: string` The first line of the contact's address. - `companyName: string` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. # Letters ## Create 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 ### Body Parameters - `body: object { from, html, to, 14 more } or object { template } or object { from, pdf, to, 14 more }` - `LetterCreateWithHTML = object { from, html, to, 14 more }` - `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `addressLine1: string` The first line of the contact's address. - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `firstName: string` - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `addressLine1: string` The first line of the contact's address. - `companyName: string` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `string` - `html: string` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `addressPlacement: optional AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `color: optional boolean` Indicates if the letter is in color. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `doubleSided: optional boolean` Indicates if the letter is double-sided. - `envelope: optional string` The envelope (ID) for the letter. You can either specify a custom envelope ID or use the default `standard` envelope. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `perforatedPage: optional 1` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plasticCard: optional PlasticCard` Model representing a plastic card. - `size: "standard"` Enum representing the size of the plastic card. - `"standard"` - `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }` Model representing a double-sided plastic card. - `backHTML: optional string` The HTML content for the back side of the double-sided plastic card. - `backTemplate: optional string` The template ID for the back side of the double-sided plastic card. - `frontHTML: optional string` The HTML content for the front side of the double-sided plastic card. - `frontTemplate: optional string` The template ID for the front side of the double-sided plastic card. - `pdf: optional string` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `singleSided: optional object { html, pdf, template }` Model representing a single-sided plastic card. - `html: optional string` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: optional string` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: optional string` The template ID for the single-sided plastic card. - `returnEnvelope: optional string` The return envelope (ID) sent out with the letter, if any. - `sendDate: optional string` 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"` - `LetterCreateWithTemplate = object { template }` - `template: string` The template ID for the letter. You can supply _either_ this or `html` but not both. - `LetterCreateWithPdf = object { from, pdf, to, 14 more }` - `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `pdf: string` A URL pointing to a PDF file for the letter or the PDF file itself. - `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `addressPlacement: optional AddressPlacement` Enum representing the placement of the address on the letter. - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `color: optional boolean` Indicates if the letter is in color. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `doubleSided: optional boolean` Indicates if the letter is double-sided. - `envelope: optional string` The envelope (ID) for the letter. You can either specify a custom envelope ID or use the default `standard` envelope. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `perforatedPage: optional 1` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plasticCard: optional PlasticCard` Model representing a plastic card. - `returnEnvelope: optional string` The return envelope (ID) sent out with the letter, if any. - `sendDate: optional string` 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. ### Returns - `Letter = object { id, addressPlacement, color, 29 more }` - `id: string` A unique ID prefixed with letter_ - `addressPlacement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: boolean` Indicates if the letter is in color. - `createdAt: string` The UTC time at which this resource was created. - `doubleSided: boolean` Indicates if the letter is double-sided. - `envelope: string` The envelope (ID) for the letter or the default `standard` envelope. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "letter"` Always `letter`. - `"letter"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `pdfWorkflowRun: optional string` The ID of the PDF workflow run that created the letter, if any. - `perforatedPage: optional 1` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plasticCard: optional PlasticCard` Model representing a plastic card. - `size: "standard"` Enum representing the size of the plastic card. - `"standard"` - `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }` Model representing a double-sided plastic card. - `backHTML: optional string` The HTML content for the back side of the double-sided plastic card. - `backTemplate: optional string` The template ID for the back side of the double-sided plastic card. - `frontHTML: optional string` The HTML content for the front side of the double-sided plastic card. - `frontTemplate: optional string` The template ID for the front side of the double-sided plastic card. - `pdf: optional string` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `singleSided: optional object { html, pdf, template }` Model representing a single-sided plastic card. - `html: optional string` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: optional string` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: optional string` The template ID for the single-sided plastic card. - `returnEnvelope: optional string` The return envelope (ID) sent out with the letter, if any. - `template: optional string` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploadedPDF: optional string` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/letters \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "from": { "addressLine1": "addressLine1", "countryCode": "countryCode", "firstName": "firstName" }, "html": "html", "to": { "addressLine1": "addressLine1", "countryCode": "countryCode", "firstName": "firstName" } }' ``` #### 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 **get** `/print-mail/v1/letters` Get a list of letters. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of Letter` - `id: string` A unique ID prefixed with letter_ - `addressPlacement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: boolean` Indicates if the letter is in color. - `createdAt: string` The UTC time at which this resource was created. - `doubleSided: boolean` Indicates if the letter is double-sided. - `envelope: string` The envelope (ID) for the letter or the default `standard` envelope. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "letter"` Always `letter`. - `"letter"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `pdfWorkflowRun: optional string` The ID of the PDF workflow run that created the letter, if any. - `perforatedPage: optional 1` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plasticCard: optional PlasticCard` Model representing a plastic card. - `size: "standard"` Enum representing the size of the plastic card. - `"standard"` - `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }` Model representing a double-sided plastic card. - `backHTML: optional string` The HTML content for the back side of the double-sided plastic card. - `backTemplate: optional string` The template ID for the back side of the double-sided plastic card. - `frontHTML: optional string` The HTML content for the front side of the double-sided plastic card. - `frontTemplate: optional string` The template ID for the front side of the double-sided plastic card. - `pdf: optional string` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `singleSided: optional object { html, pdf, template }` Model representing a single-sided plastic card. - `html: optional string` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: optional string` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: optional string` The template ID for the single-sided plastic card. - `returnEnvelope: optional string` The return envelope (ID) sent out with the letter, if any. - `template: optional string` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploadedPDF: optional string` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: optional string` 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. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/letters \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/letters/{id}` Retrieve a letter by ID. ### Path Parameters - `id: string` ### Returns - `Letter = object { id, addressPlacement, color, 29 more }` - `id: string` A unique ID prefixed with letter_ - `addressPlacement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: boolean` Indicates if the letter is in color. - `createdAt: string` The UTC time at which this resource was created. - `doubleSided: boolean` Indicates if the letter is double-sided. - `envelope: string` The envelope (ID) for the letter or the default `standard` envelope. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "letter"` Always `letter`. - `"letter"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `pdfWorkflowRun: optional string` The ID of the PDF workflow run that created the letter, if any. - `perforatedPage: optional 1` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plasticCard: optional PlasticCard` Model representing a plastic card. - `size: "standard"` Enum representing the size of the plastic card. - `"standard"` - `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }` Model representing a double-sided plastic card. - `backHTML: optional string` The HTML content for the back side of the double-sided plastic card. - `backTemplate: optional string` The template ID for the back side of the double-sided plastic card. - `frontHTML: optional string` The HTML content for the front side of the double-sided plastic card. - `frontTemplate: optional string` The template ID for the front side of the double-sided plastic card. - `pdf: optional string` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `singleSided: optional object { html, pdf, template }` Model representing a single-sided plastic card. - `html: optional string` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: optional string` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: optional string` The template ID for the single-sided plastic card. - `returnEnvelope: optional string` The return envelope (ID) sent out with the letter, if any. - `template: optional string` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploadedPDF: optional string` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/letters/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **delete** `/print-mail/v1/letters/{id}` Cancel a letter by ID. Note that this operation cannot be undone. ### Path Parameters - `id: string` ### Returns - `Letter = object { id, addressPlacement, color, 29 more }` - `id: string` A unique ID prefixed with letter_ - `addressPlacement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: boolean` Indicates if the letter is in color. - `createdAt: string` The UTC time at which this resource was created. - `doubleSided: boolean` Indicates if the letter is double-sided. - `envelope: string` The envelope (ID) for the letter or the default `standard` envelope. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "letter"` Always `letter`. - `"letter"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `pdfWorkflowRun: optional string` The ID of the PDF workflow run that created the letter, if any. - `perforatedPage: optional 1` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plasticCard: optional PlasticCard` Model representing a plastic card. - `size: "standard"` Enum representing the size of the plastic card. - `"standard"` - `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }` Model representing a double-sided plastic card. - `backHTML: optional string` The HTML content for the back side of the double-sided plastic card. - `backTemplate: optional string` The template ID for the back side of the double-sided plastic card. - `frontHTML: optional string` The HTML content for the front side of the double-sided plastic card. - `frontTemplate: optional string` The template ID for the front side of the double-sided plastic card. - `pdf: optional string` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `singleSided: optional object { html, pdf, template }` Model representing a single-sided plastic card. - `html: optional string` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: optional string` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: optional string` The template ID for the single-sided plastic card. - `returnEnvelope: optional string` The return envelope (ID) sent out with the letter, if any. - `template: optional string` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploadedPDF: optional string` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/letters/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with letter_ - `object: string` - `url: string` A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call. ### Example ```http curl https://api.postgrid.com/print-mail/v1/letters/$ID/url \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 - `AddressPlacement = "top_first_page" or "insert_blank_page"` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` ### Attached Pdf - `AttachedPdf = object { file, placement }` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` ### Letter - `Letter = object { id, addressPlacement, color, 29 more }` - `id: string` A unique ID prefixed with letter_ - `addressPlacement: AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `color: boolean` Indicates if the letter is in color. - `createdAt: string` The UTC time at which this resource was created. - `doubleSided: boolean` Indicates if the letter is double-sided. - `envelope: string` The envelope (ID) for the letter or the default `standard` envelope. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "letter"` Always `letter`. - `"letter"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content for the letter. You can supply _either_ this or `template` but not both. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `pdfWorkflowRun: optional string` The ID of the PDF workflow run that created the letter, if any. - `perforatedPage: optional 1` If specified, indicates which letter page is perforated. Currently, only the first page can be perforated. - `1` - `plasticCard: optional PlasticCard` Model representing a plastic card. - `size: "standard"` Enum representing the size of the plastic card. - `"standard"` - `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }` Model representing a double-sided plastic card. - `backHTML: optional string` The HTML content for the back side of the double-sided plastic card. - `backTemplate: optional string` The template ID for the back side of the double-sided plastic card. - `frontHTML: optional string` The HTML content for the front side of the double-sided plastic card. - `frontTemplate: optional string` The template ID for the front side of the double-sided plastic card. - `pdf: optional string` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `singleSided: optional object { html, pdf, template }` Model representing a single-sided plastic card. - `html: optional string` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: optional string` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: optional string` The template ID for the single-sided plastic card. - `returnEnvelope: optional string` The return envelope (ID) sent out with the letter, if any. - `template: optional string` The template ID used for the letter. You can supply _either_ this or `html` but not both. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `uploadedPDF: optional string` If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF. - `url: optional string` 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 - `LetterSize = "us_letter" or "a4"` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` ### Plastic Card - `PlasticCard = object { size, doubleSided, singleSided }` Model representing a plastic card. - `size: "standard"` Enum representing the size of the plastic card. - `"standard"` - `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }` Model representing a double-sided plastic card. - `backHTML: optional string` The HTML content for the back side of the double-sided plastic card. - `backTemplate: optional string` The template ID for the back side of the double-sided plastic card. - `frontHTML: optional string` The HTML content for the front side of the double-sided plastic card. - `frontTemplate: optional string` The template ID for the front side of the double-sided plastic card. - `pdf: optional string` A URL pointing to a PDF file for the double-sided plastic card or the file itself. - `singleSided: optional object { html, pdf, template }` Model representing a single-sided plastic card. - `html: optional string` The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`. - `pdf: optional string` A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself. - `template: optional string` The template ID for the single-sided plastic card. # Mailing List Imports ## Create Mailing List Import **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. ### Header Parameters - `"idempotency-key": optional string` ### Body Parameters - `file: string` The CSV file for this import. - `fileType: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiverAddressMapping: map[string]` Mapping of columns for receiver addresses. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `receiverMergeVariableMapping: optional map[string]` Optional mapping of columns for receiver merge variables. - `senderAddressMapping: optional map[string]` Optional mapping of columns for sender addresses. If this is present, then all receivers should have a corresponding sender. - `senderMergeVariableMapping: optional map[string]` Optional mapping of columns for sender merge variables. ### Returns - `MailingListImportResponse = object { id, createdAt, errors, 13 more }` Read-only view of a MailingListImport - `id: string` A unique ID prefixed with mailing_list_import_ - `createdAt: string` The UTC time at which this resource was created. - `errors: array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "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: object { fileType, receiverAddressMapping, url, 3 more }` The file object your controller returns: all the mappings plus a signed URL. - `fileType: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiverAddressMapping: map[string]` 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: string` The signed URL your controller generates. - `receiverMergeVariableMapping: optional map[string]` Optional mapping of columns for receiver merge variables. - `senderAddressMapping: optional map[string]` Optional mapping of columns for sender addresses. - `senderMergeVariableMapping: optional map[string]` Optional mapping of columns for sender merge variables. - `invalidRowCount: number` Number of invalid rows found in the file. - `live: boolean` `true` if this is a live mode resource else `false`. - `notes: array of object { message, type }` Additional notes about the import process. - `message: string` A human-readable message describing the note. - `type: "truncated_test_file" or "skipped_invalid_contacts"` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: string` The organization that owns this import. - `receiverStatusCount: VerificationStatusCount` Count of contact verification statuses. - `correctedCount: number` Number of contacts that were corrected during verification. - `failedCount: number` Number of contacts that failed verification. - `verifiedCount: number` Number of contacts that were verified without changes. - `status: "validating" or "completed" or "changes_required"` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updatedAt: string` The UTC time at which this resource was last updated. - `validRowCount: number` Number of valid rows processed from the file. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `reportURL: optional string` A temporary URL to download the processing report, available once the import is completed. - `senderStatusCount: optional VerificationStatusCount` Count of contact verification statuses. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_list_imports \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "file": "https://signed-upload-url.csv", "fileType": "csv", "receiverAddressMapping": { "description": "Description", "firstName": "First Name", "lastName": "Last Name", "email": "Email", "addressLine1": "Address", "city": "City", "postalOrZip": "Postal Code", "provinceOrState": "State", "countryCode": "Country" } }' ``` #### 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 **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. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of MailingListImportResponse` - `id: string` A unique ID prefixed with mailing_list_import_ - `createdAt: string` The UTC time at which this resource was created. - `errors: array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "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: object { fileType, receiverAddressMapping, url, 3 more }` The file object your controller returns: all the mappings plus a signed URL. - `fileType: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiverAddressMapping: map[string]` 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: string` The signed URL your controller generates. - `receiverMergeVariableMapping: optional map[string]` Optional mapping of columns for receiver merge variables. - `senderAddressMapping: optional map[string]` Optional mapping of columns for sender addresses. - `senderMergeVariableMapping: optional map[string]` Optional mapping of columns for sender merge variables. - `invalidRowCount: number` Number of invalid rows found in the file. - `live: boolean` `true` if this is a live mode resource else `false`. - `notes: array of object { message, type }` Additional notes about the import process. - `message: string` A human-readable message describing the note. - `type: "truncated_test_file" or "skipped_invalid_contacts"` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: string` The organization that owns this import. - `receiverStatusCount: VerificationStatusCount` Count of contact verification statuses. - `correctedCount: number` Number of contacts that were corrected during verification. - `failedCount: number` Number of contacts that failed verification. - `verifiedCount: number` Number of contacts that were verified without changes. - `status: "validating" or "completed" or "changes_required"` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updatedAt: string` The UTC time at which this resource was last updated. - `validRowCount: number` Number of valid rows processed from the file. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `reportURL: optional string` A temporary URL to download the processing report, available once the import is completed. - `senderStatusCount: optional VerificationStatusCount` Count of contact verification statuses. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_list_imports \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **post** `/print-mail/v1/mailing_list_imports/{id}` Update an existing mailing list import. ### Path Parameters - `id: string` ### Body Parameters - `description: optional string` An optional description for the import. Set to `null` to remove the existing description. - `metadata: optional map[string]` Optional key-value data associated with the import. Set to `null` to remove existing metadata. ### Returns - `MailingListImportResponse = object { id, createdAt, errors, 13 more }` Read-only view of a MailingListImport - `id: string` A unique ID prefixed with mailing_list_import_ - `createdAt: string` The UTC time at which this resource was created. - `errors: array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "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: object { fileType, receiverAddressMapping, url, 3 more }` The file object your controller returns: all the mappings plus a signed URL. - `fileType: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiverAddressMapping: map[string]` 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: string` The signed URL your controller generates. - `receiverMergeVariableMapping: optional map[string]` Optional mapping of columns for receiver merge variables. - `senderAddressMapping: optional map[string]` Optional mapping of columns for sender addresses. - `senderMergeVariableMapping: optional map[string]` Optional mapping of columns for sender merge variables. - `invalidRowCount: number` Number of invalid rows found in the file. - `live: boolean` `true` if this is a live mode resource else `false`. - `notes: array of object { message, type }` Additional notes about the import process. - `message: string` A human-readable message describing the note. - `type: "truncated_test_file" or "skipped_invalid_contacts"` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: string` The organization that owns this import. - `receiverStatusCount: VerificationStatusCount` Count of contact verification statuses. - `correctedCount: number` Number of contacts that were corrected during verification. - `failedCount: number` Number of contacts that failed verification. - `verifiedCount: number` Number of contacts that were verified without changes. - `status: "validating" or "completed" or "changes_required"` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updatedAt: string` The UTC time at which this resource was last updated. - `validRowCount: number` Number of valid rows processed from the file. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `reportURL: optional string` A temporary URL to download the processing report, available once the import is completed. - `senderStatusCount: optional VerificationStatusCount` Count of contact verification statuses. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_list_imports/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 **get** `/print-mail/v1/mailing_list_imports/{id}` Retrieve a specific mailing list import by its ID. ### Path Parameters - `id: string` ### Returns - `MailingListImportResponse = object { id, createdAt, errors, 13 more }` Read-only view of a MailingListImport - `id: string` A unique ID prefixed with mailing_list_import_ - `createdAt: string` The UTC time at which this resource was created. - `errors: array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "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: object { fileType, receiverAddressMapping, url, 3 more }` The file object your controller returns: all the mappings plus a signed URL. - `fileType: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiverAddressMapping: map[string]` 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: string` The signed URL your controller generates. - `receiverMergeVariableMapping: optional map[string]` Optional mapping of columns for receiver merge variables. - `senderAddressMapping: optional map[string]` Optional mapping of columns for sender addresses. - `senderMergeVariableMapping: optional map[string]` Optional mapping of columns for sender merge variables. - `invalidRowCount: number` Number of invalid rows found in the file. - `live: boolean` `true` if this is a live mode resource else `false`. - `notes: array of object { message, type }` Additional notes about the import process. - `message: string` A human-readable message describing the note. - `type: "truncated_test_file" or "skipped_invalid_contacts"` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: string` The organization that owns this import. - `receiverStatusCount: VerificationStatusCount` Count of contact verification statuses. - `correctedCount: number` Number of contacts that were corrected during verification. - `failedCount: number` Number of contacts that failed verification. - `verifiedCount: number` Number of contacts that were verified without changes. - `status: "validating" or "completed" or "changes_required"` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updatedAt: string` The UTC time at which this resource was last updated. - `validRowCount: number` Number of valid rows processed from the file. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `reportURL: optional string` A temporary URL to download the processing report, available once the import is completed. - `senderStatusCount: optional VerificationStatusCount` Count of contact verification statuses. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_list_imports/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with mailing_list_import_ - `deleted: true` - `true` ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_list_imports/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "mailing_list_import_123", "deleted": true } ``` ## Domain Types ### File Type - `FileType = "csv"` Type of file supported for mailing list imports. - `"csv"` ### Mailing List Import Response - `MailingListImportResponse = object { id, createdAt, errors, 13 more }` Read-only view of a MailingListImport - `id: string` A unique ID prefixed with mailing_list_import_ - `createdAt: string` The UTC time at which this resource was created. - `errors: array of object { message, type }` A list of processing errors encountered, if any. Present when status is 'changes_required'. - `message: string` A human-readable message describing the error. - `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "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: object { fileType, receiverAddressMapping, url, 3 more }` The file object your controller returns: all the mappings plus a signed URL. - `fileType: FileType` Type of file supported for mailing list imports. - `"csv"` - `receiverAddressMapping: map[string]` 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: string` The signed URL your controller generates. - `receiverMergeVariableMapping: optional map[string]` Optional mapping of columns for receiver merge variables. - `senderAddressMapping: optional map[string]` Optional mapping of columns for sender addresses. - `senderMergeVariableMapping: optional map[string]` Optional mapping of columns for sender merge variables. - `invalidRowCount: number` Number of invalid rows found in the file. - `live: boolean` `true` if this is a live mode resource else `false`. - `notes: array of object { message, type }` Additional notes about the import process. - `message: string` A human-readable message describing the note. - `type: "truncated_test_file" or "skipped_invalid_contacts"` Type of note attached to the import process. - `"truncated_test_file"` - `"skipped_invalid_contacts"` - `organization: string` The organization that owns this import. - `receiverStatusCount: VerificationStatusCount` Count of contact verification statuses. - `correctedCount: number` Number of contacts that were corrected during verification. - `failedCount: number` Number of contacts that failed verification. - `verifiedCount: number` Number of contacts that were verified without changes. - `status: "validating" or "completed" or "changes_required"` Status of the mailing list import process. - `"validating"` - `"completed"` - `"changes_required"` - `updatedAt: string` The UTC time at which this resource was last updated. - `validRowCount: number` Number of valid rows processed from the file. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. - `reportURL: optional string` A temporary URL to download the processing report, available once the import is completed. - `senderStatusCount: optional VerificationStatusCount` Count of contact verification statuses. ### Verification Status Count - `VerificationStatusCount = object { correctedCount, failedCount, verifiedCount }` Count of contact verification statuses. - `correctedCount: number` Number of contacts that were corrected during verification. - `failedCount: number` Number of contacts that failed verification. - `verifiedCount: number` Number of contacts that were verified without changes. # Mailing Lists ## Create Mailing List **post** `/print-mail/v1/mailing_lists` Create a new mailing list. ### Header Parameters - `"idempotency-key": optional string` ### Body Parameters - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. ### Returns - `MailingList = object { id, createdAt, live, 5 more }` Represents a mailing list. - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. - `message: string` A human-readable message describing the error. - `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "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 map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 **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. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of MailingList` - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. - `message: string` A human-readable message describing the error. - `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "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 map[unknown]` See the section on Metadata. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/mailing_lists/{id}` Retrieve a specific mailing list by its ID. ### Path Parameters - `id: string` ### Returns - `MailingList = object { id, createdAt, live, 5 more }` Represents a mailing list. - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. - `message: string` A human-readable message describing the error. - `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "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 map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **post** `/print-mail/v1/mailing_lists/{id}` Update an existing mailing list. ### Path Parameters - `id: string` ### Body Parameters - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. ### Returns - `MailingListUpdate = object { description, metadata }` Parameters for updating an existing mailing list. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### Response ```json { "description": "Test Mailing List", "metadata": { "campaign": "launch" } } ``` ## Delete Mailing List **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. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with mailing_list_ - `deleted: true` - `true` ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "mailing_list_sqF12lZ1VlBb", "deleted": true } ``` ## Submit a Mailing List Job **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. ### Path Parameters - `id: string` ### Body Parameters - `addContacts: optional array of string` List of contact IDs to add to the mailing list. Cannot be used with other operations. - `addMailingListImports: optional array of string` List of mailing list import IDs to add to the mailing list. Cannot be used with other operations. - `removeContacts: optional array of string` List of contact IDs to remove from the mailing list. Cannot be used with other operations. - `removeMailingListImports: optional array of string` List of mailing list import IDs to remove from the mailing list. Cannot be used with other operations. ### Returns - `MailingList = object { id, createdAt, live, 5 more }` Represents a mailing list. - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. - `message: string` A human-readable message describing the error. - `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "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 map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID/jobs \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 - `MailingList = object { id, createdAt, live, 5 more }` Represents a mailing list. - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` A list of processing errors encountered, if any. - `message: string` A human-readable message describing the error. - `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "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 map[unknown]` See the section on Metadata. ### Mailing List Update - `MailingListUpdate = object { description, metadata }` Parameters for updating an existing mailing list. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: optional map[unknown]` See the section on Metadata. # Order Profiles # Cheques ## Create Cheque Profile **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`. ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Body Parameters - `bankAccount: string` 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"` - `currencyCode: optional CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `letterPDF: optional string` PDF file for an optional attached letter. Cannot be used with `letterHTML` or `letterTemplate`. Input only. - `letterTemplate: optional string` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `logo: optional string` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string` Memo line text for the cheque. Set to `null` to remove during update. - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `message: optional string` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: optional map[string]` Optional key-value metadata. ### Returns - `ChequeProfile = object { id, bankAccount, createdAt, 14 more }` - `id: string` Unique identifier for the order profile. - `bankAccount: string` ID of the bank account to use for the cheque. Required for creation. - `createdAt: string` Timestamp when the profile was created. - `currencyCode: CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "cheque_profile"` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `letterTemplate: optional string` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letterUploadedPDF: optional string` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: optional string` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string` Memo line text for the cheque. Set to `null` to remove during update. - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `message: optional string` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: optional map[string]` Optional key-value metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/cheques \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "bankAccount": "bankAccount", "size": "us_letter" }' ``` #### 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 **get** `/print-mail/v1/order_profiles/cheques` Retrieves a list of Cheque Profiles. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of object { id, bankAccount, createdAt, 13 more }` - `id: string` Unique identifier for the order profile. - `bankAccount: string` ID of the bank account to use for the cheque. Required for creation. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "cheque_profile"` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `letterTemplate: optional string` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letterUploadedPDF: optional string` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: optional string` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string` Memo line text for the cheque. Set to `null` to remove during update. - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `message: optional string` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: optional map[string]` Optional key-value metadata. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/cheques \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/order_profiles/cheques/{id}` Retrieves the details of a specific Cheque Profile. ### Path Parameters - `id: string` ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Returns - `ChequeProfile = object { id, bankAccount, createdAt, 14 more }` - `id: string` Unique identifier for the order profile. - `bankAccount: string` ID of the bank account to use for the cheque. Required for creation. - `createdAt: string` Timestamp when the profile was created. - `currencyCode: CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "cheque_profile"` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `letterTemplate: optional string` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letterUploadedPDF: optional string` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: optional string` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string` Memo line text for the cheque. Set to `null` to remove during update. - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `message: optional string` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: optional map[string]` Optional key-value metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/cheques/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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`. ### Path Parameters - `id: string` ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Body Parameters - `bankAccount: string` 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"` - `currencyCode: optional CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `letterPDF: optional string` PDF file for an optional attached letter. Cannot be used with `letterHTML` or `letterTemplate`. Input only. - `letterTemplate: optional string` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `logo: optional string` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string` Memo line text for the cheque. Set to `null` to remove during update. - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `message: optional string` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: optional map[string]` Optional key-value metadata. ### Returns - `ChequeProfile = object { id, bankAccount, createdAt, 14 more }` - `id: string` Unique identifier for the order profile. - `bankAccount: string` ID of the bank account to use for the cheque. Required for creation. - `createdAt: string` Timestamp when the profile was created. - `currencyCode: CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "cheque_profile"` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `letterTemplate: optional string` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letterUploadedPDF: optional string` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: optional string` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string` Memo line text for the cheque. Set to `null` to remove during update. - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `message: optional string` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: optional map[string]` Optional key-value metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/cheques/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "bankAccount": "bankAccount", "size": "us_letter" }' ``` #### 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 **delete** `/print-mail/v1/order_profiles/cheques/{id}` Deletes a Cheque Profile. ### Path Parameters - `id: string` ### Returns - `id: string` Unique identifier for the order profile. - `deleted: true` - `true` - `object: "cheque_profile"` Always `cheque_profile`. - `"cheque_profile"` ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/cheques/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "cheque_profile_789", "object": "cheque_profile", "deleted": true } ``` ## Domain Types ### Cheque Profile - `ChequeProfile = object { id, bankAccount, createdAt, 14 more }` - `id: string` Unique identifier for the order profile. - `bankAccount: string` ID of the bank account to use for the cheque. Required for creation. - `createdAt: string` Timestamp when the profile was created. - `currencyCode: CurrencyCode` Enum representing the supported currency codes. - `"CAD"` - `"USD"` - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "cheque_profile"` Always `cheque_profile`. - `"cheque_profile"` - `size: ChequeSize` Enum representing the supported cheque sizes. - `"us_letter"` - `"us_legal"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `letterTemplate: optional string` ID of a template for an optional attached letter. Cannot be used with `letterHTML` or `letterPDF`. - `letterUploadedPDF: optional string` A temporary, signed URL to view the attached letter PDF, if any. Output only. - `logo: optional string` A publicly accessible URL for the logo to print on the cheque. Set to `null` to remove during update. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string` Memo line text for the cheque. Set to `null` to remove during update. - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `message: optional string` Message included on the cheque stub. Set to `null` to remove during update. - `metadata: optional map[string]` Optional key-value metadata. ### Currency Code - `CurrencyCode = "CAD" or "USD"` Enum representing the supported currency codes. - `"CAD"` - `"USD"` # Letters ## Create Letter Profile **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`. ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Body Parameters - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `addressPlacement: optional AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `color: optional boolean` Specifies whether to print in color (true) or black and white (false). - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `doubleSided: optional boolean` Specifies whether to print on both sides of the paper. - `envelope: optional string` ID of a custom envelope to use. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `pdf: optional string` A PDF file containing the letter content. Cannot be used with `template`. - `perforatedPage: optional 1` Specifies which page number should be perforated (if any). - `1` - `returnEnvelope: optional string` ID of a return envelope to include. - `template: optional string` ID of a template to use for the letter content. Cannot be used with `pdf`. ### Returns - `LetterProfile = object { id, createdAt, live, 15 more }` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "letter_profile"` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updatedAt: string` Timestamp when the profile was last updated. - `addressPlacement: optional AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `color: optional boolean` Specifies whether to print in color (true) or black and white (false). - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `doubleSided: optional boolean` Specifies whether to print on both sides of the paper. - `envelope: optional string` ID of a custom envelope to use. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `perforatedPage: optional 1` Specifies which page number should be perforated (if any). - `1` - `template: optional string` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/letters \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "size": "us_letter" }' ``` #### 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 **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. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of LetterProfile` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "letter_profile"` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updatedAt: string` Timestamp when the profile was last updated. - `addressPlacement: optional AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `color: optional boolean` Specifies whether to print in color (true) or black and white (false). - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `doubleSided: optional boolean` Specifies whether to print on both sides of the paper. - `envelope: optional string` ID of a custom envelope to use. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `perforatedPage: optional 1` Specifies which page number should be perforated (if any). - `1` - `template: optional string` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/letters \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/order_profiles/letters/{id}` Retrieves the details of a specific Letter Profile by its ID. ### Path Parameters - `id: string` ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Returns - `LetterProfile = object { id, createdAt, live, 15 more }` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "letter_profile"` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updatedAt: string` Timestamp when the profile was last updated. - `addressPlacement: optional AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `color: optional boolean` Specifies whether to print in color (true) or black and white (false). - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `doubleSided: optional boolean` Specifies whether to print on both sides of the paper. - `envelope: optional string` ID of a custom envelope to use. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `perforatedPage: optional 1` Specifies which page number should be perforated (if any). - `1` - `template: optional string` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/letters/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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`. ### Path Parameters - `id: string` ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Body Parameters - `addressPlacement: optional AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `color: optional boolean` Specifies whether to print in color (true) or black and white (false). - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `doubleSided: optional boolean` Specifies whether to print on both sides of the paper. - `envelope: optional string` ID of a custom envelope to use. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `pdf: optional string` A PDF file containing the letter content. Cannot be used with `template`. - `perforatedPage: optional 1` Specifies which page number should be perforated (if any). - `1` - `returnEnvelope: optional string` ID of a return envelope to include. - `template: optional string` ID of a template to use for the letter content. Cannot be used with `pdf`. ### Returns - `LetterProfile = object { id, createdAt, live, 15 more }` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "letter_profile"` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updatedAt: string` Timestamp when the profile was last updated. - `addressPlacement: optional AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `color: optional boolean` Specifies whether to print in color (true) or black and white (false). - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `doubleSided: optional boolean` Specifies whether to print on both sides of the paper. - `envelope: optional string` ID of a custom envelope to use. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `perforatedPage: optional 1` Specifies which page number should be perforated (if any). - `1` - `template: optional string` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/letters/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 **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. ### Path Parameters - `id: string` ### Returns - `id: string` Unique identifier for the order profile. - `deleted: true` - `true` - `object: "letter_profile"` Always `letter_profile`. - `"letter_profile"` ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/letters/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "letter_profile_123", "object": "letter_profile", "deleted": true } ``` ## Domain Types ### Letter Profile - `LetterProfile = object { id, createdAt, live, 15 more }` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "letter_profile"` Always `letter_profile`. - `"letter_profile"` - `size: LetterSize` Enum representing the supported letter sizes. - `"us_letter"` - `"a4"` - `updatedAt: string` Timestamp when the profile was last updated. - `addressPlacement: optional AddressPlacement` Enum representing the placement of the address on the letter. - `"top_first_page"` - `"insert_blank_page"` - `attachedPDF: optional AttachedPdf` Model representing an attached PDF. - `file: string` The file (multipart form upload) or URL pointing to a PDF for the attached PDF. - `placement: "before_template" or "after_template"` Enum representing the placement of the attached PDF. - `"before_template"` - `"after_template"` - `color: optional boolean` Specifies whether to print in color (true) or black and white (false). - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `doubleSided: optional boolean` Specifies whether to print on both sides of the paper. - `envelope: optional string` ID of a custom envelope to use. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `perforatedPage: optional 1` Specifies which page number should be perforated (if any). - `1` - `template: optional string` ID of a template to use for the letter content. Cannot be used with `pdf`. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. # Postcards ## Create Postcard Profile **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`. ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Body Parameters - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `backTemplate: optional string` ID of the template for the back side. Required unless `pdf` is provided. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `frontTemplate: optional string` ID of the template for the front side. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `pdf: optional string` A 2-page PDF file containing the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`. ### Returns - `PostcardProfile = object { id, createdAt, live, 10 more }` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "postcard_profile"` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updatedAt: string` Timestamp when the profile was last updated. - `backTemplate: optional string` ID of the template for the back side. Required unless `pdf` is provided. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `frontTemplate: optional string` ID of the template for the front side. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF content, if any. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/postcards \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "size": "6x4" }' ``` #### 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 **get** `/print-mail/v1/order_profiles/postcards` Retrieves a list of Postcard Profiles. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of PostcardProfile` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "postcard_profile"` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updatedAt: string` Timestamp when the profile was last updated. - `backTemplate: optional string` ID of the template for the back side. Required unless `pdf` is provided. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `frontTemplate: optional string` ID of the template for the front side. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF content, if any. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/postcards \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/order_profiles/postcards/{id}` Retrieves the details of a specific Postcard Profile. ### Path Parameters - `id: string` ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Returns - `PostcardProfile = object { id, createdAt, live, 10 more }` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "postcard_profile"` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updatedAt: string` Timestamp when the profile was last updated. - `backTemplate: optional string` ID of the template for the back side. Required unless `pdf` is provided. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `frontTemplate: optional string` ID of the template for the front side. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF content, if any. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/postcards/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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`. ### Path Parameters - `id: string` ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Body Parameters - `backTemplate: optional string` ID of the template for the back side. Required unless `pdf` is provided. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `frontTemplate: optional string` ID of the template for the front side. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `pdf: optional string` A 2-page PDF file containing the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`. ### Returns - `PostcardProfile = object { id, createdAt, live, 10 more }` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "postcard_profile"` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updatedAt: string` Timestamp when the profile was last updated. - `backTemplate: optional string` ID of the template for the back side. Required unless `pdf` is provided. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `frontTemplate: optional string` ID of the template for the front side. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF content, if any. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/postcards/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 **delete** `/print-mail/v1/order_profiles/postcards/{id}` Deletes a Postcard Profile. ### Path Parameters - `id: string` ### Returns - `id: string` Unique identifier for the order profile. - `deleted: true` - `true` - `object: "postcard_profile"` Always `postcard_profile`. - `"postcard_profile"` ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/postcards/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "postcard_profile_456", "object": "postcard_profile", "deleted": true } ``` ## Domain Types ### Postcard Profile - `PostcardProfile = object { id, createdAt, live, 10 more }` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "postcard_profile"` Always `postcard_profile`. - `"postcard_profile"` - `size: PostcardSize` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` - `updatedAt: string` Timestamp when the profile was last updated. - `backTemplate: optional string` ID of the template for the back side. Required unless `pdf` is provided. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `frontTemplate: optional string` ID of the template for the front side. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF content, if any. ### Postcard Size - `PostcardSize = "6x4" or "9x6" or "11x6"` Enum representing the supported postcard sizes. - `"6x4"` - `"9x6"` - `"11x6"` # Self Mailers ## Create Self-Mailer Profile **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`. ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Body Parameters - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `insideTemplate: optional string` ID of the template for the inside. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `outsideTemplate: optional string` ID of the template for the outside. Required unless `pdf` is provided. - `pdf: optional string` A 2-page PDF file containing the self-mailer content (inside and outside). Cannot be used with `insideTemplate`/`outsideTemplate`. ### Returns - `SelfMailerProfile = object { id, createdAt, live, 10 more }` Represents a Self-Mailer Profile resource. - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "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"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `insideTemplate: optional string` ID of the template for the inside. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `outsideTemplate: optional string` ID of the template for the outside. Required unless `pdf` is provided. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/self_mailers \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "size": "8.5x11_bifold" }' ``` #### 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 **get** `/print-mail/v1/order_profiles/self_mailers` Retrieves a list of Self-Mailer Profiles. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of SelfMailerProfile` - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "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"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `insideTemplate: optional string` ID of the template for the inside. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `outsideTemplate: optional string` ID of the template for the outside. Required unless `pdf` is provided. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/self_mailers \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/order_profiles/self_mailers/{id}` Retrieves the details of a specific Self-Mailer Profile. ### Path Parameters - `id: string` ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Returns - `SelfMailerProfile = object { id, createdAt, live, 10 more }` Represents a Self-Mailer Profile resource. - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "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"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `insideTemplate: optional string` ID of the template for the inside. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `outsideTemplate: optional string` ID of the template for the outside. Required unless `pdf` is provided. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/self_mailers/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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`. ### Path Parameters - `id: string` ### Query Parameters - `expand: optional array of string` Optional list of related resources to expand in the response. ### Body Parameters - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `insideTemplate: optional string` ID of the template for the inside. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `outsideTemplate: optional string` ID of the template for the outside. Required unless `pdf` is provided. - `pdf: optional string` A 2-page PDF file containing the self-mailer content (inside and outside). Cannot be used with `insideTemplate`/`outsideTemplate`. ### Returns - `SelfMailerProfile = object { id, createdAt, live, 10 more }` Represents a Self-Mailer Profile resource. - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "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"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `insideTemplate: optional string` ID of the template for the inside. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `outsideTemplate: optional string` ID of the template for the outside. Required unless `pdf` is provided. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/self_mailers/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "size": "8.5x11_bifold" }' ``` #### 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 **delete** `/print-mail/v1/order_profiles/self_mailers/{id}` Deletes a Self-Mailer Profile. ### Path Parameters - `id: string` ### Returns - `id: string` Unique identifier for the order profile. - `deleted: true` - `true` - `object: "self_mailer_profile"` Always `self_mailer_profile`. - `"self_mailer_profile"` ### Example ```http curl https://api.postgrid.com/print-mail/v1/order_profiles/self_mailers/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "self_mailer_profile_101", "object": "self_mailer_profile", "deleted": true } ``` ## Domain Types ### Self Mailer Profile - `SelfMailerProfile = object { id, createdAt, live, 10 more }` Represents a Self-Mailer Profile resource. - `id: string` Unique identifier for the order profile. - `createdAt: string` Timestamp when the profile was created. - `live: boolean` Indicates if the profile is associated with the live or test environment. - `object: "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"` - `updatedAt: string` Timestamp when the profile was last updated. - `description: optional string` An optional description for the profile. Set to `null` to remove during update. - `insideTemplate: optional string` ID of the template for the inside. Required unless `pdf` is provided. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` Default merge variables for orders created using this profile. - `metadata: optional map[string]` Optional key-value metadata. - `outsideTemplate: optional string` ID of the template for the outside. Required unless `pdf` is provided. - `uploadedPDF: optional string` A temporary, signed URL to view the uploaded PDF, if any. ### Self Mailer Size - `SelfMailerSize = "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"` Enum representing the supported self-mailer sizes. - `"8.5x11_bifold"` - `"8.5x11_trifold"` - `"9.5x16_trifold"` # Postcards ## Create 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 ### Body Parameters - `body: object { backHTML, frontHTML, size, 7 more } or object { backTemplate, frontTemplate } or object { pdf, size, to, 6 more } or object { pdf, size, to, 6 more }` - `PostcardCreateWithHTML = object { backHTML, frontHTML, size, 7 more }` - `backHTML: string` The HTML content for the back of the postcard. You can supply _either_ this or `backTemplate` but not both. - `frontHTML: string` 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: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `addressLine1: string` The first line of the contact's address. - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `firstName: string` - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `addressLine1: string` The first line of the contact's address. - `companyName: string` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `string` - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `from: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `sendDate: optional string` 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. - `PostcardCreateWithTemplate = object { backTemplate, frontTemplate }` - `backTemplate: string` The template ID for the back of the postcard. You can supply _either_ this or `backHTML` but not both. - `frontTemplate: string` The template ID for the front of the postcard. You can supply _either_ this or `frontHTML` but not both. - `PostcardCreateWithPdfurl = object { pdf, size, to, 6 more }` - `pdf: string` A URL pointing to a 2 page PDF file. The first page is the front of the postcard and the second page is the back (where the address will be stamped on). - `size: PostcardSize` Enum representing the supported postcard sizes. - `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `from: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `sendDate: optional string` 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. - `PostcardCreateWithPdfFile = object { pdf, size, to, 6 more }` - `pdf: string` A 2 page PDF file. The first page is the front of the postcard and the second page is the back (where the address will be stamped on). - `size: PostcardSize` Enum representing the supported postcard sizes. - `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `from: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `sendDate: optional string` 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 - `Postcard = object { id, createdAt, live, 17 more }` - `id: string` A unique ID prefixed with postcard_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "postcard"` Always `postcard`. - `"postcard"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `from: optional Contact` The contact information of the sender. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/postcards \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "backHTML": "backHTML", "frontHTML": "frontHTML", "size": "6x4", "to": { "addressLine1": "addressLine1", "countryCode": "countryCode", "firstName": "firstName" } }' ``` #### 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 **get** `/print-mail/v1/postcards` Get a list of postcards. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of Postcard` - `id: string` A unique ID prefixed with postcard_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "postcard"` Always `postcard`. - `"postcard"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `from: optional Contact` The contact information of the sender. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/postcards \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/postcards/{id}` Retrieve a postcard by ID. ### Path Parameters - `id: string` ### Returns - `Postcard = object { id, createdAt, live, 17 more }` - `id: string` A unique ID prefixed with postcard_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "postcard"` Always `postcard`. - `"postcard"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `from: optional Contact` The contact information of the sender. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/postcards/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **delete** `/print-mail/v1/postcards/{id}` Cancel a postcard by ID. Note that this operation cannot be undone. ### Path Parameters - `id: string` ### Returns - `Postcard = object { id, createdAt, live, 17 more }` - `id: string` A unique ID prefixed with postcard_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "postcard"` Always `postcard`. - `"postcard"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `from: optional Contact` The contact information of the sender. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/postcards/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with postcard_ - `object: string` - `url: string` A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call. ### Example ```http curl https://api.postgrid.com/print-mail/v1/postcards/$ID/url \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 - `Postcard = object { id, createdAt, live, 17 more }` - `id: string` A unique ID prefixed with postcard_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "postcard"` Always `postcard`. - `"postcard"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `from: optional Contact` The contact information of the sender. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 **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. ### Body Parameters - `sqlQuery: string` The SQL query defining the report. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. ### Returns - `Report = object { id, createdAt, live, 5 more }` Represents a saved Report definition. - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?" }' ``` #### 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 **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. ### Body Parameters - `sqlQuery: string` The SQL query to execute for the sample. - `limit: optional number` Maximum number of rows to return in the sample. - `params: optional array of string` Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1). ### Returns - `ReportSample = object { id, records, report }` Represents the result of a report sample query. - `id: string` Unique identifier for the sample query result. - `records: array of map[unknown]` The actual data records returned by the sample query. - `report: string` The ID of the report this sample was generated from, or null for ad-hoc samples. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/samples \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "sqlQuery": "sqlQuery" }' ``` #### Response ```json { "id": "sample_abc", "report": "report_123", "records": [ { "id": "order_1" }, { "id": "order_2" } ] } ``` ## Update Report **post** `/print-mail/v1/reports/{id}` Update an existing saved report definition. You can change the query, description, or metadata. ### Path Parameters - `id: string` ### Body Parameters - `description: optional string` An optional user-friendly description for the report. Set to null to remove. - `metadata: optional map[string]` Optional key-value metadata associated with the report. Set to null to remove. - `sqlQuery: optional string` The SQL query defining the report. ### Returns - `Report = object { id, createdAt, live, 5 more }` Represents a saved Report definition. - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 **get** `/print-mail/v1/reports` Retrieve a list of saved reports for your organization. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of Report` - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/reports/{id}` Retrieve the details of a specific saved report by its ID. ### Path Parameters - `id: string` ### Returns - `Report = object { id, createdAt, live, 5 more }` Represents a saved Report definition. - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **delete** `/print-mail/v1/reports/{id}` Delete a saved report definition. This action cannot be undone. Associated exports are not automatically deleted. ### Path Parameters - `id: string` ### Returns - `DeletedResponse = object { id, deleted }` Generic response for delete operations. - `id: string` The ID of the deleted resource. - `deleted: true` Indicates the resource was successfully deleted. - `true` ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "report_123", "deleted": true } ``` ## Domain Types ### Deleted Response - `DeletedResponse = object { id, deleted }` Generic response for delete operations. - `id: string` The ID of the deleted resource. - `deleted: true` Indicates the resource was successfully deleted. - `true` ### Report - `Report = object { id, createdAt, live, 5 more }` Represents a saved Report definition. - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. # Samples ## Sample a Saved Report **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. ### Path Parameters - `id: string` ### Body Parameters - `limit: optional number` Maximum number of rows to return in the sample. - `params: optional array of string` Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1). ### Returns - `ReportSample = object { id, records, report }` Represents the result of a report sample query. - `id: string` Unique identifier for the sample query result. - `records: array of map[unknown]` The actual data records returned by the sample query. - `report: string` The ID of the report this sample was generated from, or null for ad-hoc samples. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$ID/samples \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "sample_abc", "report": "report_123", "records": [ { "id": "order_1" }, { "id": "order_2" } ] } ``` ## Domain Types ### Report Sample - `ReportSample = object { id, records, report }` Represents the result of a report sample query. - `id: string` Unique identifier for the sample query result. - `records: array of map[unknown]` The actual data records returned by the sample query. - `report: string` The ID of the report this sample was generated from, or null for ad-hoc samples. ### Report Sample Create Base - `ReportSampleCreateBase = object { limit, params }` Base properties for creating a report sample. - `limit: optional number` Maximum number of rows to return in the sample. - `params: optional array of string` Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1). # Exports ## Create a Report Export **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. ### Path Parameters - `reportID: string` ### Body Parameters - `description: optional string` An optional user-friendly description for the export. - `metadata: optional map[string]` Optional key-value metadata associated with the export. - `params: optional array of string` Optional parameters to bind to the SQL query of the associated report. ### Returns - `ReportExport = object { id, createdAt, live, 11 more }` Represents a report export job and its results. - `id: string` Unique identifier for the report export. - `createdAt: string` Timestamp when the export was created. - `live: boolean` Indicates if the export is associated with the live or test environment. - `object: "report_export"` Always `report_export`. - `"report_export"` - `report: object { id, sqlQuery }` Details of the report this export was generated from. - `id: string` The ID of the report. - `sqlQuery: string` The SQL query used for this export (snapshotted at creation time). - `updatedAt: string` Timestamp when the export was last updated (e.g., finished generation). - `description: optional string` An optional user-friendly description for the export. - `failureMessage: optional string` If export generation failed, this contains the error message. - `metadata: optional map[string]` Optional key-value metadata associated with the export. - `outputURL: optional string` A signed URL to download the exported data (CSV format). Available when generation is complete and successful. - `params: optional array of string` Optional parameters to bind to the SQL query of the associated report. - `rowCount: optional number` The number of rows in the exported data. - `sizeInBytes: optional number` The size of the generated export file in bytes. - `truncatedToBytes: optional number` If the output was truncated, indicates the byte limit reached. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$REPORT_ID/exports \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 **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. ### Path Parameters - `reportID: string` - `exportID: string` ### Returns - `ReportExport = object { id, createdAt, live, 11 more }` Represents a report export job and its results. - `id: string` Unique identifier for the report export. - `createdAt: string` Timestamp when the export was created. - `live: boolean` Indicates if the export is associated with the live or test environment. - `object: "report_export"` Always `report_export`. - `"report_export"` - `report: object { id, sqlQuery }` Details of the report this export was generated from. - `id: string` The ID of the report. - `sqlQuery: string` The SQL query used for this export (snapshotted at creation time). - `updatedAt: string` Timestamp when the export was last updated (e.g., finished generation). - `description: optional string` An optional user-friendly description for the export. - `failureMessage: optional string` If export generation failed, this contains the error message. - `metadata: optional map[string]` Optional key-value metadata associated with the export. - `outputURL: optional string` A signed URL to download the exported data (CSV format). Available when generation is complete and successful. - `params: optional array of string` Optional parameters to bind to the SQL query of the associated report. - `rowCount: optional number` The number of rows in the exported data. - `sizeInBytes: optional number` The size of the generated export file in bytes. - `truncatedToBytes: optional number` If the output was truncated, indicates the byte limit reached. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$REPORT_ID/exports/$EXPORT_ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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. ### Path Parameters - `reportID: string` - `exportID: string` ### Returns - `DeletedResponse = object { id, deleted }` Generic response for delete operations. - `id: string` The ID of the deleted resource. - `deleted: true` Indicates the resource was successfully deleted. - `true` ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$REPORT_ID/exports/$EXPORT_ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "report_export_123", "deleted": true } ``` ## Domain Types ### Report Export - `ReportExport = object { id, createdAt, live, 11 more }` Represents a report export job and its results. - `id: string` Unique identifier for the report export. - `createdAt: string` Timestamp when the export was created. - `live: boolean` Indicates if the export is associated with the live or test environment. - `object: "report_export"` Always `report_export`. - `"report_export"` - `report: object { id, sqlQuery }` Details of the report this export was generated from. - `id: string` The ID of the report. - `sqlQuery: string` The SQL query used for this export (snapshotted at creation time). - `updatedAt: string` Timestamp when the export was last updated (e.g., finished generation). - `description: optional string` An optional user-friendly description for the export. - `failureMessage: optional string` If export generation failed, this contains the error message. - `metadata: optional map[string]` Optional key-value metadata associated with the export. - `outputURL: optional string` A signed URL to download the exported data (CSV format). Available when generation is complete and successful. - `params: optional array of string` Optional parameters to bind to the SQL query of the associated report. - `rowCount: optional number` The number of rows in the exported data. - `sizeInBytes: optional number` The size of the generated export file in bytes. - `truncatedToBytes: optional number` If the output was truncated, indicates the byte limit reached. # Self Mailers ## Create Self Mailer **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 ### Body Parameters - `body: object { from, insideHTML, outsideHTML, 7 more } or object { insideTemplate, outsideTemplate } or object { from, pdf, size, 6 more } or object { from, pdf, size, 6 more }` - `SelfMailerCreateWithHTML = object { from, insideHTML, outsideHTML, 7 more }` - `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `addressLine1: string` The first line of the contact's address. - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `firstName: string` - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `addressLine1: string` The first line of the contact's address. - `companyName: string` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `string` - `insideHTML: string` The HTML content for the inside of the self-mailer. You can supply _either_ this or `insideTemplate` but not both. - `outsideHTML: string` 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: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `sendDate: optional string` 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. - `SelfMailerCreateWithTemplate = object { insideTemplate, outsideTemplate }` - `insideTemplate: string` The template ID for the inside of the self-mailer. You can supply _either_ this or `insideHTML` but not both. - `outsideTemplate: string` The template ID for the outside of the self-mailer. You can supply _either_ this or `outsideHTML` but not both. - `SelfMailerCreateWithPdfurl = object { from, pdf, size, 6 more }` - `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `pdf: string` A URL pointing to a 2 page PDF file. The first page is the inside of the self-mailer and the second page is the outside (where the address will be stamped on). - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `sendDate: optional string` 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. - `SelfMailerCreateWithPdfFile = object { from, pdf, size, 6 more }` - `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` The contact information of the sender. You can pass contact information inline here just like you can for the `to`. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `pdf: string` A 2 page PDF file. The first page is the inside of the self-mailer and the second page is the outside (where the address will be stamped on). - `size: SelfMailerSize` Enum representing the supported self-mailer sizes. - `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string` 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. - `ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }` - `ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }` - `string` - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `mailingClass: optional "first_class" or "standard_class" or "express" or 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"` - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `sendDate: optional string` 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 - `SelfMailer = object { id, createdAt, from, 17 more }` - `id: string` A unique ID prefixed with self_mailer_ - `createdAt: string` The UTC time at which this resource was created. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "self_mailer"` Always `self_mailer`. - `"self_mailer"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/self_mailers \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "from": { "addressLine1": "addressLine1", "countryCode": "countryCode", "firstName": "firstName" }, "insideHTML": "insideHTML", "outsideHTML": "outsideHTML", "size": "8.5x11_bifold", "to": { "addressLine1": "addressLine1", "countryCode": "countryCode", "firstName": "firstName" } }' ``` #### 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 **get** `/print-mail/v1/self_mailers` Get a list of self-mailers. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of SelfMailer` - `id: string` A unique ID prefixed with self_mailer_ - `createdAt: string` The UTC time at which this resource was created. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "self_mailer"` Always `self_mailer`. - `"self_mailer"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/self_mailers \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/self_mailers/{id}` Retrieve a self-mailer by ID. ### Path Parameters - `id: string` ### Returns - `SelfMailer = object { id, createdAt, from, 17 more }` - `id: string` A unique ID prefixed with self_mailer_ - `createdAt: string` The UTC time at which this resource was created. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "self_mailer"` Always `self_mailer`. - `"self_mailer"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/self_mailers/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **delete** `/print-mail/v1/self_mailers/{id}` Cancel a self-mailer by ID. Note that this operation cannot be undone. ### Path Parameters - `id: string` ### Returns - `SelfMailer = object { id, createdAt, from, 17 more }` - `id: string` A unique ID prefixed with self_mailer_ - `createdAt: string` The UTC time at which this resource was created. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "self_mailer"` Always `self_mailer`. - `"self_mailer"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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 ```http curl https://api.postgrid.com/print-mail/v1/self_mailers/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **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. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with self_mailer_ - `object: string` - `url: string` A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call. ### Example ```http curl https://api.postgrid.com/print-mail/v1/self_mailers/$ID/url \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 - `SelfMailer = object { id, createdAt, from, 17 more }` - `id: string` A unique ID prefixed with self_mailer_ - `createdAt: string` The UTC time at which this resource was created. - `from: Contact` The contact information of the sender. - `id: string` A unique ID prefixed with contact_ - `addressLine1: string` The first line of the contact's address. - `addressStatus: "verified" or "corrected" or "failed"` One of `verified`, `corrected`, or `failed`. - `"verified"` - `"corrected"` - `"failed"` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `addressErrors: optional string` A series of human-readable errors/warnings that were raised when running the provided address through our address verification. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `companyName: optional string` Company name of the contact. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `email: optional string` Email of the contact. - `firstName: optional string` First name of the contact. - `forceVerifiedStatus: optional boolean` If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise. - `jobTitle: optional string` Job title of the contact. - `lastName: optional string` Last name of the contact. - `metadata: optional map[unknown]` See the section on Metadata. - `phoneNumber: optional string` Phone number of the contact. - `postalOrZip: optional string` The postal or ZIP code of the contact's address. - `provinceOrState: optional string` Province or state of the contact's address. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `live: boolean` `true` if this is a live mode resource else `false`. - `mailingClass: "first_class" or "standard_class" or "express" or 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: "self_mailer"` Always `self_mailer`. - `"self_mailer"` - `sendDate: string` 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: "ready" or "printing" or "processed_for_delivery" or 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. - `updatedAt: string` The UTC time at which this resource was last updated. - `cancellation: optional object { reason, cancelledByUser, note }` The cancellation details of this order. Populated if the order has been cancelled. - `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"` The reason for the cancellation. - `"user_initiated"` - `"invalid_content"` - `"invalid_order_mailing_class"` - `cancelledByUser: optional string` The user ID who cancelled the order. - `note: optional string` An optional note provided by the user who cancelled the order. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `imbDate: optional string` The last date that the IMB status was updated. See `imbStatus` for more details. - `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "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"` - `imbZIPCode: optional string` The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present. - `mergeVariables: optional map[unknown]` 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 map[unknown]` See the section on Metadata. - `trackingNumber: optional string` The tracking number of this order. Populated after an express/certified order has been processed for delivery. - `url: optional string` 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. **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. ### Body Parameters - `countryCode: string` The country code of the sub-organization. - `email: string` The email of the user to be created alongside the sub-organization. - `name: string` The name of the user to be created alongside the sub-organization. - `organizationName: string` The name of the sub-organization. - `password: string` The password of the user to be created alongside the sub-organization. - `phoneNumber: optional string` The phone number of the user to be created alongside the sub-organization. ### Returns - `subOrganization: SubOrganization` The Sub-Organization object. - `id: string` A unique ID prefixed with `sub_org_`. - `countryCode: string` The country code of the sub-organization. - `createdAt: string` The UTC time at which this resource was created. - `limit: number` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: string` The name of the sub-organization. - `object: "sub_org"` Always `sub_org`. - `"sub_org"` - `spend: number` The current rolling charge for the sub-organization for the month, in cents. - `updatedAt: string` The UTC time at which this resource was last update. - `usage: number` The amount of mail the sub-organization has sent out this month. - `user: object { id, apiKeys, email, 9 more }` The user object. - `id: string` A unique ID prefixed with `user_`. - `apiKeys: array of object { value, activeUntil }` The user's API keys. Contains live and test mode API keys. - `value: string` The value of the API key. - `activeUntil: optional string` An optional date which the API key is active until. After this date, the API key will no longer be valid. - `email: string` The email of the user. - `name: string` The name of the user. - `organization: string` A unique ID prefixed with `user_`. - `pendingInvite: boolean` Indicates if the user has a pending invite. - `roles: array of string` The roles given to the user. Roles can be used to restrict access for users. - `verifiedEmail: boolean` Indicates if the user has a verified email or not. - `emailPreferences: optional EmailPreferences` A set of preferences for how a user should receive emails. - `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` - `lastLoginTime: optional string` The date and time at which the user last logged in. - `phoneNumber: optional string` The phone number of the user. - `previousEmails: optional array of string` 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 ```http curl https://api.postgrid.com/print-mail/v1/sub_organizations \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "countryCode": "CA", "email": "suborg@postgrid.com", "name": "Calvin", "organizationName": "PostGrid", "password": "very-strong-password" }' ``` #### 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. **get** `/print-mail/v1/sub_organizations` List sub-organizations. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of SubOrganization` - `id: string` A unique ID prefixed with `sub_org_`. - `countryCode: string` The country code of the sub-organization. - `createdAt: string` The UTC time at which this resource was created. - `limit: number` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: string` The name of the sub-organization. - `object: "sub_org"` Always `sub_org`. - `"sub_org"` - `spend: number` The current rolling charge for the sub-organization for the month, in cents. - `updatedAt: string` The UTC time at which this resource was last update. - `usage: number` The amount of mail the sub-organization has sent out this month. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/sub_organizations \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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. **get** `/print-mail/v1/sub_organizations/{id}` Get a sub-organization. ### Path Parameters - `id: string` ### Returns - `SubOrganization = object { id, countryCode, createdAt, 6 more }` The Sub-Organization object. - `id: string` A unique ID prefixed with `sub_org_`. - `countryCode: string` The country code of the sub-organization. - `createdAt: string` The UTC time at which this resource was created. - `limit: number` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: string` The name of the sub-organization. - `object: "sub_org"` Always `sub_org`. - `"sub_org"` - `spend: number` The current rolling charge for the sub-organization for the month, in cents. - `updatedAt: string` The UTC time at which this resource was last update. - `usage: number` The amount of mail the sub-organization has sent out this month. ### Example ```http curl https://api.postgrid.com/print-mail/v1/sub_organizations/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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. **get** `/print-mail/v1/sub_organizations/{id}/users` List users for a sub-organization. ### Path Parameters - `id: string` ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `id: string` A unique ID prefixed with `user_`. - `email: string` The email of the user. - `name: string` The name of the user. - `organization: string` A unique ID prefixed with `user_`. - `pendingInvite: boolean` Indicates if the user has a pending invite. - `roles: array of string` The roles given to the user. Roles can be used to restrict access for users. - `verifiedEmail: boolean` Indicates if the user has a verified email or not. - `emailPreferences: optional EmailPreferences` A set of preferences for how a user should receive emails. - `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` - `lastLoginTime: optional string` The date and time at which the user last logged in. - `phoneNumber: optional string` The phone number of the user. - `previousEmails: optional array of string` 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 ```http curl https://api.postgrid.com/print-mail/v1/sub_organizations/$ID/users \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 - `EmailPreferences = object { orderPreviewSendPreference }` A set of preferences for how a user should receive emails. - `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "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 - `SubOrganization = object { id, countryCode, createdAt, 6 more }` The Sub-Organization object. - `id: string` A unique ID prefixed with `sub_org_`. - `countryCode: string` The country code of the sub-organization. - `createdAt: string` The UTC time at which this resource was created. - `limit: number` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: string` The name of the sub-organization. - `object: "sub_org"` Always `sub_org`. - `"sub_org"` - `spend: number` The current rolling charge for the sub-organization for the month, in cents. - `updatedAt: string` The UTC time at which this resource was last update. - `usage: number` The amount of mail the sub-organization has sent out this month. # Templates ## Create 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. ### Body Parameters - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content of this template. - `metadata: optional map[unknown]` See the section on Metadata. ### Returns - `Template = object { id, createdAt, live, 5 more }` - `id: string` A unique ID prefixed with template_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "template"` Always `template`. - `"template"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content of this template. - `metadata: optional map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/templates \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 **get** `/print-mail/v1/templates` Get a list of templates. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of Template` - `id: string` A unique ID prefixed with template_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "template"` Always `template`. - `"template"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content of this template. - `metadata: optional map[unknown]` See the section on Metadata. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/templates \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **get** `/print-mail/v1/templates/{id}` Retrieve a template by ID. ### Path Parameters - `id: string` ### Returns - `Template = object { id, createdAt, live, 5 more }` - `id: string` A unique ID prefixed with template_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "template"` Always `template`. - `"template"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content of this template. - `metadata: optional map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/templates/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### 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 **post** `/print-mail/v1/templates/{id}` Update a template by ID. ### Path Parameters - `id: string` ### Body Parameters - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content of this template. - `metadata: optional map[unknown]` See the section on Metadata. ### Returns - `Template = object { id, createdAt, live, 5 more }` - `id: string` A unique ID prefixed with template_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "template"` Always `template`. - `"template"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content of this template. - `metadata: optional map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/templates/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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 **delete** `/print-mail/v1/templates/{id}` Delete a template by ID. Note that this operation cannot be undone. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with template_ - `deleted: true` - `true` - `object: "template"` Always `template`. - `"template"` ### Example ```http curl https://api.postgrid.com/print-mail/v1/templates/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "template_sqF12lZ1VlBb", "deleted": true, "object": "template" } ``` ## Domain Types ### Template - `Template = object { id, createdAt, live, 5 more }` - `id: string` A unique ID prefixed with template_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "template"` Always `template`. - `"template"` - `updatedAt: string` The UTC time at which this resource was last updated. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `html: optional string` The HTML content of this template. - `metadata: optional map[unknown]` See the section on Metadata.