{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"30d9da4f-15c3-4b6a-aae1-d3a329dc6b13","name":"PostGrid Print & Mail","description":"A simple API to send letters, postcards, and cheques. You can integrate this API to automate your transactional mailings and/or provide offline sending capabilities to your users.\n\nIf you just want to perform one-off sends, you can also do so directly from the API dashboard at [https://dashboard.postgrid.com](https://dashboard.postgrid.com)\n\nTake a look at our [guides](https://www.postgrid.com/guides/print-mail/) for information on how to get started.\n\n# Test Mode\n\nEvery user in your organization will be provided 2 API keys which they can access from their settings: the _test_ key and the _live_ key. Any API calls made with the test key operate in an isolated sandbox. None of the resources you manage in test mode will affect your live environment, and vice versa.\n\nYou can try out your integration using the test API keys. There is no difference other than the fact that we do not verify addresses in test mode. Also, more importantly, **none of the orders made in test mode will be sent out**. Once you've tested your integration, you can switch to the live API key and it will _just work_.\n\nTest orders will also transition from `ready` to `completed` at the same time (equivalent) live orders would transition into `printing`.\n\n# Design\n\nThere are two primary ways of providing printable content to this API: you can either send predesigned PDFs or provide HTML with personalizable variables. In either case, the address information will automatically be stamped on the final mailing.\n\n### Letters\n\nFor letters, the destination and return addresses are stamped on the first page of your mailing by default. Refer to the following table:\n\n| Country | Guideline |\n| --- | --- |\n| Canada | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/canada_letter_guideline.pdf) |\n| United Kingdom | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/letter_guideline_uk.pdf) |\n| US & Intl. | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/letter_guideline.pdf) |\n| Australia | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/letter_guideline_au.pdf) |\n\n| Country | Page Size |\n| --- | --- |\n| Canada | 8.5 x 11 inches |\n| United Kingdom | 8.3 x 11.7 inches |\n| US & Intl. | 8.5 x 11 inches |\n| Australia | 8.3 x 11.7 inches |\n\n**PostGrid will automatically cancel orders if it detects that there is content underneath the address region**. If you are not able to accommodate the address region in your design, you can also insert a blank page just for the address via the letters API `addressPlacement` parameter.\n\n### Plastic Card Inserts\n\nIf you have the plastic card inserts feature enabled, your plastic card templates/PDF files must follow the following guideline: Click [here.](https://pg-prod-bucket-1.s3.amazonaws.com/assets/plastic_card_guideline_standard.pdf)\n\n### Postcards\n\nFor postcards, the guideline varies depending on size and country. Refer to the following table\n\nCanada:\n\n| Size | Guideline |\n| --- | --- |\n| `6x4` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/postcard_guideline_6x4_ca.pdf) to view the guideline |\n| `9x6` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/postcard_guideline_9x6_ca.pdf) to view the guideline |\n| `11x6` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/postcard_guideline_11x6_ca.pdf) to view the guideline |\n\nUnited Kingdom & Europe:\n\n| Size | Guideline |\n| --- | --- |\n| `6x4` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/uk_postcard_guideline_6x4.pdf) to view the guideline |\n| `9x6` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/uk_postcard_guideline_9x6.pdf) to view the guideline |\n| `11x6` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/uk_postcard_guideline_11x6.pdf) to view the guideline |\n\n_Note that for the UK postcards, the red zone's width is half the width of the postcard itself._\n\nUS & International:\n\n| Size | Guideline |\n| --- | --- |\n| `6x4` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/postcard_guideline_6x4.pdf) to view the guideline |\n| `9x6` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/postcard_guideline_9x6.pdf) to view the guideline |\n| `11x6` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/postcard_guideline_11x6.pdf) to view the guideline |\n\n### Cheques\n\nFor cheques, the `message` HTML can cover 7 inches from the top of the first page to the top of the cheque. There is a `0.3in` margin applied to this message as it is required for optimal printing.\n\n### Self Mailers\n\nFor self mailers, the guideline varies depending on the size/type of self mailer you're sending:\n\nUS & International:\n\n| Size | Guideline |\n| --- | --- |\n| `8.5x11_bifold` | Click [here](https://pg-prod-bucket-1.s3.amazonaws.com/assets/bifold_guideline.pdf) to view the guideline |\n| `8.5x11_trifold` | Click [here ](https://pg-prod-bucket-1.s3.us-east-1.amazonaws.com/assets/trifold_guideline.pdf) to view the guideline |\n\n# Integrations\n\nClick [here](https://zapier.com/developer/public-invite/122621/b21ef467fae16f31201738815f0055a7/) to get access to our Zapier integration. Zapier will enable you to connect over 1300 apps with PostGrid's print & mail capabilities without writing any code.\n\n# Tracking\n\nEvery order contains a `status` field with one of the following values\n\n| Status | Description |\n| --- | --- |\n| `ready` | The order was created successfully and will be printed on `sendDate` |\n| `printing` | The order has been given to a printer and will be processed within our SLA |\n| `processed_for_delivery` | The order has been handed off to the local postal service |\n| `completed` | The order has most likely been delivered. This is an approximation. |\n| `cancelled` | The order has been cancelled and will never be sent out |\n\nSee the intelligent-mail tracking section below for more detailed tracking information that we provide in the US.\n\n# Intelligent-Mail Tracking\n\nLive orders **destined for the US** have an `imbStatus` field added to them once they are processed at a USPS facility. This field has one of the following values\n\n| Status | Description |\n| --- | --- |\n| `entered_mail_stream` | The order has entered a USPS facility. |\n| `out_for_delivery` | The order has been processed at its final USPS facility and will deliver within a day. |\n| `returned_to_sender` | The order has been returned to the sender. |\n\nAdditionally, the fields `imbDate` and `imbZIPCode` are included to provide more details about the mailing's journey.\n\nThe `imbDate` represents the date when the mailing was last scanned at a USPS facility, and the `imbZIPCode` indicates the postal code of that facility. These fields are updated as your order progresses through the USPS processing stages.\n\n# Mailing Class\n\nBy default, all mail is sent as First Class or the fastest non-express postage available in the destination country. You can override this by supplying a specific `mailingClass` value. For instance, for a lower postage you can supply a `mailingClass` parameter with value of `standard_class` to your API calls.\n\nThe table below is an exhaustive list of the possible `mailingClass` values.\n\n| **Mailing Class** | **Description** |\n| --- | --- |\n| `first_class` | Generic first class mail. A suitable carrier will be automatically chosen to send the first class mail. |\n| `standard_class` | Generic standard class mail. A suitable carrier will be automatically chosen to send the standard class mail |\n| `express` | Generic express mail. A suitable carrier will be automatically chosen to send the express mail. |\n| `certified` | Generic certified mail. A suitable carrier will be automatically chosen to send the certified mail. See [Certified and Registered Mail](#certified-and-registered-mail) for more information. |\n| `certified_return_receipt` | Generic certified mail with return receipt. A suitable carrier will be automatically chosen to send the certified mail with return receipt. See [Certified and Registered Mail](#certified-and-registered-mail) for more information. |\n| `registered` | Generic registered mail. A suitable carrier will be automatically chosen to send the registered mail. See [Certified and Registered Mail](#certified-and-registered-mail) for more information. |\n| `usps_first_class` | First class mail sent through USPS. |\n| `usps_standard_class` | Standard class mail sent through USPS. |\n| `usps_express_3_day` | USPS Priority Mail (2-3 day); Expedited USPS shipping tracking. |\n| `usps_first_class_certified` | First class certified mail sent through USPS. See [Certified and Registered Mail](#certified-and-registered-mail) for more information. |\n| `usps_first_class_certified_return_receipt` | First class certified mail with return receipt sent through USPS. See [Certified and Registered Mail](#certified-and-registered-mail) for more information. |\n| `ca_post_lettermail` | Lettermail mail sent through Canada Post. |\n| `ca_post_personalized` | Personailzed mail sent through Canada Post. |\n| `ca_post_registered` | Generic registered mail sent through Canada Post. |\n| `ca_post_expedited_with_signature` | Expedited mail with signature sent through Canada Post. |\n| `ca_post_expedited` | Expedited mail sent through Canada Post |\n| `ca_post_xpresspost_with_signature` | Xpresspost mail with signature sent through Canada Post. |\n| `ca_post_xpresspost` | Xpresspost mail sent through Canada Post. |\n| `royal_mail_first_class` | First class mail sent through Royal Mail. |\n| `royal_mail_standard_class` | Standard class mail sent through Royal Mail. |\n| `au_post_regular` | Regular class mail sent through Australian Post. |\n| `ups_express_overnight` | Overnight express mail sent through UPS; only supported in Canada at the moment |\n| `ups_express_2_day` | 2-day express mail sent through UPS; only supported in Canada at the moment |\n| `ups_express_3_day` | 3-day express mail sent through UPS; only supported in Canada at the moment |\n| `ups_express_3_day_signature_confirmation` | 3-day express mail sent through UPS; only supported in Canada at the moment |\n| `ups_express_3_day_adult_signature_confirmation` | 3-day express mail sent through UPS; only supported in Canada at the moment |\n\n# Letter Size\n\nBy default, the letter size will be chosen based on the destination country. You can override this to get a specific letter size by supplying a `size` parameter with one of the other size options `us_letter`, `us_legal`, `a4`.\n\n| **Country** | **Allowed Options** |\n| --- | --- |\n| US | `us_letter` |\n| UK | `a4` |\n| Rest of the world | `us_letter` |\n\n# Cheque Size\n\nBy default, the cheque size will be chosen based on the destination country. You can override this to get a specific cheque size by supplying a `size` parameter with one of the other size options `us_letter` or `us_legal`.\n\n| **Country** | **Allowed Options** |\n| --- | --- |\n| US | `us_letter` |\n| Rest of the world | `us_letter` |\n\n# Cancellation\n\nYou can cancel orders while they are still in the `ready` status. For orders scheduled in advance, this typically means you can cancel them until 12AM eastern time on its `sendDate`. For orders that are scheduled to send ASAP, you should be able to cancel until 12AM eastern time on the following day.\n\nFor example, if I create an order without a `sendDate` (i.e. send ASAP) at 3PM eastern time on `2020-09-14`, I can cancel it until 12AM eastern time on `2020-09-15`.\n\n# Authorization\n\nAll requests here can be authorized via an `x-api-key` header. If you're using `cURL`, you can also supply the key using the shorthand `-u YOUR_API_KEY:`\n\nYou can retrieve your API key from the dashboard inside the `Settings` page.\n\n# Request Bodies\n\nAll request bodies can be specified in `application/json` or `application/x-www-form-urlencoded`. For the endpoints that require uploading a file, you can supply the body as `multipart/form-data`.\n\nNote that the examples here use the URL encoded format. However, this maps easily into JSON. Wherever you see e.g. `to[addressLine1]=Example`, that's equivalent to\n\n``` json\n\"to\": { \"addressLine1\": \"Example\" }\n\n ```\n\nin JSON.\n\n# Rate Limit\n\nWe have different rate limits depending on the type of request.\n\nFor orders (letters, postcards, cheques, self mailers, boxes) and resources (contacts, templates, bank accounts, return envelopes, trackers).\n\n| **Request** | **Limit** |\n| --- | --- |\n| POST Create | 1000/minute |\n| GET Individual | 50/minute |\n| GET List | 10/minute |\n\nIf you do exceed our rate limit we will return a 429 status code. We recommend using an [exponential backoff with jitter retry strategy](https://postgrid.readme.io/docs/response-codes-and-retry-logic#/) along with making use of our [idempotent requests](#idempotent-requests) feature.\n\n# Idempotent Requests\n\nOur API supports [idempotence](https://en.wikipedia.org/wiki/Idempotence) on our order creation endpoints. This allows you to safely retry API calls without creating duplicate orders. This also makes your code more robust in the presence of network issues which disrupt API calls. As such, **we highly recommend you make use of this feature.**\n\nIn order to make your order creation calls idempotent, you must supply an additional `Idempotency-Key:` header. **If your request validates successfully**, we will ensure that subsequent requests with an identical idempotency key **made up to 24 hours after the initial** will return the exact same response without creating any orders. This includes error responses.\n\nYou are free to generate your keys however you like, but we suggest using V4 UUIDs.\n\n# Errors\n\nAll of our error responses contain an `error` top-level object. This is what it looks like.\n\n| Name | Type | Description |\n| --- | --- | --- |\n| type | string | An computer friendly stable string like `invalid_pdf_error` |\n| message | string | A human-readable description of the error |\n\nPostGrid uses standard HTTP codes to indicate successful or failed API requests. Successful operations will return 2xx codes. Responses with 4xx codes usually indicate input errors and 5xx codes indicate a server error.\n\nPlease refer to the documentation below for more details.\n\n## Authentication Errors\n\n| Error Condition | **Status Code** | **Code** | **Message** |\n| --- | --- | --- | --- |\n| Your API key could have an incorrect value or be missing from your request headers. | 401 | missing_auth_error | Missing or invalid authentication. |\n|  | 401 | invalid_oauth_token_error | Invalid OAuth token. |\n| Your API key is incorrect. Learn how to access your API keys [here](https://postgrid.readme.io/docs/account-set-up#api-keys). | 401 | invalid_api_key_error | Invalid API key ${keyValue} |\n\n## Authorization Errors\n\n| Error Condition | **Status Code** | **Code** | **Message** |\n| --- | --- | --- | --- |\n|  | 403 | limit_reached_error | You have reached your mailing limit for the month (${limit}). Upgrade to send more. |\n| It is necessary to add a payment method in order to use Live Mode. Learn more about adding a payment method [here](https://postgrid.readme.io/docs/account-set-up#setting-up-a-payment-method). | 403 | org_missing_payment_method_error | You have not attached a payment method so you cannot access the live API. |\n|  | 403 | org_not_subscribed_error | You are not subscribed so you cannot do this. |\n| It is necessary to attach a payment method to your PostGrid account to access live mode. If you made an external payment, contact PostGrid support to enable live access to your account. | 401 | live_permissions_missing_error | You do not have permission to complete live requests. Contact your administrator to gain live access. |\n|  | 429 | rate_limit_exceeded_error | Rate limit exceeded. |\n|  | 403 | self_mailers_not_enabled_error | Self mailers are not enabled for this organization. |\n|  | 400 | expired_url_error | The URL you are trying to access has expired. |\n|  | 422 | url_generation_error | Failed to generate URL for tracker. |\n\n## Validation Errors\n\n| Error Condition | **Status Code** | **Code** | **Message** |\n| --- | --- | --- | --- |\n| Missing signature text or image when creating a bank account. | 400 | missing_signature_image_error | Missing signature image or signature text. |\n| Invalid signature image type (must be PNG/JPEG). | 400 | invalid_signature_image_type | Invalid signature image type ${mimetype} when expecting one of \\['image/jpeg', 'image/png'\\] |\n|  | 400 | invalid_protocol_error | Please use the 'https' protocol for the url: ${url} |\n|  | 400 | express_extra_service_unsupported_error | Cannot create an order with both extra service and express delivery. |\n|  | 400 | missing_contact_name_error | Missing first name and company name on contact. At least one must be provided. |\n| You must provide a valid ISO 3611-1 country code when creating contacts. | 400 | missing_contact_country_error | Missing country information on contact. |\n|  | 400 | multiple_countries_in_batch_error | Provided multiple destination countries ${countryCodeA} and ${countryCodeB}. Please make sure all letters are destined for the same country. |\n|  | 400 | no_valid_contacts_in_batch_error | There are no valid contacts in this batch; make sure the country of the contacts is set correctly or adjust your address strictness setting. |\n|  | 400 | validation_error | Failed to satisfy the following constraints: ${errors} |\n|  | 400 | invalid_pdf_error | Unable to get PDF information. The file or the link you provided might be incorrect. |\n| Please refer to our [design guidelines](https://postgrid.readme.io/docs/design-and-templates) for the expected PDF dimensions for each country. | 400 | pdf_incorrect_size_error | File has incorrect page dimensions ${width}x${height} when expecting ${expectedWidth}x${expectedHeight}. |\n| The provided PDF has pages with different sizes. Please check and resize the PDF according to the [design guidelines](https://postgrid.readme.io/docs/design-and-templates). | 400 | pdf_inconsistent_page_dimensions_error | File has minimum ${dimension} of ${minDimension} and a maximum of ${maxDimension} when expecting similar values. |\n|  | 400 | pdf_invalid_page_rotation_error | Page ${ page} in PDF has invalid rotation of ${rotation} |\n|  | 400 | pdf_incorrect_page_count_error | File has an incorrect number of pages ${pageCount} when expecting ${expectedPageCount}. |\n| The order status is either `complete` or `cancelled`. Therefore, it cannot be progressed. | 422 | invalid_progression_error | Cannot progress order ${id} from status '${status}' because it is terminal. |\n|  | 400 | could_not_resolve_error | Could not resolve the domain for the URL \"${url}\" |\n| The `search` parameter may be incorrectly formatted. Learn more about the searching capabilities of our endpoints [here](https://docs.postgrid.com/#search). | 400 | invalid_search_query_error | The syntax of the search query is incorrect. Make sure it is valid JSON. |\n|  | 400 | insert_blank_page_perforate_error | Cannot insert blank page for address and also perforate the first page. Please disable one or the other. |\n| The selected mailing class is not available for the selected country. Please check the list of all available mailing classes here. | 400 | mailing_class_not_supported_for_country_error | The mailing class ${mailingClass} is not available for the country code ${countryCode}. |\n|  | 400 | ${collateral}_size_not_available_error | The requested ${collateral} size ${requestedSize} is not available for destination country '${destCountryCode}'. Please choose one of ${availableSizes} |\n|  | 422 | pdf_workflow_run_not_waiting_for_confirmation_error | Attempted to confirm a workflow run ${runID} whose status is not waiting_for_confirmation. |\n|  | 400 | pdf_workflow_missing_last_send_job | The last job in a PDF workflow must be a send job. See the API documentation for the various send jobs available. |\n|  | 400 | pdf_workflow_multiple_send_jobs_error | PDF workflows cannot contain multiple send jobs. Send jobs must be the last job in a workflow. |\n|  | 400 | pdf_workflow_invalid_job_sequence_error | You cannot have a '${prevJobType}' job followed by a '${nextJobType}' job in a PDF workflow. The following job types are valid inputs to a '${nextJobType}' job: ${validInputJobs}. |\n| You cannot retrieve a postal cheque (non-digital) using this endpoint. | 400 | cheque_not_digital_only_error | Cheque is not digital only. |\n\n## Not Found Errors\n\n| Error Condition | **Status Code** | **Code** | **Message** |\n| --- | --- | --- | --- |\n| The resource (such as order, user, template, etc.) with the specified ID could not be found. | 404 | ${object}_not_found_error | Could not find ${object} with id ${id} |\n|  | 404 | contact_not_found_error | Contact with ID ${id} was not found. |\n|  | 404 | no_users_found_error | No users could be found with your organization |\n|  | 404 | email_not_found_error | User with email ${email} not found. |\n|  | 400 | url_not_found_error | Got status ${status} when attempting to download PDF from the URL \"${url}\" |\n\n## Conflict Errors\n\n| **Error Condition** | **Status Code** | **Code** | **Message** |\n| --- | --- | --- | --- |\n|  | 422 | duplicate_contact_info_error | There is already a contact with the exact same information. |\n| The return envelope you attempted to use is out of stock. Learn more about ordering return envelopes [here](https://postgrid.readme.io/docs/creating-your-first-return-envelope-order). | 422 | return_envelope_out_of_stock_error | Return envelope ${id} is out of stock (0 available). Please order more or wait for existing orders to fill. |\n| It is not possible to create a return envelope as one already exists for the selected contact. | 422 | return_envelope_already_exists_error | There is already a return envelope for destination contact ${contactID}. |\n\n## Order Errors\n\n| Error Condition | Status Code | Code | Message |\n| --- | --- | --- | --- |\n|  | 422 | return_envelope_order_cannot_fill_live_error | Can only force-fill return envelope orders in test mode. |\n|  | 422 | return_envelope_order_cannot_fill_error | Cannot fill return envelope order ${id} because its status is not 'placed'. |\n| The order you attempted to cancel may have already been cancelled or may have progressed beyond the `ready` status. Please contact PostGrid Support for more assistance.  <br>The order you attempted to cancel may have already been cancelled or may have progressed beyond the `ready` status. Please contact PostGrid Support for more assistance. | 422 | return_envelope_order_cancel_failed_error | Cannot cancel return envelope order ID ${id}. |\n| Same as above. | 422 | cancel_failed_error | Cannot cancel order ID ${id}. |\n| A postal code is required for sending mail to the selected country. | 400 | postal_code_required_error | Cannot mail to ${countryCode} without a postal code |\n\n## Address Errors\n\n| Error Condition | Status Code | **Code** | **Message** |\n| --- | --- | --- | --- |\n| The contact’s address may have failed to verify and your address strictness status may be set to `allow_corrected` or `allow_verified`. You can either update your address strictness setting or set the `forceVerifiedStatus` flag to `true`. Check more about that [here](https://docs.postgrid.com/#a72df6c8-a887-4203-8f7e-98d928e00580). | 422 | address_strictness_error | The address '${address}' does not meet the strictness '${setting}' because its status is '${status} |\n| Same as above. | 422 | address_strictness_error | The address containing '${line1}' failed to meet your strictness requirement (${setting}) because its status was ${status} |\n|  | 400 | invalid_address_error | Cannot create plausible address from '${address}'. |\n\n## Generic Errors\n\n| **Error Condition** | **Status Code** | **Code** | **Message** |\n| --- | --- | --- | --- |\n|  | 503 | service_unavailable_error | Our service is temporarily unavailable, please try again. |\n\n# Lists and Pagination\n\nAll of our listing endpoints are paginated and produce responses according to the [List](#list-response) schema. These endpoints receive a `skip` and `limit` parameter which can be used to traverse the pages. You can traverse a complete list by incrementing `skip` by `limit` for each request until `skip >= totalCount`, where `totalCount` is returned in the list response.\n\n# Search\n\nOur resource listing endpoints such as `GET /contacts` and `GET /letters` provide advanced search capabilities. You can perform this search via a `search` query parameter, or use the search field on our _dashboard_.\n\nFor example `GET /v1/contacts?search=\"New York\"` (i.e. `search=\"New York\"`) will produce all the contacts that have the exact string `\"New York\"` in their body.\n\nYou can also perform structured queries like `GET /v1/letters?search={\"metadata.campaignID\": \"ABC\"}` which searches for\n\n```\n{\n    \"metadata.campaignID\": \"ABC\"\n}\n\n ```\n\nIn other words, this will produce all the letters whose `campaignID` matches `ABC`.\n\n# Expansions\n\nSome of our endpoints return resources with nested IDs. For example, when you retrieve a letter that was created from a template, its body will contain the template ID (See [Letter](https://null)). Rather than making a separate API request for the nested template, you can pass along an query parameter like `GET /letters?expand[]=template`.\n\nThis also works for getting the nested `bankAccount` inside a cheque. However, it is important to note that **you cannot do this for the listing endpoints** due to its performance implications.\n\n# Metadata\n\nEvery object in the API can have arbitrary `metadata` attached to it. For example, I can tag my letters with a campaign ID:\n\n``` json\n{\n    // Other letter fields...\n    \"metadata\": {\n        \"campaignID\": \"ABC\"\n    }\n}\n\n ```\n\nI can later get analytics on these letters using the advanced search functionality in the dashboard.\n\nThe metadata object must not exceed 10kb of uncompressed storage.\n\n# Merge Variables\n\nWhenever you supply HTML to the API via a [Template](https://null), directly inside a [Letter](https://null), [Postcard](https://null), or in the `message` of a [Cheque](https://null), you can specify variable fields using curly braces like `{{variableName}}`. You can then supply a `mergeVariables` object in your `POST` requests, and provide values for them.\n\n`mergeVariables` on a request can contain arbitrarily nested objects. For example\n\n```\n{\n    \"income\": {\n        \"beforeTax\": 100,\n        \"afterTax\": 73\n    }\n}\n\n ```\n\nand these can be referenced by using a `.` to access nested fields `{{income.beforeTax}}` and `{{income.afterTax}}`. **Note that variable names (e.g.** **`income`**, **`beforeTax`**, **`afterTax`**) cannot contain the characters **`, # $ .`**\n\nYou can also access the following predefined merge variables in your template\n\n| Name | Type | Description |\n| --- | --- | --- |\n| to | [Contact](#a72df6c8-a887-4203-8f7e-98d928e00580) | The recipient info e.g. `to.firstName`, `to.companyName` |\n| from | [Contact](#a72df6c8-a887-4203-8f7e-98d928e00580) | The sender info e.g. `from.firstName`, `from.companyName` |\n\n# PDF Previews\n\nWe provide PDF previews for all orders (including those created in test mode). These previews should be generated a few seconds after you create an order. They can be accessed through the `url` property of the returned objects or on the dashboard by clicking `View PDF` on the top-right of the order details page.\n\nIn the case of cheques, the previews will censor the account number by padding the last 4 digits of the account number with zeros.\n\n# Certified and Registered Mail\n\nYou can provide an `extraService` parameter to the Letter and Cheque creation endpoints. This parameter will allow you to send certified/registered mail (including certified mail with return receipts). **This is currently only available for US mailings**. Note that additional charges will apply for these mailings.\n\nOnce a tracking number has been generated, a `letter.updated` or `cheque.updated` event will be generated and a webhook will be triggered with the `trackingNumber` field present. It can be retrieved through a `GET` request or via the raw data in the dashboard. Using this tracking number, you can view the delivery status of the order on the USPS website or using their API.\n\nHere are the possible values you can provide for `extraService`\n\n| Value | Description |\n| --- | --- |\n| `certified` | Send as certified mail |\n| `certified_return_receipt` | Send as certified mail with a return receipt |\n| `registered` | Send as registered mail |\n\nYou can also supply specific values to [mailingClass ](#mailing-class) to extra service for your orders.\n\n# Perforation\n\nYou can request that the first page of a letter is perforated by adding a parameter `perforatedPage: 1` to your letters `POST` request body. The perforation will be done such that the bottom 3rd of the page (3.6 inches from the bottom) can be torn off the letter.\n\n# Return Envelopes\n\nYou can send your letters along with a return envelope by supplying a `returnEnvelope` ID to your `POST /letters` or `POST /cheques` API call. Note that you must first order return envelopes using our Return Envelopes API (see the relevant sections).\n\n# Secret Resources\n\nOn select resources, providing a `secret` parameter allows hiding information from the dashboard and API. This allows external and private information to be used in the final prints without allowing PostGrid users to view this information. The provided resource ID can be used as a token to allow using these secret resources without giving access to their underlying data.\n\n# US NCOA Address Changes\n\nIn the event that one of the recipients you've mailed to has moved from the address you supplied, PostGrid may redirect the mail to their new address (depending on your subscription tier).\n\nIf mail is redirected, the address changes are applied directly to the affected contacts/orders within our API and dashboard. This also issues a webhook `{order_type}.updated` event where `{order_type}` is one of `letter`, `postcard`, `cheque`, or `self_mailer` depending on which type of order was updated.\n\nYou can examine the new address by looking at the `addressLine1`, `addressLine2`, etc. fields of the contacts. There is also a new `addressChange` object that gets added to contacts that have changed as a result of a move. See the following for the schema of this object.\n\n## Address Change Object\n\n| Name | Type | Description |\n| --- | --- | --- |\n| processedOn | Date (string) | The date and time this address change was ingested into our system. |\n| moveYearMonth | string | The `MM/YYYY` that this contact moved. |\n| oldAddress | object | An object containing the `addressLine1`, `city`, etc of the address prior to the move update. |\n\n# Express Shipping\n\nYou can request express shipping for your orders by setting specific options in `mailingClass`. See [Mailing Class](#mailing-class) for more details.\n\n# Carrier Tracking\n\nPostGrid can provide the **exact** status of an order as provided by the underlying mail carrier when an appropriate `mailingClass` is used (e.g. USPS certified mail). You can learn more about this feature here: [https://postgrid.readme.io/reference/carrier-tracking](https://postgrid.readme.io/reference/carrier-tracking)\n\n# List Response\n\n| Name | Type | Description |\n| --- | --- | --- |\n| object | string | Always `list` |\n| limit | integer | The `limit` passed into the request |\n| skip | integer | The `skip` passed into the request |\n| totalCount | integer | Total number of documents in this list, including skipped documents |\n| data | Array | The requested documents |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"17206988","team":1674902,"collectionId":"30d9da4f-15c3-4b6a-aae1-d3a329dc6b13","publishedId":"U16opPhz","public":true,"publicUrl":"https://docs.postgrid.com","privateUrl":"https://go.postman.co/documentation/17206988-30d9da4f-15c3-4b6a-aae1-d3a329dc6b13","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"2d69ed"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"REST API documentation for the PostGrid Print and Mail API. Also includes information on how to get started with the API and other considerations, including integrations and optional features."},{"name":"title","value":"PostGrid Print and Mail API"}],"appearance":{"default":"system_default","themes":[{"name":"dark","logo":"https://content.pstmn.io/a1d1dbf1-e12e-4bf5-90b7-912779792f54/bG9nby5wbmc=","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"2d69ed"}},{"name":"light","logo":"https://content.pstmn.io/a1d1dbf1-e12e-4bf5-90b7-912779792f54/bG9nby5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"2d69ed"}}]}},"version":"8.10.0","publishDate":"2023-07-14T21:05:00.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"PostGrid Print and Mail API","description":"REST API documentation for the PostGrid Print and Mail API. Also includes information on how to get started with the API and other considerations, including integrations and optional features."},"logos":{"logoLight":"https://content.pstmn.io/a1d1dbf1-e12e-4bf5-90b7-912779792f54/bG9nby5wbmc=","logoDark":"https://content.pstmn.io/a1d1dbf1-e12e-4bf5-90b7-912779792f54/bG9nby5wbmc="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/34bd04019e69deb8dbe2753382c09c0e8683157cabf78a2860fcea37da95f5af","favicon":"https://postgrid.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://docs.postgrid.com/view/metadata/U16opPhz"}