openapi: 3.0.0
info:
title: PostGrid Print & Mail API
contact:
email: support@postgrid.com
url: postgrid.com
version: "1.0"
tags:
- name: Templates
description: " Create and manage reusable HTML templates. A template's HTML can
include
\ merge variables (e.g. `{{firstName}}`) and be referenced by ID when
creating
\ letters, postcards, cheques, and self mailers.
\ "
- name: Contacts
description: " Manage contacts that you can mail to. Test mode addresses will
always have a
\ `verified` status. In live mode, they may be `verified`, `corrected`, or
\ `failed`. Addresses that fail to be corrected are likely undeliverable,
but
\ you can still send to them if you want to.
\ For test mode contacts, you have the ability to assert the
`addressStatus` of
\ the contact by passing specific values to the `description` field. To
receive
\ an `addressStatus` of `failed`, the description of the contact should be
a
\ string with the exact value `test failed`. For an `addressStatus` value
of
\ `corrected`, the description of the contact should be a string with the
exact
\ value `test corrected`.
\ Our address correction engine will often be able to fix missing
postal/ZIP
\ codes, city names, and also append ZIP+4. It is SERP (Canada Post) and
CASS
\ (USPS) certified, so you can rest assured that if an address is
verified, we
\ can deliver to it.
\ "
- name: Events
description: " View Events related to your orders.
\ An event is created whenever a webhook is triggered. For example, if a
webhook
\ is created that listens to `letter.updated` events and the delivery
status of a
\ letter is updated, an event detailing the updated fields will get
created.
\ "
- name: Letters
description: " Create and manage letter orders.\n "
- name: Postcards
description: " Create and manage postcard mailings.
\ "
- name: Bank Accounts
description: " Manage bank accounts that will be used for mailing cheques.
\ "
- name: Cheques
description: " Create and manage cheque orders.\n "
- name: Boxes
description: " Create and manage box orders.\n "
- name: Self Mailers
description: " Create and manage self mailers.\n "
- name: Return Envelopes
description: " You can use the return envelopes API to create and manage return
envelopes.
\ These are envelopes that are sent along with your mail (if specified)
and
\ allow your recipients to send mail to a particular address without
having to
\ purchase their own envelopes/stamps.
\ Note that you must order return envelopes and wait for the order to be
\ filled before you can use them. You can manage these return envelope
orders
\ via the API as well as the dashboard.
\ "
- name: Reports
description: " The reports API lets you run SQL queries against a data lake with
all of your PostGrid data. You can use this to run ad-hoc SQL queries or
save them as reports. You can bulk export data from these reports to fit
all of your reporting needs.
\ Note that the data this API provides may be up to 2 hours behind your
current PostGrid environment.
\ Your test and live data lakes are fully segregated, so you'll need a
live API key to run queries against your live data.
\ You can request access to this to this feature by reaching out to
support@postgrid.com
\ "
- name: Sub-Organizations
description: " Sub-organizations enable you to create isolated PostGrid accounts
\ (\"sub-organizations\") under your PostGrid account (the \"parent
organization\").
\ Each sub-organization has fully isolated resources
\ and users, and can act independently.
\ This allows you to isolate different departments or even re-sell
PostGrid
\ entirely.
\ You can request access to this feature by reaching out to
\ support@postgrid.com
\ "
- name: Campaigns
description: " The campaigns API enables you to send out large volumes of fully
\ personalized mail to a mailing list.
\ "
- name: Snap Packs
description: " Snap packs are pressure-sealed mailers that resemble official
documents
\ and encourage higher open rates. They do not require envelopes and are
\ opened by tearing along perforated edges. The sealed design keeps
contents
\ hidden until opened, making snap packs ideal for sensitive or important
\ documents such as contracts, forms, or notices.
\ You can request access to this feature by reaching out to
\ support@postgrid.com
\ "
- name: Mailing Lists
description: " The mailing lists API enables you to manage collections of
contacts
\ that can be used for bulk mail campaigns.
\ "
- name: Mailing List Imports
description: " The mailing list imports API enables you to import contact lists
from files
\ and validate them for use in campaigns.
\ "
- name: Virtual Mailboxes
description: " Virtual mailboxes let you receive, scan, and forward your
physical mail
\ without needing a traditional physical mailbox. Each mailbox is fully
\ digital, giving you a unique ID, status, and a set of capabilities such
as
\ forwarding mail to another address or viewing envelope scans. This
allows you
\ to manage physical correspondence entirely online.
\ You can request access to this feature by reaching out to
\ support@postgrid.com
\ "
- name: Targeted List Builds
description: " **Beta:** the targeted list builds API is in beta and is subject
to
\ breaking changes. Endpoint shapes, status values, and filter fields may
\ change without notice.
\ The targeted list builds API lets you programmatically build mailing
\ lists of US consumers (B2C) or US companies (B2B) that match a set of
\ demographic, geographic, and firmographic filters.
\ The lifecycle of a list build is:
\ 1. Create a list build by supplying either `usConsumers` or
`usCompanies`
\ filters. A quote is generated asynchronously — poll the resource or
\ wait for its `status` to become `quote_ready`.
\ 2. Review the `quote` (total count and price per contact) and masked
\ `previewRecords`. Adjust the filters with an update call if needed —
\ this will regenerate the quote.
\ 3. Confirm the build. This deducts the appropriate amount of list build
\ credits from your organization (in live mode) and begins constructing
\ the mailing list. `buildProgressPercent` reflects progress from 0 to
\ 100.
\ 4. Once `status` is `completed`, the ID of the resulting mailing list is
\ available in the `mailingList` field and can be used like any other
\ mailing list in the PostGrid API.
\ Targeted list builds must be enabled on your organization before they
\ can be used. Contact PostGrid support to request access.
\ "
- name: Template Editor Sessions
description: " You can use template editor sessions to bring the capabilities of
our
\ template editor to your website. When you create a session, you provide
the
\ `template` which you want to edit, and we return a session with a `url`
that
\ you can `iframe` or redirect your customers to.
\ When users save their changes in the editor session, it will update the
\ underlying template. Note that sessions are only valid for 24 hours,
after
\ which point they are automatically deleted for security reasons.
\ You can have multiple sessions active for the same template at the same
time.
\ In general, we recommend creating a new session every time you present
our
\ editor to your users.
\ Note: you can use the template editor to modify templates created using
HTML,
\ but saving a session from the editor will override the original HTML
content.
\ "
- name: Trackers
description: " Create and manage Trackers.
\ Trackers can be used to track interactions in your orders through
\ personalized URLs and QR codes.
\ As a brief introduction to using Trackers in your orders, a QR code can
be
\ generated by using the Tracker's ID as a merge variable in your orders
HTML
\ and Templates. The following example HTML uses Trackers to generate
\ personalized URLs (PURLs) in your orders.
\ See the following guide for more details:
https://postgrid.readme.io/reference/trackers-1
\ "
- name: Webhooks
description: " Create and manage Webhooks.
\ Webhooks can be used to notify your application when events occur in
PostGrid.
\ For example, you may use a `letter.updated` webhook to receive a
notification
\ when a letter has been processed for delivery.
\ Every webhook has a `secret` and this is used to sign the payload of the
event.
\ You can choose what format you want the payload to be delivered in. By
default,
\ the webhook payload will be delivered as a [JSON Web
Token](https://jwt.io/).
\ When you receive the event, you can verify it using a JWT library
available for
\ your particular language (using the HMAC SHA256 Algorithm). There are
\ [many](https://jwt.io/#libraries-io) off-the-shelf solutions you can
use.
\ You can alternatively choose to receive a JSON payload. In this case,
you'll
\ also receive a `PostGrid-Signature` HTTP header along with the payload.
\ You must respond with a `200` status from your webhook. Otherwise,
PostGrid
\ will retry the webhook up to 3 times. First, after 1 hour, then 2 hours,
then
\ 4 hours. We will also keep track of every invocation and its response
status.
\ You can retrieve data about prior invocations using the webhook
invocations
\ list endpoint below.
\ "
paths:
/print-mail/v1/bank_accounts:
post:
operationId: BankAccounts_create
summary: Create Bank Account
description: >-
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.
Note that the reasonable character limit for `signatureText` is 6
capital letters or 20 lowercase letters — anything exceeding that will
likely overflow onto a new line.
parameters: []
responses:
"201":
description: The request has succeeded and a new resource has been created as a
result.
content:
application/json:
schema:
$ref: "#/components/schemas/BankAccount"
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Bank Accounts
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/BankAccountCreate"
example:
bankName: Test Bank
bankPrimaryLine: 145 mulberry st
bankSecondaryLine: new york ny 10013
bankCountryCode: US
accountNumber: "1234567"
routingNumber: "123456789"
signatureText: Example
get:
operationId: BankAccounts_list
summary: List Bank Accounts
description: >-
Get a list of bank accounts.
Note that we do not return the complete account number or the signature
image for security reasons.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/BankAccountList"
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Bank Accounts
/print-mail/v1/bank_accounts/{id}:
get:
operationId: BankAccounts_get
summary: Get Bank Account
description: >-
Retrieve a bank account by ID.
Note that we do not return the complete account number or the signature
image for security reasons.
parameters:
- name: id
in: path
required: true
description: The ID of the bank account to retrieve.
schema:
type: string
responses:
"200":
description: the BankAccount.
content:
application/json:
schema:
$ref: "#/components/schemas/BankAccount"
example:
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
"401":
description: the BankAccount.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the BankAccount.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the BankAccount.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the BankAccount.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the BankAccount.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Bank Accounts
delete:
operationId: BankAccounts_delete
summary: Delete Bank Account
description: Delete a bank account by ID. Note that this operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The ID of the bank account you want to delete.
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- object
- id
- deleted
properties:
object:
type: string
enum:
- bank_account
description: Always `bank_account`.
readOnly: true
id:
type: string
pattern: bank_account_[a-zA-Z0-9]+
description: A unique ID prefixed with bank_account_
readOnly: true
deleted:
type: boolean
enum:
- true
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Bank Accounts
/print-mail/v1/boxes:
post:
operationId: Boxes_create
summary: Create Box
description: |-
This endpoint allows you to create a box containing up to 100 cheques.
A Box is mailed to a single destination.
To create a box. You must specify:
- `to`: The recipient (contact or contact ID)
- `from`: The sender (contact or contact ID)
- `cheques`: An array of cheques to go in the box
For each cheque You must specify:
- `to`: The recipient (contact or contact ID)
- `from`: The sender (contact or contact ID)
- `bankAccount`: The bank account ID
- `amount`: The amount to be sent
- `number`: The cheque number
parameters: []
responses:
"201":
description: The created Box.
content:
application/json:
schema:
$ref: "#/components/schemas/Box"
example:
id: box_123456
object: box
description: A sample box of cheques
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
cheques:
- 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
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
bankAccount: bank_123
amount: 12345
memo: Test Memo
logoURL: https://example.com/logo.png
messageTemplate: Thank you!
number: 1001
mergeVariables:
customKey: customValue
mailingClass: first_class
sendDate: 2020-11-12T23:23:47.974Z
createdAt: 2025-01-01T12:00:00Z
updatedAt: 2025-01-02T12:00:00Z
"400":
description: The created Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The created Box.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The created Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The created Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The created Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The created Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Boxes
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/BoxCreate"
example:
to: contact_123
from: contact_456
cheques:
- from: contact_456
to: contact_123
bankAccount: bank_abc
amount: 5000
number: 1042
description: The details of the box to create.
get:
operationId: Boxes_list
summary: List Boxes
description: List all boxes.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/BoxList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: box_123456
object: box
description: A sample box of cheques
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
cheques:
- 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
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
bankAccount: bank_123
amount: 12345
memo: Test Memo
logoURL: https://example.com/logo.png
messageTemplate: Thank you!
number: 1001
mergeVariables:
customKey: customValue
mailingClass: first_class
sendDate: 2020-11-12T23:23:47.974Z
createdAt: 2025-01-01T12:00:00Z
updatedAt: 2025-01-02T12:00:00Z
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Boxes
/print-mail/v1/boxes/{id}:
get:
operationId: Boxes_get
summary: Get Box
description: Retrieve a box by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the box to retrieve.
schema:
type: string
responses:
"200":
description: The retrieved Box.
content:
application/json:
schema:
$ref: "#/components/schemas/Box"
example:
id: box_123456
object: box
description: A sample box of cheques
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
cheques:
- 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
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
bankAccount: bank_123
amount: 12345
memo: Test Memo
logoURL: https://example.com/logo.png
messageTemplate: Thank you!
number: 1001
mergeVariables:
customKey: customValue
mailingClass: first_class
sendDate: 2020-11-12T23:23:47.974Z
createdAt: 2025-01-01T12:00:00Z
updatedAt: 2025-01-02T12:00:00Z
"401":
description: The retrieved Box.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The retrieved Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The retrieved Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The retrieved Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The retrieved Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Boxes
delete:
operationId: Boxes_delete
summary: Cancel Box
description: Cancel a box by ID (cannot be undone).
parameters:
- name: id
in: path
required: true
description: The ID of the box to cancel.
schema:
type: string
responses:
"200":
description: The cancelled Box.
content:
application/json:
schema:
$ref: "#/components/schemas/Box"
example:
id: box_123456
object: box
description: A sample box of cheques
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
cheques:
- 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
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
bankAccount: bank_123
amount: 12345
memo: Test Memo
logoURL: https://example.com/logo.png
messageTemplate: Thank you!
number: 1001
mergeVariables:
customKey: customValue
mailingClass: first_class
sendDate: 2020-11-12T23:23:47.974Z
createdAt: 2025-01-01T12:00:00Z
updatedAt: 2025-01-02T12:00:00Z
"401":
description: The cancelled Box.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The cancelled Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The cancelled Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The cancelled Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The cancelled Box.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Boxes
/print-mail/v1/boxes/{id}/progressions:
post:
operationId: Boxes_progress
summary: Progress Status
description: >-
Progresses a box's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order
would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
parameters:
- name: id
in: path
required: true
description: The ID of the box you want to progress.
schema:
type: string
responses:
"200":
description: The progressed box
content:
application/json:
schema:
$ref: "#/components/schemas/Box"
example:
id: box_123456
object: box
description: A sample box of cheques
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
cheques:
- 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
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
bankAccount: bank_123
amount: 12345
memo: Test Memo
logoURL: https://example.com/logo.png
messageTemplate: Thank you!
number: 1001
mergeVariables:
customKey: customValue
mailingClass: first_class
sendDate: 2020-11-12T23:23:47.974Z
createdAt: 2025-01-01T12:00:00Z
updatedAt: 2025-01-02T12:00:00Z
"400":
description: The progressed box
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The progressed box
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The progressed box
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The progressed box
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The progressed box
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The progressed box
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Boxes
/print-mail/v1/campaigns:
post:
operationId: Campaigns_create
summary: Create Campaign
description: >-
Create a new campaign.
A campaign links a mailing list with a specific mail piece configuration
(letter, postcard, cheque, self-mailer, or snap pack)
to send bulk mail. Only one collateral type can be set per campaign.
Upon creation, the campaign enters the `drafting` status while assets
are validated.
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
responses:
"201":
description: The newly created campaign in `drafting` status.
content:
application/json:
schema:
$ref: "#/components/schemas/Campaign"
"400":
description: The newly created campaign in `drafting` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The newly created campaign in `drafting` status.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The newly created campaign in `drafting` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The newly created campaign in `drafting` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The newly created campaign in `drafting` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The newly created campaign in `drafting` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Campaigns
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CampaignCreate"
multipart/form-data:
schema:
$ref: "#/components/schemas/CampaignCreateMultiPart"
description: The details of the campaign to create.
get:
operationId: Campaigns_list
summary: List Campaigns
description: >-
Retrieve a list of campaigns.
Returns a paginated list of campaigns associated with the authenticated
organization,
filterable by various parameters.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing campaigns.
content:
application/json:
schema:
$ref: "#/components/schemas/CampaignList"
"400":
description: A list object containing campaigns.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing campaigns.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing campaigns.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing campaigns.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Campaigns
/print-mail/v1/campaigns/{id}:
get:
operationId: Campaigns_get
summary: Get Campaign
description: Retrieve a specific campaign by its ID.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`campaign_...`) for the campaign.
schema:
type: string
responses:
"200":
description: The requested campaign details.
content:
application/json:
schema:
$ref: "#/components/schemas/Campaign"
"401":
description: The requested campaign details.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The requested campaign details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The requested campaign details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The requested campaign details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The requested campaign details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Campaigns
post:
operationId: Campaigns_update
summary: Update Campaign
description: >-
Update an existing campaign.
Campaigns can only be updated if they are in the `draft` or
`changes_required` status.
Updating a campaign will trigger reprocessing and set its status back to
`drafting`.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`campaign_...`) for the campaign to update.
schema:
type: string
responses:
"200":
description: The updated campaign details, now in `drafting` status.
content:
application/json:
schema:
$ref: "#/components/schemas/Campaign"
"400":
description: The updated campaign details, now in `drafting` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The updated campaign details, now in `drafting` status.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The updated campaign details, now in `drafting` status.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- draftable_campaign_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The updated campaign details, now in `drafting` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The updated campaign details, now in `drafting` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The updated campaign details, now in `drafting` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Campaigns
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CampaignUpdate"
description: The fields to update on the campaign.
delete:
operationId: Campaigns_delete
summary: Delete Campaign
description: >-
Delete a campaign.
Campaigns can only be deleted if they are in `draft`,
`changes_required`, or `ready` status.
This also permanently deletes associated resources. This operation
cannot be undone.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`campaign_...`) for the campaign to delete.
schema:
type: string
responses:
"200":
description: A confirmation object indicating the campaign was marked for
deletion.
content:
application/json:
schema:
type: object
required:
- id
- deleted
properties:
id:
type: string
pattern: campaign_[a-zA-Z0-9]+
description: A unique ID prefixed with campaign_
readOnly: true
deleted:
type: boolean
enum:
- true
"401":
description: A confirmation object indicating the campaign was marked for
deletion.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A confirmation object indicating the campaign was marked for
deletion.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- deletable_campaign_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A confirmation object indicating the campaign was marked for
deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A confirmation object indicating the campaign was marked for
deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A confirmation object indicating the campaign was marked for
deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Campaigns
/print-mail/v1/campaigns/{id}/send:
post:
operationId: Campaigns_send
summary: Send Campaign
description: >-
Send a campaign for processing.
This action transitions a campaign from the `draft` status to
`creating_orders`.
You can optionally specify a future `sendDate`. Once sent, the campaign
cannot be updated.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`campaign_...`) for the campaign to send.
schema:
type: string
responses:
"200":
description: The campaign details, now in `creating_orders` status.
content:
application/json:
schema:
$ref: "#/components/schemas/Campaign"
"400":
description: The campaign details, now in `creating_orders` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The campaign details, now in `creating_orders` status.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The campaign details, now in `creating_orders` status.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- sendable_campaign_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The campaign details, now in `creating_orders` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The campaign details, now in `creating_orders` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The campaign details, now in `creating_orders` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Campaigns
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CampaignSend"
description: Parameters for sending the campaign, including the optional send date.
/print-mail/v1/cheques:
post:
operationId: Cheques_create
summary: Create Cheque
description: >-
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.
Digital-only cheques are not sent out — they are created with a
`cancelled` status and a
cancellation reason of `digital_only`.
Example request body:
```json
{
"from": "contact_123",
"bankAccount": "bank_123",
"amount": 1000,
"currencyCode": "USD",
"number": 123456,
"size": "us_letter",
"digitalOnly": {
"watermark": "VOID"
}
}
```
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
responses:
"201":
description: the created Cheque.
content:
application/json:
schema:
$ref: "#/components/schemas/Cheque"
example:
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
"400":
description: the created Cheque.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: the created Cheque.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the created Cheque.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the created Cheque.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the created Cheque.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the created Cheque.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Cheques
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChequeCreate"
example:
to: contact_123
from: contact_123
bankAccount: bank_123
amount: 1000
currencyCode: USD
number: 123456
size: us_letter
multipart/form-data:
schema:
$ref: "#/components/schemas/ChequeCreateMultiPart"
description: The details of the cheque to create.
get:
operationId: Cheques_list
summary: List Cheques
description: Get a list of cheques.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/ChequeList"
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Cheques
/print-mail/v1/cheques/{id}:
get:
operationId: Cheques_get
summary: Get Cheque
description: Retrieve a cheque by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the cheque to retrieve.
schema:
type: string
responses:
"200":
description: the Cheque.
content:
application/json:
schema:
$ref: "#/components/schemas/Cheque"
example:
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
"401":
description: the Cheque.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the Cheque.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the Cheque.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the Cheque.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the Cheque.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Cheques
delete:
operationId: Cheques_delete
summary: Cancel Cheque
description: Cancel a cheque by ID. Note that this operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The ID of the cheque you want to cancel.
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Cheque"
example:
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
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Cheques
/print-mail/v1/cheques/{id}/cancellation:
post:
operationId: Cheques_cancelWithNote
summary: Cancel Cheque With Note
description: |-
Cancel a cheque by ID with a note. Note that this operation
cannot be undone and that only cheques with a status of `ready` can be
cancelled.
parameters:
- name: id
in: path
required: true
description: The ID of the cheque you want to cancel.
schema:
type: string
responses:
"200":
description: The cancelled cheque
content:
application/json:
schema:
$ref: "#/components/schemas/Cheque"
example:
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
"400":
description: The cancelled cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The cancelled cheque
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The cancelled cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The cancelled cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The cancelled cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The cancelled cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Cheques
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
note:
type: string
required:
- note
example:
note: Cancelling this cheque
description: The cancellation details including a note.
/print-mail/v1/cheques/{id}/progressions:
post:
operationId: Cheques_progress
summary: Progress Status
description: >-
Progresses a cheque's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order
would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
parameters:
- name: id
in: path
required: true
description: The ID of the cheque you want to progress.
schema:
type: string
responses:
"200":
description: The progressed cheque
content:
application/json:
schema:
$ref: "#/components/schemas/Cheque"
example:
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
"400":
description: The progressed cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The progressed cheque
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The progressed cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The progressed cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The progressed cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The progressed cheque
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Cheques
/print-mail/v1/cheques/{id}/url:
get:
operationId: Cheques_getURL
summary: Get Cheque Preview
description: >-
Retrieve a cheque preview URL.
This is only available for customers with our document management addon,
which offers
document generation and hosting capabilities. This endpoint has a much
higher rate limit
than the regular order retrieval endpoint, so it is suitable for
customer-facing use-cases.
parameters:
- name: id
in: path
required: true
description: The ID of the cheque to retrieve the preview URL for.
schema:
type: string
responses:
"200":
description: the Cheque Preview URL.
content:
application/json:
schema:
type: object
required:
- id
- object
- url
properties:
id:
type: string
pattern: cheque_[a-zA-Z0-9]+
description: A unique ID prefixed with cheque_
readOnly: true
object:
type: string
pattern: cheque_url
readOnly: true
url:
type: string
format: uri
description: A signed URL linking to the order preview PDF. The link remains
valid for 15 minutes from the time of the API call.
readOnly: true
example:
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
"401":
description: the Cheque Preview URL.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the Cheque Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the Cheque Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the Cheque Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the Cheque Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Cheques
/print-mail/v1/cheques/{id}/with_deposit_ready_pdf:
get:
operationId: Cheques_getDepositReadyPDF
summary: Retrieve Cheque Deposit-Ready PDF (Digital Only)
description: >-
Retrieve the deposit-ready PDF for a digital-only cheque. The endpoint
can only be called by users with 'Admin' role.
In test mode, the preview PDF of the digitalOnly cheque and the
deposit-ready PDF are the same.
In live mode, the deposit-ready will have the full account number.
parameters:
- name: id
in: path
required: true
description: The ID of the cheque you want the deposit-ready PDF for.
schema:
type: string
responses:
"200":
description: Cheque object with the depositReadyPDFURL
content:
application/json:
schema:
$ref: "#/components/schemas/Cheque"
example:
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
"400":
description: Cheque object with the depositReadyPDFURL
content:
application/json:
schema:
type: object
properties:
object:
type: string
enum:
- error
error:
type: object
properties:
type:
type: string
enum:
- cheque_not_digital_only_error
message:
type: string
enum:
- Cheque is not digital only
required:
- type
- message
required:
- object
- error
"401":
description: Cheque object with the depositReadyPDFURL
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: Cheque object with the depositReadyPDFURL
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Cheque object with the depositReadyPDFURL
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Cheque object with the depositReadyPDFURL
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Cheque object with the depositReadyPDFURL
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Cheques
/print-mail/v1/contacts:
post:
operationId: Contacts_create
summary: Create Contact
description: >-
Creates a contact. This will also verify the contact's address **if you
create it using a live API key**. To sucessfully create a contact,
either a `firstName`, a `companyName`, or both are required. You can
supply both, but you **cannot** supply neither.
You have the option to supply the entire address (except for
`countryCode`) via `addressLine1`, in which case PostGrid will parse it
automatically. However, this is **not guaranteed to be correct**, so we
recommend passing along the structured address fields (`city`,
`provinceOrState`, etc) if you have them.
_Note that if you create a contact that has identical information to
another contact, this will simply update the description of the existing
contact and return it. This avoids creating duplicate contacts._
parameters: []
responses:
"201":
description: The request has succeeded and a new resource has been created as a
result.
content:
application/json:
schema:
$ref: "#/components/schemas/Contact"
examples:
Create Contact with Single Line:
summary: Create Contact with Single Line
description: This example shows that you can call the contact creation endpoint
with an unstructured address. You can supply all the address
info into `addressLine1` and PostGrid's address parsing
engine will automatically break it apart into the
appropriate fields. Note that the parsing operation is not
guaranteed to be correct, so if you already have the
structured data (`city`, `provinceOrState`, etc), prefer
providing it.
value:
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
Create Contact with Structured Address:
summary: Create Contact with Structured Address
value:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Contacts
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ContactCreate"
examples:
Create Contact with Single Line:
summary: Create Contact with Single Line
description: This example shows that you can call the contact creation endpoint
with an unstructured address. You can supply all the address
info into `addressLine1` and PostGrid's address parsing engine
will automatically break it apart into the appropriate fields.
Note that the parsing operation is not guaranteed to be
correct, so if you already have the structured data (`city`,
`provinceOrState`, etc), prefer providing it.
value:
firstName: Kevin
companyName: PostGrid
addressLine1: 90 Canal St Suite 600, Boston MA 90210
countryCode: US
Create Contact with Structured Address:
summary: Create Contact with Structured Address
value:
firstName: Kevin
companyName: PostGrid
addressLine1: 90 Canal St
addressLine2: Suite 600
city: Boston
provinceOrState: MA
countryCode: US
get:
operationId: Contacts_list
summary: List Contacts
description: Get a list of contacts.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Contact"
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Contacts
/print-mail/v1/contacts/{id}:
get:
operationId: Contacts_get
summary: Get Contact
description: Retrieve a contact.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Contact"
example:
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
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Contacts
delete:
operationId: Contacts_delete
summary: Delete Contact
description: Delete a contact. Note that this will not affect orders that were
sent to this contact.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- object
- id
- deleted
properties:
object:
type: string
enum:
- contact
description: Always `contact`.
readOnly: true
id:
type: string
pattern: contact_[a-zA-Z0-9]+
description: A unique ID prefixed with contact_
readOnly: true
deleted:
type: boolean
enum:
- true
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Contacts
/print-mail/v1/events:
get:
operationId: Events_list
summary: List Events
description: Retrieve a paginated list of Events.
parameters:
- name: type[]
in: query
required: false
description: An optional list of event types to filter the results by.
schema:
type: array
items:
$ref: "#/components/schemas/WebhookEventType"
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
responses:
"200":
description: A list object containing Events.
content:
application/json:
schema:
$ref: "#/components/schemas/EventList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: event_r1nfP4xAacyqMYtt7PeyFD
object: event
live: false
type: letter.created
data:
id: letter_rqfnwvzq5TUsYR2r6L9V8X
object: letter
live: false
description: letter test 2
createdAt: 2021-04-02T02:06:55.086Z
"400":
description: A list object containing Events.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing Events.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing Events.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing Events.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Events
/print-mail/v1/letters:
post:
operationId: Letters_createJSON_Letters_createMultipart
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
description: >-
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 for a PDF for the letter Create a letter via a
multipart/form-data request. Accepts the same
fields as the JSON create body (nested objects are bracket-encoded form
fields, e.g. `to[firstName]`); use this content type to upload the PDF
file directly.
summary: Create Letter Create Letter
responses:
"201":
description: the created Letter.
content:
application/json:
schema:
anyOf:
- $ref: "#/components/schemas/Letter"
- $ref: "#/components/schemas/Letter"
"400":
description: the created Letter.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: the created Letter.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the created Letter.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the created Letter.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the created Letter.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the created Letter.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Letters
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/LetterCreate"
examples:
Create Letter with Premium Paper:
summary: Create Letter with Premium Paper
value:
to: contact_123
from: contact_123
html: Content
paper: standard
example1:
value:
to: contact_123
from: contact_123
html: Content
multipart/form-data:
schema:
$ref: "#/components/schemas/LetterCreateFormMultiPart"
description: The details of the letter to create. The details of the letter to
create.
get:
operationId: Letters_list
summary: List Letters
description: Get a list of letters.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/LetterList"
example:
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
paper: standard
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Letters
/print-mail/v1/letters/{id}:
get:
operationId: Letters_get
summary: Get Letter
description: Retrieve a letter by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the letter to retrieve.
schema:
type: string
responses:
"200":
description: the Letter.
content:
application/json:
schema:
$ref: "#/components/schemas/Letter"
example:
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
paper: standard
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
"401":
description: the Letter.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the Letter.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the Letter.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the Letter.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the Letter.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Letters
delete:
operationId: Letters_delete
summary: Cancel Letter
description: Cancel a letter by ID. Note that this operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The ID of the letter you want to cancel.
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Letter"
example:
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
paper: standard
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
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Letters
/print-mail/v1/letters/{id}/cancellation:
post:
operationId: Letters_cancelWithNote
summary: Cancel Letter With Note
description: |-
Cancel a letter by ID with a note. Note that this operation
cannot be undone and that only letters with a status of `ready` can be
cancelled.
parameters:
- name: id
in: path
required: true
description: The ID of the letter you want to cancel.
schema:
type: string
responses:
"200":
description: The cancelled letter
content:
application/json:
schema:
$ref: "#/components/schemas/Letter"
example:
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
paper: standard
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
"400":
description: The cancelled letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The cancelled letter
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The cancelled letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The cancelled letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The cancelled letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The cancelled letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Letters
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
note:
type: string
required:
- note
example:
note: Cancelling this letter
description: The cancellation details including a note.
/print-mail/v1/letters/{id}/progressions:
post:
operationId: Letters_progress
summary: Progress Status
description: >-
Progresses a letter's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order
would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
parameters:
- name: id
in: path
required: true
description: The ID of the letter you want to progress.
schema:
type: string
responses:
"200":
description: The progressed letter
content:
application/json:
schema:
$ref: "#/components/schemas/Letter"
example:
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
paper: standard
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
"400":
description: The progressed letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The progressed letter
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The progressed letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The progressed letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The progressed letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The progressed letter
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Letters
/print-mail/v1/letters/{id}/url:
get:
operationId: Letters_getURL
summary: Get Letter Preview
description: >-
Retrieve a letter preview URL.
This is only available for customers with our document management addon,
which offers
document generation and hosting capabilities. This endpoint has a much
higher rate limit
than the regular order retrieval endpoint, so it is suitable for
customer-facing use-cases.
parameters:
- name: id
in: path
required: true
description: The ID of the letter to retrieve the preview URL for.
schema:
type: string
responses:
"200":
description: the Letter Preview URL.
content:
application/json:
schema:
type: object
required:
- id
- object
- url
properties:
id:
type: string
pattern: letter_[a-zA-Z0-9]+
description: A unique ID prefixed with letter_
readOnly: true
object:
type: string
pattern: letter_url
readOnly: true
url:
type: string
format: uri
description: A signed URL linking to the order preview PDF. The link remains
valid for 15 minutes from the time of the API call.
readOnly: true
example:
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
"401":
description: the Letter Preview URL.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the Letter Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the Letter Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the Letter Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the Letter Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Letters
/print-mail/v1/mailing_list_imports:
post:
operationId: MailingListImports_create
summary: Create Mailing List Import
description: >-
Create a new mailing list import.
Initiates the import process for a contact list file. The import enters
the
`validating` status while contacts are processed and verified.
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
responses:
"201":
description: The newly created mailing list import in `validating` status.
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListImportResponse"
example:
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
"400":
description: The newly created mailing list import in `validating` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The newly created mailing list import in `validating` status.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The newly created mailing list import in `validating` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The newly created mailing list import in `validating` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The newly created mailing list import in `validating` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The newly created mailing list import in `validating` status.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing List Imports
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListImportCreate"
example:
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
description: The details of the mailing list import to create.
get:
operationId: MailingListImports_list
summary: List Mailing List Imports
description: >-
Retrieve a list of mailing list imports.
Returns a paginated list of imports associated with the authenticated
organization,
filterable by various parameters.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing mailing list imports.
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListImportList"
example:
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
"400":
description: A list object containing mailing list imports.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing mailing list imports.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing mailing list imports.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing mailing list imports.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing List Imports
/print-mail/v1/mailing_list_imports/{id}:
post:
operationId: MailingListImports_update
summary: Update Mailing List Import
description: Update an existing mailing list import.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`mailing_list_import_...`) for the import to
update.
schema:
type: string
responses:
"200":
description: The updated mailing list import details.
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListImportResponse"
example:
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
"400":
description: The updated mailing list import details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The updated mailing list import details.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The updated mailing list import details.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- mailing_list_import_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The updated mailing list import details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The updated mailing list import details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The updated mailing list import details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing List Imports
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListImportUpdate"
example:
description: Corrected description
metadata:
batch: spring_sale
description: The fields to update on the mailing list import.
get:
operationId: MailingListImports_get
summary: Get Mailing List Import
description: Retrieve a specific mailing list import by its ID.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`mailing_list_import_...`) for the import.
schema:
type: string
responses:
"200":
description: The requested mailing list import details.
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListImportResponse"
example:
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
"401":
description: The requested mailing list import details.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The requested mailing list import details.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- mailing_list_import_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The requested mailing list import details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The requested mailing list import details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The requested mailing list import details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing List Imports
delete:
operationId: MailingListImports_delete
summary: Delete Mailing List Import
description: |-
Delete a mailing list import.
This permanently deletes the import and its associated resources.
This operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`mailing_list_import_...`) for the import to
delete.
schema:
type: string
responses:
"200":
description: A confirmation object indicating the import was marked for deletion.
content:
application/json:
schema:
type: object
required:
- id
- deleted
properties:
id:
type: string
pattern: mailing_list_import_[a-zA-Z0-9]+
description: A unique ID prefixed with mailing_list_import_
readOnly: true
deleted:
type: boolean
enum:
- true
example:
id: mailing_list_import_123
deleted: true
"401":
description: A confirmation object indicating the import was marked for deletion.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A confirmation object indicating the import was marked for deletion.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- mailing_list_import_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A confirmation object indicating the import was marked for deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A confirmation object indicating the import was marked for deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A confirmation object indicating the import was marked for deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing List Imports
/print-mail/v1/mailing_lists:
post:
operationId: MailingLists_create
summary: Create Mailing List
description: Create a new mailing list.
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
responses:
"201":
description: The newly created mailing list.
content:
application/json:
schema:
$ref: "#/components/schemas/MailingList"
example:
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: []
"400":
description: The newly created mailing list.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The newly created mailing list.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The newly created mailing list.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The newly created mailing list.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The newly created mailing list.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The newly created mailing list.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing Lists
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListCreate"
example:
description: Test Mailing List
metadata:
campaign: launch
description: The details of the mailing list to create.
get:
operationId: MailingLists_list
summary: List Mailing Lists
description: >-
Retrieve a list of mailing lists.
Returns a paginated list of mailing lists associated with the
authenticated organization,
filterable by various parameters.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing mailing lists.
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListList"
example:
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: []
"400":
description: A list object containing mailing lists.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing mailing lists.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing mailing lists.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing mailing lists.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing Lists
/print-mail/v1/mailing_lists/{id}:
get:
operationId: MailingLists_get
summary: Get Mailing List
description: Retrieve a specific mailing list by its ID.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`mailing_list_...`) for the mailing list.
schema:
type: string
responses:
"200":
description: The requested mailing list details.
content:
application/json:
schema:
$ref: "#/components/schemas/MailingList"
example:
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: []
"401":
description: The requested mailing list details.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The requested mailing list details.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- mailing_list_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The requested mailing list details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The requested mailing list details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The requested mailing list details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing Lists
post:
operationId: MailingLists_update
summary: Update Mailing List
description: Update an existing mailing list.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`mailing_list_...`) for the mailing list to
update.
schema:
type: string
responses:
"200":
description: The updated mailing list details.
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListUpdate"
example:
description: Test Mailing List
metadata:
campaign: launch
"400":
description: The updated mailing list details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The updated mailing list details.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The updated mailing list details.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- mailing_list_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The updated mailing list details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The updated mailing list details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The updated mailing list details.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing Lists
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListUpdate"
example:
description: Updated Mailing List Description
description: The fields to update on the mailing list.
delete:
operationId: MailingLists_delete
summary: Delete Mailing List
description: |-
Delete a mailing list.
This permanently deletes the mailing list and its associations.
This operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`mailing_list_...`) for the mailing list to
delete.
schema:
type: string
responses:
"200":
description: A confirmation object indicating the mailing list was marked for
deletion.
content:
application/json:
schema:
type: object
required:
- id
- deleted
properties:
id:
type: string
pattern: mailing_list_[a-zA-Z0-9]+
description: A unique ID prefixed with mailing_list_
readOnly: true
deleted:
type: boolean
enum:
- true
"401":
description: A confirmation object indicating the mailing list was marked for
deletion.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A confirmation object indicating the mailing list was marked for
deletion.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- mailing_list_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A confirmation object indicating the mailing list was marked for
deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A confirmation object indicating the mailing list was marked for
deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A confirmation object indicating the mailing list was marked for
deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing Lists
/print-mail/v1/mailing_lists/{id}/jobs:
post:
operationId: MailingLists_mailingListJobs
summary: Submit a Mailing List Job
description: >-
Runs a mailing list job. Mailing list jobs allow you to add or remove
contacts
to your mailing list from mailing list imports or directly with contact
IDs.
Only one job can be ran at a time and jobs are only able to be ran while
the
mailing list has a `status` of "completed".
Once a job as successfully been kicked off, the mailing list will have a
`status`
of either `creating_contacts` or `removing_contacts` depending on which
job
was ran. After the job has finished, the mailing list will go back into
the
`completed` state where more jobs can be ran. If there are any errors
while
running a job, the `errors` field on the mailing list will contain a
list of
error objects which describe the errors.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/MailingList"
examples:
example0:
value:
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: []
example1:
value:
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: []
example2:
value:
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: []
example3:
value:
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: []
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- list_is_processing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- mailing_list_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- contacts_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- completed_mailing_list_imports_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Mailing Lists
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailingListJobsRequest"
examples:
example0:
value:
removeMailingListImports:
- mailing_list_import_123
- mailing_list_import_456
example1:
value:
addMailingListImports:
- mailing_list_import_123
- mailing_list_import_456
example2:
value:
removeContacts:
- contact_123
- contact_456
example3:
value:
addContacts:
- contact_123
- contact_456
/print-mail/v1/postcards:
post:
operationId: Postcards_createJSON_Postcards_createMultipart
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
description: >-
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 for a 2 page PDF where the first page is the front of the
postcard and the second page is the back Create a postcard via a
multipart/form-data request. Accepts the same
fields as the JSON create body (nested objects are bracket-encoded form
fields, e.g. `to[firstName]`); use this content type to upload the PDF
file directly.
summary: Create Postcard Create Postcard
responses:
"201":
description: the created Postcard.
content:
application/json:
schema:
anyOf:
- $ref: "#/components/schemas/Postcard"
- $ref: "#/components/schemas/Postcard"
"400":
description: the created Postcard.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: the created Postcard.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the created Postcard.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the created Postcard.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the created Postcard.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the created Postcard.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Postcards
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PostcardCreate"
examples:
Create Postcard with Premium Paper:
summary: Create Postcard with Premium Paper
value:
to: contact_456
from: contact_123
size: 6x4
paper: standard
frontHTML: Front
backHTML: Back
example1:
value:
to: contact_456
from: contact_123
size: 6x4
frontHTML: Front
backHTML: Back
multipart/form-data:
schema:
$ref: "#/components/schemas/PostcardCreateFormMultiPart"
description: The details of the postcard to create. The details of the postcard
to create.
get:
operationId: Postcards_list
summary: List Postcards
description: Get a list of postcards.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/PostcardList"
example:
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
paper: standard
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Postcards
/print-mail/v1/postcards/{id}:
get:
operationId: Postcards_get
summary: Get Postcard
description: Retrieve a postcard by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the postcard to retrieve.
schema:
type: string
responses:
"200":
description: the Postcard.
content:
application/json:
schema:
$ref: "#/components/schemas/Postcard"
example:
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
paper: standard
"401":
description: the Postcard.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the Postcard.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the Postcard.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the Postcard.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the Postcard.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Postcards
delete:
operationId: Postcards_delete
summary: Cancel Postcard
description: Cancel a postcard by ID. Note that this operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The ID of the postcard you want to cancel.
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Postcard"
example:
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
paper: standard
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Postcards
/print-mail/v1/postcards/{id}/cancellation:
post:
operationId: Postcards_cancelWithNote
summary: Cancel Postcard With Note
description: |-
Cancel a postcard by ID with a note. Note that this operation
cannot be undone and that only postcards with a status of `ready` can be
cancelled.
parameters:
- name: id
in: path
required: true
description: The ID of the postcard you want to cancel.
schema:
type: string
responses:
"200":
description: The cancelled postcard
content:
application/json:
schema:
$ref: "#/components/schemas/Postcard"
example:
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
paper: standard
"400":
description: The cancelled postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The cancelled postcard
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The cancelled postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The cancelled postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The cancelled postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The cancelled postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Postcards
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
note:
type: string
required:
- note
example:
note: Cancelling this postcard
description: The cancellation details including a note.
/print-mail/v1/postcards/{id}/progressions:
post:
operationId: Postcards_progress
summary: Progress Status
description: >-
Progresses a postcard's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order
would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
parameters:
- name: id
in: path
required: true
description: The ID of the postcard you want to progress.
schema:
type: string
responses:
"200":
description: The progressed postcard
content:
application/json:
schema:
$ref: "#/components/schemas/Postcard"
example:
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
paper: standard
"400":
description: The progressed postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The progressed postcard
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The progressed postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The progressed postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The progressed postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The progressed postcard
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Postcards
/print-mail/v1/postcards/{id}/url:
get:
operationId: Postcards_getURL
summary: Get Postcard Preview
description: >-
Retrieve a postcard preview URL.
This is only available for customers with our document management addon,
which offers
document generation and hosting capabilities. This endpoint has a much
higher rate limit
than the regular order retrieval endpoint, so it is suitable for
customer-facing use-cases.
parameters:
- name: id
in: path
required: true
description: The ID of the postcard to retrieve the preview URL for.
schema:
type: string
responses:
"200":
description: the Postcard Preview URL.
content:
application/json:
schema:
type: object
required:
- id
- object
- url
properties:
id:
type: string
pattern: postcard_[a-zA-Z0-9]+
description: A unique ID prefixed with postcard_
readOnly: true
object:
type: string
pattern: postcard_url
readOnly: true
url:
type: string
format: uri
description: A signed URL linking to the order preview PDF. The link remains
valid for 15 minutes from the time of the API call.
readOnly: true
example:
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
"401":
description: the Postcard Preview URL.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the Postcard Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the Postcard Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the Postcard Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the Postcard Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Postcards
/print-mail/v1/reports:
post:
operationId: Reports_createReport
summary: Create Saved Report
description: >-
Create a new saved report definition. Saved reports are SQL queries that
can be executed later to generate
full exports or samples.
If you just want to do ad-hoc queries, you should use the
`/reports/samples` endpoint.
parameters: []
responses:
"201":
description: The created Report object.
content:
application/json:
schema:
$ref: "#/components/schemas/Report"
example:
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
"400":
description: The created Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The created Report object.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The created Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The created Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The created Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The created Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReportCreate"
example:
sqlQuery: SELECT id, status FROM orders WHERE created_at > ?
description: Recent Orders
metadata:
team: Sales
description: The details of the report to create.
get:
operationId: Reports_listReports
summary: List Saved Reports
description: Retrieve a list of saved reports for your organization.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list of Report objects.
content:
application/json:
schema:
$ref: "#/components/schemas/ReportList"
example:
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
"400":
description: A list of Report objects.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list of Report objects.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list of Report objects.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list of Report objects.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
/print-mail/v1/reports/samples:
post:
operationId: Reports_runAdHocSample
summary: Run Ad-hoc Query
description: >-
Run an ad-hoc SQL query against your data lake and get a sample of the
results.
This is useful for quickly testing queries without saving them as a
report.
The query execution time and result size are limited.
parameters: []
responses:
"201":
description: A sample of the query results.
content:
application/json:
schema:
$ref: "#/components/schemas/ReportSample"
example:
id: sample_abc
report: report_123
records:
- id: order_1
- id: order_2
"400":
description: A sample of the query results.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A sample of the query results.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A sample of the query results.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A sample of the query results.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A sample of the query results.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A sample of the query results.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AdHocReportSampleCreate"
example:
sqlQuery: SELECT id FROM contacts LIMIT 5
params: []
limit: 5
description: Details of the ad-hoc query to run.
/print-mail/v1/reports/{id}:
post:
operationId: Reports_updateReport
summary: Update Report
description: Update an existing saved report definition. You can change the
query, description, or metadata.
parameters:
- name: id
in: path
required: true
description: The ID of the report to update.
schema:
type: string
responses:
"200":
description: The updated Report object.
content:
application/json:
schema:
$ref: "#/components/schemas/Report"
example:
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
"400":
description: The updated Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The updated Report object.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The updated Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The updated Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The updated Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The updated Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReportUpdate"
example:
description: Recent Orders (Updated)
metadata: null
description: The fields to update on the report.
get:
operationId: Reports_getReport
summary: Retrieve Saved Report
description: Retrieve the details of a specific saved report by its ID.
parameters:
- name: id
in: path
required: true
description: The ID of the report to retrieve.
schema:
type: string
responses:
"200":
description: The requested Report object.
content:
application/json:
schema:
$ref: "#/components/schemas/Report"
example:
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
"401":
description: The requested Report object.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The requested Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The requested Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The requested Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The requested Report object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
delete:
operationId: Reports_deleteReport
summary: Delete Saved Report
description: |-
Delete a saved report definition. This action cannot be undone.
Associated exports are not automatically deleted.
parameters:
- name: id
in: path
required: true
description: The ID of the report to delete.
schema:
type: string
responses:
"200":
description: Confirmation of the deletion.
content:
application/json:
schema:
$ref: "#/components/schemas/DeletedResponse"
example:
id: report_123
deleted: true
"401":
description: Confirmation of the deletion.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: Confirmation of the deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Confirmation of the deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Confirmation of the deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Confirmation of the deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
/print-mail/v1/reports/{id}/samples:
post:
operationId: Reports_runSavedReportSample
summary: Sample a Saved Report
description: >-
Run the query associated with a saved report and get a sample of the
results.
This allows getting up to 1000 rows of resutls but the runtime of the
query is limited to 30 seconds.
If you need more rows or longer runtime, you should create an export
from this report.
parameters:
- name: id
in: path
required: true
description: The ID of the saved report to sample.
schema:
type: string
responses:
"201":
description: A sample of the query results for the specified report.
content:
application/json:
schema:
$ref: "#/components/schemas/ReportSample"
example:
id: sample_abc
report: report_123
records:
- id: order_1
- id: order_2
"400":
description: A sample of the query results for the specified report.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A sample of the query results for the specified report.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A sample of the query results for the specified report.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A sample of the query results for the specified report.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A sample of the query results for the specified report.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A sample of the query results for the specified report.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SavedReportSampleCreate"
example:
params:
- 2023-10-01T00:00:00Z
limit: 10
description: Parameters and limits for the sample query.
/print-mail/v1/reports/{reportID}/exports:
post:
operationId: Reports_createReportExport
summary: Create a Report Export
description: >-
Create a new export job for a saved report. This runs the report's query
asynchronously and generates a downloadable CSV file with the full
results.
Your queries can run for up to 13 minutes the resulting file can be up
to 100mb large.
parameters:
- name: reportID
in: path
required: true
description: The ID of the report to export.
schema:
type: string
responses:
"201":
description: The created ReportExport object, representing the pending job.
content:
application/json:
schema:
$ref: "#/components/schemas/ReportExport"
example:
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
"400":
description: The created ReportExport object, representing the pending job.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The created ReportExport object, representing the pending job.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The created ReportExport object, representing the pending job.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The created ReportExport object, representing the pending job.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The created ReportExport object, representing the pending job.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The created ReportExport object, representing the pending job.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReportExportCreate"
example:
params:
- 2023-10-01T00:00:00Z
description: October Orders Export
description: Details for the export job, including any parameters.
/print-mail/v1/reports/{reportID}/exports/{exportID}:
get:
operationId: Reports_getReportExport
summary: Get Report Export
description: >-
Retrieve the status and details of a specific report export job.
Check the `outputURL` property for the download link once generation is
complete.
parameters:
- name: reportID
in: path
required: true
description: The ID of the report the export belongs to.
schema:
type: string
- name: exportID
in: path
required: true
description: The ID of the export job to retrieve.
schema:
type: string
responses:
"200":
description: The requested ReportExport object.
content:
application/json:
schema:
$ref: "#/components/schemas/ReportExport"
example:
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
"401":
description: The requested ReportExport object.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The requested ReportExport object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The requested ReportExport object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The requested ReportExport object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The requested ReportExport object.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
delete:
operationId: Reports_deleteReportExport
summary: Delete Report Export
description: >-
Delete a completed or failed report export job and its associated output
file (if any).
This action cannot be undone. You cannot delete an export that is still
generating.
parameters:
- name: reportID
in: path
required: true
description: The ID of the report the export belongs to.
schema:
type: string
- name: exportID
in: path
required: true
description: The ID of the export job to delete.
schema:
type: string
responses:
"200":
description: Confirmation of the deletion.
content:
application/json:
schema:
$ref: "#/components/schemas/DeletedResponse"
example:
id: report_export_123
deleted: true
"401":
description: Confirmation of the deletion.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: Confirmation of the deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Confirmation of the deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Confirmation of the deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Confirmation of the deletion.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Reports
/print-mail/v1/return_envelopes:
post:
operationId: ReturnEnvelopes_create
summary: Create Return Envelope
description: |-
Creates a new return envelope. Note that if there is already a return
envelope for the destination contact, this will fail with a
`return_envelope_already_exists_error`.
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
responses:
"201":
description: The newly created return envelope.
content:
application/json:
schema:
$ref: "#/components/schemas/ReturnEnvelope"
example:
id: return_envelope_7mhJUt25TnagyYzy1N81SJ
object: return_envelope
live: false
available: 0
to:
id: contact_pxd7wnnD1xY6H6etKNvjb4
companyName: PostGrid
addressLine1: 90 CANAL ST STE 600
city: BOSTON
provinceOrState: MA
postalOrZip: 90210-1234
countryCode: US
addressStatus: verified
createdAt: 2021-12-16T03:06:17.419Z
updatedAt: 2021-12-16T03:06:17.419Z
"400":
description: The newly created return envelope.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The newly created return envelope.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The newly created return envelope.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The newly created return envelope.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- return_envelope_already_exists_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The newly created return envelope.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The newly created return envelope.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Return Envelopes
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReturnEnvelopeCreate"
example:
to: contact_kFjQtFqJtRXgahx5vgc9mA
description: The details of the return envelope to create.
get:
operationId: ReturnEnvelopes_list
summary: List Return Envelopes
description: Gets a list of return envelopes for the user.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing return envelopes.
content:
application/json:
schema:
$ref: "#/components/schemas/ReturnEnvelopeList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: return_envelope_7mhJUt25TnagyYzy1N81SJ
object: return_envelope
live: false
available: 0
to:
id: contact_pxd7wnnD1xY6H6etKNvjb4
companyName: PostGrid
addressLine1: 90 CANAL ST STE 600
city: BOSTON
provinceOrState: MA
postalOrZip: 90210-1234
countryCode: US
addressStatus: verified
createdAt: 2021-12-16T03:06:17.419Z
updatedAt: 2021-12-16T03:06:17.419Z
"400":
description: A list object containing return envelopes.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing return envelopes.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing return envelopes.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing return envelopes.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Return Envelopes
/print-mail/v1/return_envelopes/{id}:
get:
operationId: ReturnEnvelopes_get
summary: Get Return Envelope
description: |-
Gets the information for a return envelope by `id`. This should be a
unique identifying string starting with `return_envelope_`.
parameters:
- name: id
in: path
required: true
description: The ID of the return envelope to retrieve.
schema:
type: string
responses:
"200":
description: The return envelope.
content:
application/json:
schema:
$ref: "#/components/schemas/ReturnEnvelope"
example:
id: return_envelope_7mhJUt25TnagyYzy1N81SJ
object: return_envelope
live: false
available: 0
to:
id: contact_pxd7wnnD1xY6H6etKNvjb4
companyName: PostGrid
addressLine1: 90 CANAL ST STE 600
city: BOSTON
provinceOrState: MA
postalOrZip: 90210-1234
countryCode: US
addressStatus: verified
createdAt: 2021-12-16T03:06:17.419Z
updatedAt: 2021-12-16T03:06:17.419Z
"401":
description: The return envelope.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The return envelope.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The return envelope.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The return envelope.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The return envelope.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Return Envelopes
/print-mail/v1/return_envelopes/{id}/orders:
post:
operationId: ReturnEnvelopes_createOrder
summary: Create Return Envelope Order
description: |-
Creates a batch order of return envelopes. The minimum order quantity is
5000.
parameters:
- name: id
in: path
required: true
description: The ID of the return envelope to order more envelopes for.
schema:
type: string
responses:
"201":
description: The newly created return envelope order.
content:
application/json:
schema:
$ref: "#/components/schemas/ReturnEnvelopeOrder"
example:
id: return_envelope_order_cJhFxQhs69MGhxu3L5NvyA
object: return_envelope_order
live: false
returnEnvelope: return_envelope_7mhJUt25TnagyYzy1N81SJ
quantityOrdered: 5000
status: placed
createdAt: 2021-12-16T03:23:22.617Z
updatedAt: 2021-12-16T03:23:22.617Z
"400":
description: The newly created return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The newly created return envelope order.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The newly created return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The newly created return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The newly created return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The newly created return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Return Envelopes
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- quantityOrdered
properties:
quantityOrdered:
type: integer
format: int32
minimum: 5000
description: The quantity of return envelopes ordered. Minimum 5000.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
example:
quantityOrdered: 5000
description: A batch of 5000
description: The details of the return envelope order to create.
get:
operationId: ReturnEnvelopes_listOrders
summary: List Return Envelope Orders
description: Gets a list of orders for the return envelope by `id`.
parameters:
- name: id
in: path
required: true
description: The ID of the return envelope whose orders should be listed.
schema:
type: string
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing return envelope orders.
content:
application/json:
schema:
$ref: "#/components/schemas/ReturnEnvelopeOrderList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: return_envelope_order_cJhFxQhs69MGhxu3L5NvyA
object: return_envelope_order
live: false
returnEnvelope: return_envelope_7mhJUt25TnagyYzy1N81SJ
quantityOrdered: 5000
status: placed
createdAt: 2021-12-16T03:23:22.617Z
updatedAt: 2021-12-16T03:23:22.617Z
"400":
description: A list object containing return envelope orders.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing return envelope orders.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing return envelope orders.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing return envelope orders.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Return Envelopes
/print-mail/v1/return_envelopes/{id}/orders/{orderID}:
get:
operationId: ReturnEnvelopes_getOrder
summary: Get Return Envelope Order
description: |-
Gets a specific return envelope order by return envelope ID as `id` and
return envelope order ID as `orderID`.
parameters:
- name: id
in: path
required: true
description: The ID of the return envelope.
schema:
type: string
- name: orderID
in: path
required: true
description: The ID of the return envelope order.
schema:
type: string
- name: expand[]
in: query
required: false
description: |-
Pass `expand[]=returnEnvelope` to expand the order's
`returnEnvelope` field into the full return envelope object.
schema:
type: array
items:
type: string
enum:
- returnEnvelope
responses:
"200":
description: The return envelope order.
content:
application/json:
schema:
$ref: "#/components/schemas/ReturnEnvelopeOrder"
example:
id: return_envelope_order_cJhFxQhs69MGhxu3L5NvyA
object: return_envelope_order
live: false
returnEnvelope: return_envelope_7mhJUt25TnagyYzy1N81SJ
quantityOrdered: 5000
status: placed
createdAt: 2021-12-16T03:23:22.617Z
updatedAt: 2021-12-16T03:23:22.617Z
"401":
description: The return envelope order.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Return Envelopes
delete:
operationId: ReturnEnvelopes_cancelOrder
summary: Cancel Return Envelope Order
description: |-
Cancels the return envelope order by `orderID` for the return envelope
by `id`. Note that this operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The ID of the return envelope.
schema:
type: string
- name: orderID
in: path
required: true
description: The ID of the return envelope order to cancel.
schema:
type: string
- name: expand[]
in: query
required: false
description: |-
Pass `expand[]=returnEnvelope` to expand the order's
`returnEnvelope` field into the full return envelope object.
schema:
type: array
items:
type: string
enum:
- returnEnvelope
responses:
"200":
description: The cancelled return envelope order.
content:
application/json:
schema:
$ref: "#/components/schemas/ReturnEnvelopeOrder"
example:
id: return_envelope_order_cJhFxQhs69MGhxu3L5NvyA
object: return_envelope_order
live: false
returnEnvelope: return_envelope_7mhJUt25TnagyYzy1N81SJ
quantityOrdered: 5000
status: cancelled
createdAt: 2021-12-16T03:23:22.617Z
updatedAt: 2021-12-16T03:23:22.617Z
"401":
description: The cancelled return envelope order.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The cancelled return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The cancelled return envelope order.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- return_envelope_order_cancel_failed_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The cancelled return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The cancelled return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Return Envelopes
/print-mail/v1/return_envelopes/{id}/orders/{orderID}/fills:
post:
operationId: ReturnEnvelopes_fillTestOrder
summary: Fill Test Return Envelope Order
description: |-
Fills the return envelope order by `orderID` for the return envelope by
`id`. This is only available in test mode and can be used to simulate
how a live order would be filled.
Note: this will fail with a `return_envelope_order_cannot_fill_error` if
the order's status is not `placed`.
parameters:
- name: id
in: path
required: true
description: The ID of the return envelope.
schema:
type: string
- name: orderID
in: path
required: true
description: The ID of the return envelope order to fill.
schema:
type: string
responses:
"200":
description: The filled return envelope order.
content:
application/json:
schema:
$ref: "#/components/schemas/ReturnEnvelopeOrder"
example:
id: return_envelope_order_cJhFxQhs69MGhxu3L5NvyA
object: return_envelope_order
live: false
returnEnvelope: return_envelope_7mhJUt25TnagyYzy1N81SJ
quantityOrdered: 5000
status: filled
createdAt: 2021-12-16T03:23:22.617Z
updatedAt: 2021-12-16T03:23:22.617Z
quantityFilled: 5000
"400":
description: The filled return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The filled return envelope order.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The filled return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The filled return envelope order.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- return_envelope_order_cannot_fill_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- return_envelope_order_cannot_fill_live_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The filled return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The filled return envelope order.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Return Envelopes
/print-mail/v1/self_mailers:
post:
operationId: SelfMailers_createJSON_SelfMailers_createMultipart
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
description: >-
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 for a 2 page PDF where the first page is the outside of the
self-mailer and the second page is the inside Create a self-mailer via a
multipart/form-data request. Accepts the same
fields as the JSON create body (nested objects are bracket-encoded form
fields, e.g. `to[firstName]`); use this content type to upload the PDF
file directly.
summary: Create Self Mailer Create Self Mailer
responses:
"201":
description: the created SelfMailer.
content:
application/json:
schema:
anyOf:
- $ref: "#/components/schemas/SelfMailer"
- $ref: "#/components/schemas/SelfMailer"
"400":
description: the created SelfMailer.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: the created SelfMailer.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the created SelfMailer.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the created SelfMailer.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the created SelfMailer.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the created SelfMailer.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Self Mailers
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SelfMailerCreate"
example:
to: contact_456
from: contact_123
size: 8.5x11_bifold
insideHTML: Inside
outsideHTML: Outside
multipart/form-data:
schema:
$ref: "#/components/schemas/SelfMailerCreateFormMultiPart"
description: The details of the self-mailer to create. The details of the
self-mailer to create.
get:
operationId: SelfMailers_list
summary: List Self Mailers
description: Get a list of self-mailers.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/SelfMailerList"
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Self Mailers
/print-mail/v1/self_mailers/{id}:
get:
operationId: SelfMailers_get
summary: Get Self Mailer
description: Retrieve a self-mailer by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the self-mailer to retrieve.
schema:
type: string
responses:
"200":
description: the Self-Mailer.
content:
application/json:
schema:
$ref: "#/components/schemas/SelfMailer"
example:
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
"401":
description: the Self-Mailer.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the Self-Mailer.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the Self-Mailer.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the Self-Mailer.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the Self-Mailer.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Self Mailers
delete:
operationId: SelfMailers_delete
summary: Cancel Self Mailer
description: Cancel a self-mailer by ID. Note that this operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The ID of the self-mailer you want to cancel.
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/SelfMailer"
example:
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
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Self Mailers
/print-mail/v1/self_mailers/{id}/progressions:
post:
operationId: SelfMailers_progress
summary: Progress Status
description: >-
Progresses a self-mailer's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order
would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
parameters:
- name: id
in: path
required: true
description: The ID of the self-mailer you want to progress.
schema:
type: string
responses:
"200":
description: The progressed self-mailer
content:
application/json:
schema:
$ref: "#/components/schemas/SelfMailer"
example:
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
"400":
description: The progressed self-mailer
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The progressed self-mailer
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The progressed self-mailer
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The progressed self-mailer
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The progressed self-mailer
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The progressed self-mailer
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Self Mailers
/print-mail/v1/self_mailers/{id}/url:
get:
operationId: SelfMailers_getURL
summary: Get Self Mailer Preview
description: >-
Retrieve a self-mailer preview URL.
This is only available for customers with our document management addon,
which offers
document generation and hosting capabilities. This endpoint has a much
higher rate limit
than the regular order retrieval endpoint, so it is suitable for
customer-facing use-cases.
parameters:
- name: id
in: path
required: true
description: The ID of the self-mailer to retrieve the preview URL for.
schema:
type: string
responses:
"200":
description: the Self-Mailer Preview URL.
content:
application/json:
schema:
type: object
required:
- id
- object
- url
properties:
id:
type: string
pattern: self_mailer_[a-zA-Z0-9]+
description: A unique ID prefixed with self_mailer_
readOnly: true
object:
type: string
pattern: self_mailer_url
readOnly: true
url:
type: string
format: uri
description: A signed URL linking to the order preview PDF. The link remains
valid for 15 minutes from the time of the API call.
readOnly: true
example:
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
"401":
description: the Self-Mailer Preview URL.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the Self-Mailer Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the Self-Mailer Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the Self-Mailer Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the Self-Mailer Preview URL.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Self Mailers
/print-mail/v1/snap_packs:
post:
operationId: SnapPacks_createJSON_SnapPacks_createMultipart
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
description: >-
Create a snap pack. You can supply one of the following:
- HTML content for the inside and outside of the snap pack
- Template IDs for the inside and outside of the snap pack
- A URL for a two-page PDF that matches the snap pack layout Create a
snap pack via a multipart/form-data request. Accepts the same
fields as the JSON create body (nested objects are bracket-encoded form
fields, e.g. `to[firstName]`); use this content type to upload the PDF
file directly.
summary: Create Snap Pack Create Snap Pack
responses:
"201":
description: The created snap pack.
content:
application/json:
schema:
anyOf:
- $ref: "#/components/schemas/SnapPack"
- $ref: "#/components/schemas/SnapPack"
"400":
description: The created snap pack.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The created snap pack.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The created snap pack.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The created snap pack.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The created snap pack.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The created snap pack.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Snap Packs
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SnapPackCreate"
example:
to: contact_456
from: contact_123
size: 8.5x11_bifold_v
insideHTML: Inside
outsideHTML: Outside
multipart/form-data:
schema:
$ref: "#/components/schemas/SnapPackCreateFormMultiPart"
description: The details of the snap pack to create. The details of the snap
pack to create.
get:
operationId: SnapPacks_list
summary: List Snap Packs
description: Get a list of snap packs.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/SnapPackList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: snap_pack_123456
object: snap_pack
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_v
insideHTML: Inside
outsideHTML: Outside
sendDate: 2020-11-12T23:23:47.974Z
createdAt: 2020-11-12T23:23:47.974Z
updatedAt: 2020-11-12T23:23:47.974Z
mailingClass: usps_first_class
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Snap Packs
/print-mail/v1/snap_packs/capabilities:
get:
operationId: SnapPacks_capabilities
summary: Capabilities
description: Provides sizes and mailing classes available for the destination.
parameters:
- name: destinationCountryCode
in: query
required: false
description: >-
The country code of where the snap pack will be sent to.
One of `mailingList` or `destinationCountryCode` must be supplied
but
not both.
schema:
type: string
explode: false
- name: mailingList
in: query
required: false
description: >-
Sources destination countries from the provided mailing list.
One of `mailingList` or `destinationCountryCode` must be supplied
but
not both.
schema:
type: string
explode: false
- name: returnCountryCode
in: query
required: true
description: The country code where mail may be returned to.
schema:
type: string
explode: false
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/SnapPackCapabilities"
example:
sizes:
- 8.5x11_bifold_v
mailingClasses:
- express
- usps_express_2_day
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Snap Packs
/print-mail/v1/snap_packs/{id}:
get:
operationId: SnapPacks_get
summary: Get Snap Pack
description: Retrieve a snap pack by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the snap pack to retrieve.
schema:
type: string
responses:
"200":
description: The snap pack.
content:
application/json:
schema:
$ref: "#/components/schemas/SnapPack"
example:
id: snap_pack_123456
object: snap_pack
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_v
insideHTML: Inside
outsideHTML: Outside
sendDate: 2020-11-12T23:23:47.974Z
createdAt: 2020-11-12T23:23:47.974Z
updatedAt: 2020-11-12T23:23:47.974Z
mailingClass: usps_first_class
"401":
description: The snap pack.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The snap pack.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The snap pack.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The snap pack.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The snap pack.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Snap Packs
delete:
operationId: SnapPacks_cancel
summary: Cancel
description: |-
Cancel a snap pack by ID. Note that this operation cannot be undone and
that only snap packs with a status of `ready` can be cancelled.
parameters:
- name: id
in: path
required: true
description: The ID of the snap pack you want to cancel.
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/SnapPack"
example:
id: snap_pack_123456
object: snap_pack
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_v
insideHTML: Inside
outsideHTML: Outside
sendDate: 2020-11-12T23:23:47.974Z
createdAt: 2020-11-12T23:23:47.974Z
updatedAt: 2020-11-12T23:23:47.974Z
mailingClass: usps_first_class
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Snap Packs
/print-mail/v1/snap_packs/{id}/progressions:
post:
operationId: SnapPacks_progress
summary: Progress Status
description: >-
Progresses a snap pack's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order
would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
parameters:
- name: id
in: path
required: true
description: The ID of the snap pack you want to progress.
schema:
type: string
responses:
"200":
description: The progressed snap pack
content:
application/json:
schema:
$ref: "#/components/schemas/SnapPack"
example:
id: snap_pack_123456
object: snap_pack
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_v
insideHTML: Inside
outsideHTML: Outside
sendDate: 2020-11-12T23:23:47.974Z
createdAt: 2020-11-12T23:23:47.974Z
updatedAt: 2020-11-12T23:23:47.974Z
mailingClass: usps_first_class
"400":
description: The progressed snap pack
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The progressed snap pack
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The progressed snap pack
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The progressed snap pack
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The progressed snap pack
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The progressed snap pack
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Snap Packs
/print-mail/v1/sub_organizations:
post:
operationId: SubOrganizations_create
summary: Create a sub-organization.
description: >-
When creating a user through the API, the verifiedEmail field will
automatically be
set to true. However, if public signups are used, the email will need to
be verified
by the user.
parameters: []
responses:
"201":
description: The request has succeeded and a new resource has been created as a
result.
content:
application/json:
schema:
type: object
properties:
user:
allOf:
- $ref: "#/components/schemas/User"
description: The initial user of the sub-organization.
subOrganization:
allOf:
- $ref: "#/components/schemas/SubOrganization"
description: The sub-organization object.
required:
- user
- subOrganization
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"403":
description: Access is forbidden.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- sub_organizations_not_enabled_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- sub_organization_limit_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Sub-Organizations
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SubOrganizationCreate"
example:
email: suborg@postgrid.com
organizationName: PostGrid
phoneNumber: "9059059059"
password: very-strong-password
name: Calvin
countryCode: CA
get:
operationId: SubOrganizations_list
summary: List sub-organizations.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/SubOrganizationList"
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"403":
description: Access is forbidden.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- sub_organizations_not_enabled_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Sub-Organizations
/print-mail/v1/sub_organizations/{id}:
get:
operationId: SubOrganizations_get
summary: Get a sub-organization.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/SubOrganization"
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- invalid_sub_organization_id_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"403":
description: Access is forbidden.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- sub_organizations_not_enabled_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- sub_organization_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Sub-Organizations
/print-mail/v1/sub_organizations/{id}/users:
get:
operationId: SubOrganizations_listUsers
summary: List users for a sub-organization.
parameters:
- name: id
in: path
required: true
schema:
type: string
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/UserWithoutAPIKeys"
example:
- id: user_abc123def456ghi6789
pendingInvite: false
organization: org_abc123def456ghi6789
email: user@postgrid.com
name: Calvin
verifiedEmail: true
roles:
- role_abc123def456ghi6789
tags:
- Sub-Organizations
/print-mail/v1/targeted_list_builds:
post:
operationId: TargetedListBuilds_create
summary: Create Targeted List Build
description: |-
Create a new targeted list build. A quote will be generated
asynchronously based on the provided filters.
parameters:
- name: idempotency-key
in: header
required: false
schema:
type: string
responses:
"201":
description: The newly created targeted list build.
content:
application/json:
schema:
$ref: "#/components/schemas/TargetedListBuild"
example:
id: targeted_list_build_123
live: false
description: Q1 prospecting list
metadata:
campaign: q1_prospecting
createdAt: 2026-01-05T10:00:00Z
updatedAt: 2026-01-05T10:01:30Z
organization: organization_123
status: quote_ready
usCompanies:
postalCodes:
- "10001"
- "10002"
industries:
- software
employeeCount:
- 10
- 500
limit: 1000
quote:
generatedAt: 2026-01-05T10:01:30Z
count: 1000
pricePerContactCents: 11.98
previewRecords:
- name: Acm***
formattedAddress: 12** Main St, New York, NY, 100**
errors: []
"400":
description: The newly created targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The newly created targeted list build.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The newly created targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The newly created targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The newly created targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The newly created targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Targeted List Builds
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TargetedListBuildCreate"
example:
description: Q1 prospecting list
metadata:
campaign: q1_prospecting
usCompanies:
postalCodes:
- "10001"
- "10002"
industries:
- software
employeeCount:
- 10
- 500
limit: 1000
description: The filters and metadata for the new list build.
get:
operationId: TargetedListBuilds_list
summary: List Targeted List Builds
description: |-
Retrieve a paginated list of targeted list builds for the authenticated
organization, ordered from most recently updated to least recently
updated.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing targeted list builds.
content:
application/json:
schema:
$ref: "#/components/schemas/TargetedListBuildList"
example:
object: list
totalCount: 1
skip: 0
limit: 10
data:
- id: targeted_list_build_123
live: false
description: Q1 prospecting list
metadata:
campaign: q1_prospecting
createdAt: 2026-01-05T10:00:00Z
updatedAt: 2026-01-05T10:01:30Z
organization: organization_123
status: quote_ready
usCompanies:
postalCodes:
- "10001"
- "10002"
industries:
- software
employeeCount:
- 10
- 500
limit: 1000
quote:
generatedAt: 2026-01-05T10:01:30Z
count: 1000
pricePerContactCents: 11.98
previewRecords:
- name: Acm***
formattedAddress: 12** Main St, New York, NY, 100**
errors: []
"400":
description: A list object containing targeted list builds.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing targeted list builds.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing targeted list builds.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing targeted list builds.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Targeted List Builds
/print-mail/v1/targeted_list_builds/filters/autocomplete:
post:
operationId: TargetedListBuilds_autocomplete
summary: Autocomplete Filter Values
description: |-
Return a list of autocomplete suggestions for a given filter field
(currently only `industry` is supported). Useful when building a UI
around the `industries` company filter.
parameters: []
responses:
"200":
description: A list of autocomplete suggestions.
content:
application/json:
schema:
$ref: "#/components/schemas/TargetedListBuildAutocompleteResponse"
example:
object: list
data:
- value: software
type: industry
- value: software development
type: industry
"400":
description: A list of autocomplete suggestions.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list of autocomplete suggestions.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A list of autocomplete suggestions.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A list of autocomplete suggestions.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list of autocomplete suggestions.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list of autocomplete suggestions.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Targeted List Builds
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TargetedListBuildAutocompleteRequest"
example:
field: industry
text: soft
size: 5
description: The field to autocomplete and an optional text prefix.
/print-mail/v1/targeted_list_builds/{id}:
get:
operationId: TargetedListBuilds_get
summary: Get Targeted List Build
description: Retrieve a specific targeted list build by its ID.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`targeted_list_build_...`) for the list build.
schema:
type: string
responses:
"200":
description: The requested targeted list build.
content:
application/json:
schema:
$ref: "#/components/schemas/TargetedListBuild"
example:
id: targeted_list_build_123
live: false
description: Q1 prospecting list
metadata:
campaign: q1_prospecting
createdAt: 2026-01-05T10:00:00Z
updatedAt: 2026-01-05T10:01:30Z
organization: organization_123
status: quote_ready
usCompanies:
postalCodes:
- "10001"
- "10002"
industries:
- software
employeeCount:
- 10
- 500
limit: 1000
quote:
generatedAt: 2026-01-05T10:01:30Z
count: 1000
pricePerContactCents: 11.98
previewRecords:
- name: Acm***
formattedAddress: 12** Main St, New York, NY, 100**
errors: []
"401":
description: The requested targeted list build.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The requested targeted list build.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- targeted_list_build_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The requested targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The requested targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The requested targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Targeted List Builds
post:
operationId: TargetedListBuilds_update
summary: Update Targeted List Build
description: |-
Update an existing targeted list build. Only builds that have not yet
been confirmed may be updated. Updating the filters or `limit` will
reset the build's status back to `generating_quote` and a new quote
will be generated.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`targeted_list_build_...`) for the list build.
schema:
type: string
responses:
"200":
description: The updated targeted list build.
content:
application/json:
schema:
$ref: "#/components/schemas/TargetedListBuild"
example:
id: targeted_list_build_123
live: false
description: Q1 prospecting list
metadata:
campaign: q1_prospecting
createdAt: 2026-01-05T10:00:00Z
updatedAt: 2026-01-05T10:01:30Z
organization: organization_123
status: quote_ready
usCompanies:
postalCodes:
- "10001"
- "10002"
industries:
- software
employeeCount:
- 10
- 500
limit: 1000
quote:
generatedAt: 2026-01-05T10:01:30Z
count: 1000
pricePerContactCents: 11.98
previewRecords:
- name: Acm***
formattedAddress: 12** Main St, New York, NY, 100**
errors: []
"400":
description: The updated targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The updated targeted list build.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The updated targeted list build.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- targeted_list_build_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The updated targeted list build.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- list_build_already_confirmed_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The updated targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The updated targeted list build.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Targeted List Builds
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TargetedListBuildUpdate"
example:
usCompanies:
postalCodes:
- "10001"
- "10002"
- "10003"
industries:
- software
- fintech
employeeCount:
- 50
- 1000
limit: 2000
description: The fields to update on the list build.
delete:
operationId: TargetedListBuilds_delete
summary: Delete Targeted List Build
description: |-
Delete a targeted list build. List builds can only be deleted before
they have been confirmed — once a build has transitioned to
`creating_list` or `completed` it cannot be deleted.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`targeted_list_build_...`) for the list build.
schema:
type: string
responses:
"200":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- id
- deleted
properties:
id:
type: string
pattern: targeted_list_build_[a-zA-Z0-9]+
description: A unique ID prefixed with targeted_list_build_
readOnly: true
deleted:
type: boolean
enum:
- true
example:
id: targeted_list_build_123
deleted: true
"401":
description: A deletion confirmation.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A deletion confirmation.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- targeted_list_build_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A deletion confirmation.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- cannot_delete_list_build_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Targeted List Builds
/print-mail/v1/targeted_list_builds/{id}/confirm:
post:
operationId: TargetedListBuilds_confirm
summary: Confirm Targeted List Build
description: |-
Confirm a targeted list build whose quote is ready. This deducts the
appropriate amount of list build credits from the organization (in
live mode) and kicks off the asynchronous creation of the underlying
mailing list.
parameters:
- name: id
in: path
required: true
description: The unique identifier (`targeted_list_build_...`) for the list build.
schema:
type: string
responses:
"200":
description: The targeted list build after transitioning to `creating_list`.
content:
application/json:
schema:
$ref: "#/components/schemas/TargetedListBuild"
example:
id: targeted_list_build_123
live: false
description: Q1 prospecting list
metadata:
campaign: q1_prospecting
createdAt: 2026-01-05T10:00:00Z
updatedAt: 2026-01-05T10:05:00Z
organization: organization_123
status: creating_list
usCompanies:
postalCodes:
- "10001"
- "10002"
industries:
- software
employeeCount:
- 10
- 500
limit: 1000
quote:
generatedAt: 2026-01-05T10:01:30Z
count: 1000
pricePerContactCents: 11.98
confirmedAt: 2026-01-05T10:05:00Z
buildProgressPercent: 0
errors: []
"400":
description: The targeted list build after transitioning to `creating_list`.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The targeted list build after transitioning to `creating_list`.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The targeted list build after transitioning to `creating_list`.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- targeted_list_build_not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The targeted list build after transitioning to `creating_list`.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- list_build_quote_not_ready_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- list_build_already_confirmed_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The targeted list build after transitioning to `creating_list`.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The targeted list build after transitioning to `creating_list`.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Targeted List Builds
/print-mail/v1/template_editor_sessions:
post:
operationId: TemplateEditorSessions_create
summary: Create Session
description: |-
Create a Template Editor Session.
Note that if no `backURL` is supplied, PostGrid removes the Back button
from the editor page. This is ideal for when you `iframe` the editor.
parameters: []
responses:
"201":
description: The newly created Template Editor Session.
content:
application/json:
schema:
$ref: "#/components/schemas/TemplateEditorSession"
examples:
Create Session with Trackers:
summary: Create Session with Trackers
value:
id: template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c
object: template_editor_session
live: false
template: template_eYxcbMKPZEZPk71ZJPA6Yz
backURL: https://postgrid.com
title: My Editor Session
trackers:
- tracker_123456789abcdefghijklmnopqrstuvwxyz
url: https://dashboard.postgrid.com/embed/template_editor_sessions/template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c
createdAt: 2023-07-05T19:36:01.369Z
Create Session:
summary: Create Session
value:
id: template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c
object: template_editor_session
live: false
template: template_eYxcbMKPZEZPk71ZJPA6Yz
backURL: https://postgrid.com
title: My Editor Session
trackers: none
url: https://dashboard.postgrid.com/embed/template_editor_sessions/template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c
createdAt: 2023-07-05T19:36:01.369Z
"400":
description: The newly created Template Editor Session.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The newly created Template Editor Session.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The newly created Template Editor Session.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The newly created Template Editor Session.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The newly created Template Editor Session.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The newly created Template Editor Session.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Template Editor Sessions
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TemplateEditorSessionCreate"
examples:
Create Session with Trackers:
summary: Create Session with Trackers
value:
template: template_eYxcbMKPZEZPk71ZJPA6Yz
backURL: https://postgrid.com
title: My Editor Session
trackers:
- tracker_123456789abcdefghijklmnopqrstuvwxyz
Create Session:
summary: Create Session
value:
template: template_eYxcbMKPZEZPk71ZJPA6Yz
backURL: https://postgrid.com
title: My Editor Session
description: The details of the Template Editor Session to create.
get:
operationId: TemplateEditorSessions_list
summary: List Sessions
description: Retrieve a paginated list of Template Editor Sessions.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing Template Editor Sessions.
content:
application/json:
schema:
$ref: "#/components/schemas/TemplateEditorSessionList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c
object: template_editor_session
live: false
template: template_eYxcbMKPZEZPk71ZJPA6Yz
backURL: https://postgrid.com
title: My Editor Session
trackers: none
url: https://dashboard.postgrid.com/embed/template_editor_sessions/template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c
createdAt: 2023-07-05T19:36:01.369Z
"400":
description: A list object containing Template Editor Sessions.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing Template Editor Sessions.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing Template Editor Sessions.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing Template Editor Sessions.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Template Editor Sessions
/print-mail/v1/template_editor_sessions/{id}:
delete:
operationId: TemplateEditorSessions_delete
summary: Delete Session
description: Delete a Template Editor Session by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the Template Editor Session to delete.
schema:
type: string
responses:
"200":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- id
- object
- deleted
properties:
id:
type: string
pattern: template_editor_session_[a-zA-Z0-9]+
description: A unique ID prefixed with `template_editor_session_`.
readOnly: true
object:
type: string
enum:
- template_editor_session
description: Always `template_editor_session`.
readOnly: true
deleted:
type: boolean
enum:
- true
example:
id: template_editor_session_vmb3aXRJFzHb4oNRP2XMUZiTTBDtC91CSgQeqUrQfhSqq5P9wAGpmX5UkftueTubMN
object: template_editor_session
deleted: true
"401":
description: A deletion confirmation.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Template Editor Sessions
/print-mail/v1/templates:
post:
operationId: Templates_create
summary: Create Template
description: Create a template. Note that if you want to create a template that
works with our template editor, you must use our dashboard.
parameters: []
responses:
"201":
description: The request has succeeded and a new resource has been created as a
result.
content:
application/json:
schema:
$ref: "#/components/schemas/Template"
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Templates
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TemplateCreate"
example:
description: Test
html: Hello {{to.firstName}}
get:
operationId: Templates_list
summary: List Templates
description: Get a list of templates.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/TemplateList"
example:
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
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Templates
/print-mail/v1/templates/{id}:
get:
operationId: Templates_get
summary: Get Template
description: Retrieve a template by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the template to retrieve.
schema:
type: string
responses:
"200":
description: the Template.
content:
application/json:
schema:
$ref: "#/components/schemas/Template"
example:
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
"401":
description: the Template.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the Template.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the Template.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the Template.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the Template.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Templates
post:
operationId: Templates_update
summary: Update Template
description: Update a template by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the template you want to update.
schema:
type: string
responses:
"200":
description: the updated Template.
content:
application/json:
schema:
$ref: "#/components/schemas/Template"
example:
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
"400":
description: the updated Template.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: the updated Template.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: the updated Template.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: the updated Template.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: the updated Template.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: the updated Template.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Templates
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TemplateUpdate"
example:
description: Test
html: Hello {{to.firstName}}!
delete:
operationId: Templates_delete
summary: Delete Template
description: Delete a template by ID. Note that this operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The ID of the template you want to delete.
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- object
- id
- deleted
properties:
object:
type: string
enum:
- template
description: Always `template`.
readOnly: true
id:
type: string
pattern: template_[a-zA-Z0-9]+
description: A unique ID prefixed with template_
readOnly: true
deleted:
type: boolean
enum:
- true
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Templates
/print-mail/v1/trackers:
post:
operationId: Trackers_create
summary: Create Tracker
description: Create a Tracker.
parameters: []
responses:
"201":
description: The newly created Tracker.
content:
application/json:
schema:
$ref: "#/components/schemas/Tracker"
example:
id: tracker_123456789abcdefghijklmnopqrstuvwxyz
object: tracker
live: false
redirectURLTemplate: https://postgrid.com?name={{to.firstName}}
urlExpireAfterDays: 30
visitCount: 0
uniqueVisitCount: 0
createdAt: 2020-11-12T23:30:12.581Z
updatedAt: 2020-11-12T23:30:12.581Z
"400":
description: The newly created Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The newly created Tracker.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The newly created Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The newly created Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The newly created Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The newly created Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Trackers
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TrackerCreate"
example:
redirectURLTemplate: https://postgrid.com?name={{to.firstName}}
urlExpireAfterDays: 30
description: The details of the Tracker to create.
get:
operationId: Trackers_list
summary: List Trackers
description: Retrieve a paginated list of Trackers.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing Trackers.
content:
application/json:
schema:
$ref: "#/components/schemas/TrackerList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: tracker_123456789abcdefghijklmnopqrstuvwxyz
object: tracker
live: false
redirectURLTemplate: https://postgrid.com?firstName={{to.firstName}}
urlExpireAfterDays: 90
visitCount: 0
uniqueVisitCount: 0
createdAt: 2020-11-12T23:30:12.581Z
updatedAt: 2020-11-12T23:31:12.581Z
"400":
description: A list object containing Trackers.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing Trackers.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing Trackers.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing Trackers.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Trackers
/print-mail/v1/trackers/{id}:
post:
operationId: Trackers_update
summary: Update Tracker
description: Update a Tracker by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the Tracker to update.
schema:
type: string
responses:
"200":
description: The updated Tracker.
content:
application/json:
schema:
$ref: "#/components/schemas/Tracker"
example:
id: tracker_123456789abcdefghijklmnopqrstuvwxyz
object: tracker
live: false
redirectURLTemplate: https://postgrid.com?firstName={{to.firstName}}
urlExpireAfterDays: 90
visitCount: 0
uniqueVisitCount: 0
createdAt: 2020-11-12T23:30:12.581Z
updatedAt: 2020-11-12T23:31:12.581Z
"400":
description: The updated Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The updated Tracker.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The updated Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The updated Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The updated Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The updated Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Trackers
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TrackerUpdate"
example:
redirectURLTemplate: https://postgrid.com?firstName={{to.firstName}}
urlExpireAfterDays: 90
description: The fields to update on the Tracker.
get:
operationId: Trackers_get
summary: Get Tracker
description: Retrieve a Tracker by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the Tracker to retrieve.
schema:
type: string
responses:
"200":
description: The requested Tracker.
content:
application/json:
schema:
$ref: "#/components/schemas/Tracker"
example:
id: tracker_123456789abcdefghijklmnopqrstuvwxyz
object: tracker
live: false
redirectURLTemplate: https://postgrid.com?firstName={{to.firstName}}
urlExpireAfterDays: 90
visitCount: 0
uniqueVisitCount: 0
createdAt: 2020-11-12T23:30:12.581Z
updatedAt: 2020-11-12T23:31:12.581Z
"401":
description: The requested Tracker.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The requested Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The requested Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The requested Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The requested Tracker.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Trackers
delete:
operationId: Trackers_delete
summary: Delete Tracker
description: Delete a Tracker by ID. Note that this operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The ID of the Tracker to delete.
schema:
type: string
responses:
"200":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- id
- deleted
properties:
object:
type: string
enum:
- tracker
description: Always `tracker`.
readOnly: true
id:
type: string
pattern: tracker_[a-zA-Z0-9]+
description: A unique ID prefixed with tracker_
readOnly: true
deleted:
type: boolean
enum:
- true
example:
id: tracker_123456789abcdefghijklmnopqrstuvwxyz
object: tracker
deleted: true
"401":
description: A deletion confirmation.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Trackers
/print-mail/v1/trackers/{id}/visits:
get:
operationId: Trackers_listVisits
summary: List Tracker Visits
description: Retrieve a paginated list of visits for a Tracker.
parameters:
- name: id
in: path
required: true
description: The ID of the Tracker whose visits should be listed.
schema:
type: string
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing Tracker Visits.
content:
application/json:
schema:
$ref: "#/components/schemas/TrackerVisitList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: tracker_visit_123456789abcdefghijklmnopqrstuvwxyz
object: tracker_visit
live: false
tracker: tracker_123456789abcdefghijklmnopqrstuvwxyz
orderID: order_123456789abcdefghijklmnopqrstuvwxyz
device: Device Unknown
ipAddress: Unknown IP Address
createdAt: 2020-11-12T23:30:12.581Z
updatedAt: 2020-11-12T23:31:12.581Z
"400":
description: A list object containing Tracker Visits.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing Tracker Visits.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing Tracker Visits.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing Tracker Visits.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Trackers
/print-mail/v1/virtual_mailboxes:
post:
operationId: VirtualMailboxes_create
summary: Create Virtual Mailbox
description: >-
Creates a new virtual mailbox.
In live mode, the virtual mailbox will be pending assignment and cannot
be used until it has been assigned and activated by our team. You will
be
notified via email once the virtual mailbox has been activated.
In test mode, the virtual mailbox will be activated immediately upon
creation.
parameters: []
responses:
"201":
description: The request has succeeded and a new resource has been created as a
result.
content:
application/json:
schema:
$ref: "#/components/schemas/VirtualMailbox"
example:
id: virtual_mailbox_abcdefg123456890
object: virtual_mailbox
live: true
status: pending_assignment
capabilities:
forwardMailTo:
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
envelopeScans: true
countryCode: US
createdAt: 2025-11-01T15:08:41.052Z
updatedAt: 2025-11-01T15:08:41.052Z
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Virtual Mailboxes
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/VirtualMailboxCreate"
example:
capabilities:
envelopeScans: true
forwardMailTo: contact_pxd7wnnD1xY6H6etKNvjb4
countryCode: US
get:
operationId: VirtualMailboxes_list
summary: List Virtual Mailboxes
description: |-
Lists virtual mailboxes. You can use the `skip`, `limit`, and `search`
query parameters to refine the list.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/VirtualMailbox"
example:
object: list
totalCount: 1
skip: 0
limit: 10
data:
- id: virtual_mailbox_abcdefg123456890
object: virtual_mailbox
live: true
status: pending_assignment
capabilities:
forwardMailTo:
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
envelopeScans: true
countryCode: US
createdAt: 2025-11-01T15:08:41.052Z
updatedAt: 2025-11-01T15:08:41.052Z
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Virtual Mailboxes
/print-mail/v1/virtual_mailboxes/{id}:
get:
operationId: VirtualMailboxes_retrieve
summary: Retrieve Virtual Mailbox
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/VirtualMailbox"
example:
id: virtual_mailbox_abcdefg123456890
object: virtual_mailbox
live: true
status: pending_assignment
capabilities:
forwardMailTo:
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
envelopeScans: true
countryCode: US
createdAt: 2025-11-01T15:08:41.052Z
updatedAt: 2025-11-01T15:08:41.052Z
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Virtual Mailboxes
/print-mail/v1/virtual_mailboxes/{id}/address:
get:
operationId: VirtualMailboxes_retrieveAddress
summary: Retrieve Physical Address
description: Retrieves the physical address of the virtual mailbox.
parameters:
- name: id
in: path
required: true
description: The ID of the virtual mailbox
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxAddress"
example:
addressLine1: 145 Mulberry st
city: New York
provinceOrState: NY
postalOrZip: "10013"
countryCode: US
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- virtual_mailbox_not_assigned_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Virtual Mailboxes
/print-mail/v1/virtual_mailboxes/{id}/items:
get:
operationId: VirtualMailboxes_listItems
summary: List Virtual Mailbox Items
description: Lists items for a virtual mailbox.
parameters:
- name: id
in: path
required: true
description: The ID of the virtual mailbox whose items you wish to list
schema:
type: string
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/VirtualMailboxItem"
example:
object: list
totalCount: 1
skip: 0
limit: 10
data:
- id: virtual_mailbox_item_abcdefg123456890
object: virtual_mailbox_item
live: true
virtualMailbox: virtual_mailbox_abcdefg123456890
fileURL: https://postgrid.com
matchedLetter: letter_abcdef1234567890
createdAt: 2025-11-01T15:08:41.052Z
updatedAt: 2025-11-01T15:08:41.052Z
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Virtual Mailboxes
post:
operationId: VirtualMailboxes_createTestItem
summary: Create Test Virtual Mailbox Item
description: |-
Create a test item for a virtual mailbox. This is only available in test
mode, an error will be returned if you attempt this call in live mode.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"201":
description: The request has succeeded and a new resource has been created as a
result.
content:
application/json:
schema:
$ref: "#/components/schemas/VirtualMailboxItem"
example:
id: virtual_mailbox_item_abcdefg123456890
object: virtual_mailbox_item
live: false
virtualMailbox: virtual_mailbox_abcdefg123456890
fileURL: https://postgrid.com
matchedLetter: letter_abcdef1234567890
createdAt: 2025-11-01T15:08:41.052Z
updatedAt: 2025-11-01T15:08:41.052Z
"400":
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- invalid_matched_order_id_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- virtual_mailbox_not_assigned_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- cannot_create_virtual_mailbox_item_in_live_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Virtual Mailboxes
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/VirtualMailboxItemTestCreate"
example:
matchedLetter: letter_abcdef1234567890
/print-mail/v1/virtual_mailboxes/{id}/items/{itemID}:
get:
operationId: VirtualMailboxes_retrieveItem
summary: Retrieve Virtual Mailbox Item
description: Retrieves a single item for a virtual mailbox.
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: itemID
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/VirtualMailboxItem"
example:
id: virtual_mailbox_item_abcdefg123456890
object: virtual_mailbox_item
live: true
virtualMailbox: virtual_mailbox_abcdefg123456890
fileURL: https://postgrid.com
matchedLetter: letter_abcdef1234567890
createdAt: 2025-11-01T15:08:41.052Z
updatedAt: 2025-11-01T15:08:41.052Z
"401":
description: Access is unauthorized.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The server cannot find the requested resource.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: Client error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: Server error
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Virtual Mailboxes
/print-mail/v1/webhooks:
post:
operationId: Webhooks_create
summary: Create Webhook
description: Create a Webhook.
parameters: []
responses:
"201":
description: The newly created Webhook.
content:
application/json:
schema:
$ref: "#/components/schemas/Webhook"
example:
id: webhook_skN2ZTvFwS62oc5tJY1gzw
object: webhook
live: false
description: Letter Created
url: https://example.com/postgrid-webhook
enabledEvents:
- letter.created
payloadFormat: jwt
enabled: true
secret: webhook_secret_xkNXtQ4jHevFdkTG3mSf1Q
createdAt: 2022-02-16T18:37:02.048Z
updatedAt: 2022-02-16T18:37:02.048Z
"400":
description: The newly created Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The newly created Webhook.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The newly created Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The newly created Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The newly created Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The newly created Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookCreate"
example:
description: Letter Created
url: https://example.com/postgrid-webhook
enabledEvents:
- letter.created
description: The details of the Webhook to create.
get:
operationId: Webhooks_list
summary: List Webhooks
description: Retrieve a paginated list of Webhooks.
parameters:
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing Webhooks.
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: webhook_skN2ZTvFwS62oc5tJY1gzw
object: webhook
live: false
description: Letter Created
url: https://example.com/postgrid-webhook
enabledEvents:
- letter.created
payloadFormat: jwt
enabled: true
secret: webhook_secret_xkNXtQ4jHevFdkTG3mSf1Q
createdAt: 2022-02-16T18:37:02.048Z
updatedAt: 2022-02-16T18:37:02.048Z
"400":
description: A list object containing Webhooks.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing Webhooks.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing Webhooks.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing Webhooks.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Webhooks
/print-mail/v1/webhooks/{id}:
post:
operationId: Webhooks_update
summary: Update Webhook
description: Update a Webhook by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the Webhook to update.
schema:
type: string
responses:
"200":
description: The updated Webhook.
content:
application/json:
schema:
$ref: "#/components/schemas/Webhook"
example:
id: webhook_skN2ZTvFwS62oc5tJY1gzw
object: webhook
live: false
description: Letter creates and updates
url: https://example.com/postgrid-webhook
enabledEvents:
- letter.created
- letter.updated
payloadFormat: jwt
enabled: true
secret: webhook_secret_xkNXtQ4jHevFdkTG3mSf1Q
createdAt: 2022-02-16T18:37:02.048Z
updatedAt: 2022-02-16T18:37:14.021Z
"400":
description: The updated Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: The updated Webhook.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The updated Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The updated Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The updated Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The updated Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookUpdate"
example:
description: Letter creates and updates
url: https://example.com/postgrid-webhook
enabledEvents:
- letter.created
- letter.updated
enabled: true
description: The fields to update on the Webhook.
get:
operationId: Webhooks_get
summary: Get Webhook
description: Retrieve a Webhook by ID.
parameters:
- name: id
in: path
required: true
description: The ID of the Webhook to retrieve.
schema:
type: string
responses:
"200":
description: The requested Webhook.
content:
application/json:
schema:
$ref: "#/components/schemas/Webhook"
example:
id: webhook_skN2ZTvFwS62oc5tJY1gzw
object: webhook
live: false
description: Letter Created
url: https://example.com/postgrid-webhook
enabledEvents:
- letter.created
payloadFormat: jwt
enabled: true
secret: webhook_secret_xkNXtQ4jHevFdkTG3mSf1Q
createdAt: 2022-02-16T18:37:02.048Z
updatedAt: 2022-02-16T18:37:02.048Z
"401":
description: The requested Webhook.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: The requested Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: The requested Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: The requested Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: The requested Webhook.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Webhooks
delete:
operationId: Webhooks_delete
summary: Delete Webhook
description: Delete a Webhook by ID. Note that this operation cannot be undone.
parameters:
- name: id
in: path
required: true
description: The ID of the Webhook to delete.
schema:
type: string
responses:
"200":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- id
- deleted
properties:
object:
type: string
enum:
- webhook
description: Always `webhook`.
readOnly: true
id:
type: string
pattern: webhook_[a-zA-Z0-9]+
description: A unique ID prefixed with webhook_
readOnly: true
deleted:
type: boolean
enum:
- true
example:
id: webhook_skN2ZTvFwS62oc5tJY1gzw
object: webhook
deleted: true
"401":
description: A deletion confirmation.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"404":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- not_found_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"422":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A deletion confirmation.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Webhooks
/print-mail/v1/webhooks/{id}/invocations:
get:
operationId: Webhooks_listInvocations
summary: List Webhook Invocations
description: Retrieve a paginated list of invocations for a Webhook.
parameters:
- name: id
in: path
required: true
description: The ID of the Webhook whose invocations should be listed.
schema:
type: string
- $ref: "#/components/parameters/ListParams.skip"
- $ref: "#/components/parameters/ListParams.limit"
- $ref: "#/components/parameters/ListParams.search"
responses:
"200":
description: A list object containing Webhook Invocations.
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookInvocationList"
example:
object: list
limit: 10
skip: 0
totalCount: 1
data:
- id: webhook_invocation_6TAGtJezjUyGFnznTRdX37
object: webhook_invocation
webhook: webhook_skN2ZTvFwS62oc5tJY1gzw
event: event_r1nfP4xAacyqMYtt7PeyFD
orderID: letter_rqfnwvzq5TUsYR2r6L9V8X
type: letter.created
statusCode: 200
createdAt: 2021-04-02T02:09:32.066Z
updatedAt: 2021-04-02T02:09:32.066Z
"400":
description: A list object containing Webhook Invocations.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- validation_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"401":
description: A list object containing Webhook Invocations.
content:
application/json:
schema:
anyOf:
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- permission_missing_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
- type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- missing_auth_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"429":
description: A list object containing Webhook Invocations.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- rate_limit_exceeded_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
"500":
description: A list object containing Webhook Invocations.
content:
application/json:
schema:
type: object
required:
- object
- error
properties:
object:
type: string
enum:
- error
description: Always "error".
error:
type: object
properties:
type:
type: string
enum:
- internal_server_error
description: A stable machine-friendly identifier for the error.
message:
type: string
description: A human readable message describing the error.
required:
- type
- message
description: The error object which has information on the error encountered.
tags:
- Webhooks
security:
- PrintMailApiKeyAuth: []
components:
parameters:
ListParams.limit:
name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 10
explode: false
ListParams.search:
name: search
in: query
required: false
description: 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.
schema:
anyOf:
- type: string
- $ref: "#/components/schemas/StructuredSearchQuery"
explode: false
ListParams.skip:
name: skip
in: query
required: false
schema:
type: integer
format: int32
default: 0
explode: false
schemas:
APIKey:
type: object
required:
- value
properties:
value:
type: string
description: The value of the API key.
activeUntil:
type: string
format: date-time
description: >-
An optional date which the API key is active until. After this date,
the
API key will no longer be valid.
description: An API key.
AdHocReportSampleCreate:
type: object
required:
- sqlQuery
properties:
sqlQuery:
type: string
description: The SQL query to execute for the sample.
allOf:
- $ref: "#/components/schemas/ReportSampleCreateBase"
description: Model for creating an ad-hoc SQL query.
AddressPlacement:
type: string
enum:
- top_first_page
- insert_blank_page
description: Enum representing the placement of the address on the letter.
AttachedPDF:
type: object
required:
- file
- placement
properties:
file:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: The file (multipart form upload) or URL pointing to a PDF for the
attached PDF.
placement:
allOf:
- $ref: "#/components/schemas/AttachedPDFPlacement"
description: The placement of the attached PDF.
description: Model representing an attached PDF.
AttachedPDFPlacement:
type: string
enum:
- before_template
- after_template
description: Enum representing the placement of the attached PDF.
BankAccount:
type: object
required:
- object
- bankName
- bankCountryCode
- accountNumber
- id
- live
- createdAt
- updatedAt
properties:
object:
type: string
enum:
- bank_account
description: Always `bank_account`.
bankName:
type: string
description: The name of the bank.
bankPrimaryLine:
type: string
description: The primary address line of the bank.
bankSecondaryLine:
type: string
description: The secondary address line of the bank.
bankCountryCode:
allOf:
- $ref: "#/components/schemas/BankAccountCountryCode"
description: The country code of the bank.
accountNumber:
type: string
description: The account number of the bank account.
routingNumber:
type: string
description: The routing number of the bank account (for US).
transitNumber:
type: string
description: The transit number of the bank account (for CA).
routeNumber:
type: string
description: The route number of the bank account (for CA).
caDesignationNumber:
type: string
description: The designation number of the bank account (for CA).
id:
type: string
pattern: bank_account_[a-zA-Z0-9]+
description: A unique ID prefixed with bank_account_
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
signatureText:
type: string
description: The signature text PostGrid uses to generate a signature for
cheques created using this bank account. This is omitted if
`signatureImage` is present.
signatureImage:
type: string
format: uri
description: A signed link to the signature image uploaded when this bank
account was created. This is omitted if `signatureText` is present.
BankAccountBase:
type: object
required:
- object
- bankName
- bankCountryCode
- accountNumber
properties:
object:
type: string
enum:
- bank_account
description: Always `bank_account`.
readOnly: true
bankName:
type: string
description: The name of the bank.
bankPrimaryLine:
type: string
description: The primary address line of the bank.
bankSecondaryLine:
type: string
description: The secondary address line of the bank.
bankCountryCode:
allOf:
- $ref: "#/components/schemas/BankAccountCountryCode"
description: The country code of the bank.
accountNumber:
type: string
description: The account number of the bank account.
routingNumber:
type: string
description: The routing number of the bank account (for US).
transitNumber:
type: string
description: The transit number of the bank account (for CA).
routeNumber:
type: string
description: The route number of the bank account (for CA).
caDesignationNumber:
type: string
description: The designation number of the bank account (for CA).
allOf:
- type: object
required:
- id
- live
- createdAt
- updatedAt
properties:
id:
type: string
pattern: bank_account_[a-zA-Z0-9]+
description: A unique ID prefixed with bank_account_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
BankAccountCAFields:
type: object
properties:
transitNumber:
type: string
description: The transit number of the bank account (for CA).
routeNumber:
type: string
description: The route number of the bank account (for CA).
caDesignationNumber:
type: string
description: The designation number of the bank account (for CA).
BankAccountCountryCode:
type: string
enum:
- CA
- US
description: >-
Countries typically have different bank account formats and standards.
These are the countries
which PostGrid's bank accounts API supports.
BankAccountCreate:
anyOf:
- $ref: "#/components/schemas/BankAccountCreateSignatureText"
- $ref: "#/components/schemas/BankAccountCreateSignatureImageURL"
- $ref: "#/components/schemas/BankAccountCreateSignatureImageFile"
BankAccountCreateSignatureImageFile:
type: object
required:
- bankName
- bankCountryCode
- accountNumber
- signatureImage
properties:
bankName:
type: string
description: The name of the bank.
bankPrimaryLine:
type: string
description: The primary address line of the bank.
bankSecondaryLine:
type: string
description: The secondary address line of the bank.
bankCountryCode:
allOf:
- $ref: "#/components/schemas/BankAccountCountryCode"
description: The country code of the bank.
accountNumber:
type: string
description: The account number of the bank account.
routingNumber:
type: string
description: The routing number of the bank account (for US).
transitNumber:
type: string
description: The transit number of the bank account (for CA).
routeNumber:
type: string
description: The route number of the bank account (for CA).
caDesignationNumber:
type: string
description: The designation number of the bank account (for CA).
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
signatureImage:
type: string
format: byte
description: A PNG or JPEG file which PostGrid will apply to checks created with
this bank account.
BankAccountCreateSignatureImageURL:
type: object
required:
- bankName
- bankCountryCode
- accountNumber
- signatureImage
properties:
bankName:
type: string
description: The name of the bank.
bankPrimaryLine:
type: string
description: The primary address line of the bank.
bankSecondaryLine:
type: string
description: The secondary address line of the bank.
bankCountryCode:
allOf:
- $ref: "#/components/schemas/BankAccountCountryCode"
description: The country code of the bank.
accountNumber:
type: string
description: The account number of the bank account.
routingNumber:
type: string
description: The routing number of the bank account (for US).
transitNumber:
type: string
description: The transit number of the bank account (for CA).
routeNumber:
type: string
description: The route number of the bank account (for CA).
caDesignationNumber:
type: string
description: The designation number of the bank account (for CA).
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
signatureImage:
type: string
format: uri
description: Link to signature image which PostGrid will download and apply to
cheques created with this bank account.
BankAccountCreateSignatureText:
type: object
required:
- bankName
- bankCountryCode
- accountNumber
- signatureText
properties:
bankName:
type: string
description: The name of the bank.
bankPrimaryLine:
type: string
description: The primary address line of the bank.
bankSecondaryLine:
type: string
description: The secondary address line of the bank.
bankCountryCode:
allOf:
- $ref: "#/components/schemas/BankAccountCountryCode"
description: The country code of the bank.
accountNumber:
type: string
description: The account number of the bank account.
routingNumber:
type: string
description: The routing number of the bank account (for US).
transitNumber:
type: string
description: The transit number of the bank account (for CA).
routeNumber:
type: string
description: The route number of the bank account (for CA).
caDesignationNumber:
type: string
description: The designation number of the bank account (for CA).
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
signatureText:
type: string
description: The signature text of the bank account.
BankAccountList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/BankAccount"
BankAccountUSFields:
type: object
properties:
routingNumber:
type: string
description: The routing number of the bank account (for US).
BaseUser:
type: object
required:
- id
- organization
- pendingInvite
- email
- name
- verifiedEmail
- roles
properties:
id:
type: string
description: A unique ID prefixed with `user_`.
organization:
type: string
description: A unique ID prefixed with `user_`.
pendingInvite:
type: boolean
description: Indicates if the user has a pending invite.
email:
type: string
description: The email of the user.
name:
type: string
description: The name of the user.
phoneNumber:
type: string
description: The phone number of the user.
lastLoginTime:
type: string
format: date-time
description: The date and time at which the user last logged in.
verifiedEmail:
type: boolean
description: Indicates if the user has a verified email or not.
roles:
type: array
items:
type: string
description: >-
The roles given to the user. Roles can be used to restrict access
for
users.
previousEmails:
type: array
items:
type: string
description: >-
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.
emailPreferences:
allOf:
- $ref: "#/components/schemas/EmailPreferences"
description: A set of preferences for receiving emails.
BinaryFile:
type: string
format: binary
description: |-
Represents a raw file upload. Sending the actual file requires a
`multipart/form-data` request; in `application/json` request bodies,
supply a URL instead.
Box:
type: object
required:
- status
- id
- live
- createdAt
- updatedAt
- sendDate
- mailingClass
- to
- object
- from
- cheques
properties:
status:
allOf:
- $ref: "#/components/schemas/OrderStatus"
description: See `OrderStatus` for more details on the status of this order.
mergeVariables:
type: object
additionalProperties: {}
description: 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.
trackingNumber:
type: string
description: The tracking number of this order. Populated after an
express/certified order has been processed for delivery.
imbStatus:
allOf:
- $ref: "#/components/schemas/OrderIMBStatus"
description: 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.
imbZIPCode:
type: string
description: The most recent ZIP code of the USPS facility that the order has
been processed through. Only populated when an `imbStatus` is
present.
imbDate:
type: string
format: date-time
description: The last date that the IMB status was updated. See `imbStatus` for
more details.
cancellation:
allOf:
- $ref: "#/components/schemas/Cancellation"
description: The cancellation details of this order. Populated if the order has
been cancelled.
url:
type: string
format: uri
description: >-
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.
id:
type: string
pattern: box_[a-zA-Z0-9]+
description: A unique ID prefixed with box_
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. This determines the speed and cost
of delivery. See `OrderMailingClass` for more details.
to:
allOf:
- $ref: "#/components/schemas/Contact"
description: The recipient of this order. This will be provided even if you
delete the underlying contact.
object:
type: string
enum:
- box
description: Always "box".
from:
allOf:
- $ref: "#/components/schemas/Contact"
description: The contact of the 'from' field in read mode should be a fully
expanded Contact.
cheques:
type: array
items:
$ref: "#/components/schemas/BoxCheque"
description: The cheques inside this box (in read mode).
BoxBase:
type: object
required:
- object
properties:
object:
type: string
enum:
- box
description: Always "box".
readOnly: true
description: Base fields presents when reading a Box.
BoxCheque:
type: object
required:
- from
- to
properties:
from:
$ref: "#/components/schemas/Contact"
to:
$ref: "#/components/schemas/Contact"
allOf:
- $ref: "#/components/schemas/BoxChequeBase"
description: >-
Model representing a single cheque in "read" mode.
- The "from" and "to" should be fully expanded Contact objects once
created.
BoxChequeBase:
type: object
required:
- bankAccount
- amount
- number
properties:
bankAccount:
type: string
description: The bank account (ID or reference) from which the cheque amount is
drawn.
amount:
type: integer
format: int32
description: The amount on the cheque.
memo:
type: string
description: The memo text on the cheque (optional).
logoURL:
type: string
format: uri
description: A URL to a logo for the cheque (optional).
messageTemplate:
type: string
description: An optional message template to be printed on or with the cheque.
number:
type: integer
format: int32
description: The cheque number.
mergeVariables:
type: object
additionalProperties: {}
description: A set of dynamic merge variables for customizing the cheque or
accompanying documents (optional).
description: Base fields that both reading and creating a cheque might share.
BoxChequeCreate:
type: object
required:
- from
- to
properties:
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
allOf:
- $ref: "#/components/schemas/BoxChequeBase"
description: >-
Model representing a single cheque in "create" mode.
- The "from" and "to" can be ContactCreate objects (inline) or string
contactIDs.
BoxCreate:
type: object
required:
- to
- from
- cheques
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The 'from' (sender) of the entire box. Accepts inline ContactCreate
or a contactID.
cheques:
type: array
items:
$ref: "#/components/schemas/BoxChequeCreate"
maxItems: 100
description: The cheques to be mailed in the box. Only 100 cheques can be
included in a box at a time.
BoxList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Box"
description: A list of Boxes.
Campaign:
type: object
required:
- id
- live
- createdAt
- updatedAt
- status
- mailingList
- createdCount
properties:
id:
type: string
pattern: campaign_[a-zA-Z0-9]+
description: A unique ID prefixed with campaign_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
status:
allOf:
- $ref: "#/components/schemas/CampaignStatus"
description: The current status of the campaign in its lifecycle.
readOnly: true
defaultSenderContact:
type: string
description: The ID of the default sender contact to use for orders if not
specified per recipient.
mailingList:
type: string
description: The ID of the mailing list associated with this campaign.
createdCount:
type: integer
format: int32
description: The number of orders successfully created for this campaign.
readOnly: true
letter:
allOf:
- $ref: "#/components/schemas/CampaignLetterFields"
description: Inline letter configuration for this campaign. Only one collateral
type can be set.
postcard:
allOf:
- $ref: "#/components/schemas/CampaignPostcardFields"
description: Inline postcard configuration for this campaign. Only one
collateral type can be set.
cheque:
allOf:
- $ref: "#/components/schemas/CampaignChequeFields"
description: Inline cheque configuration for this campaign. Only one collateral
type can be set.
selfMailer:
allOf:
- $ref: "#/components/schemas/CampaignSelfMailerFields"
description: Inline self-mailer configuration for this campaign. Only one
collateral type can be set.
snapPack:
allOf:
- $ref: "#/components/schemas/CampaignSnapPackFields"
description: Inline snap pack configuration for this campaign. Only one
collateral type can be set.
orderPreviewURL:
type: string
format: uri
description: A temporary URL to preview the first rendered order, available once
the campaign status is 'draft' or later.
readOnly: true
sendDate:
type: string
format: date-time
description: The scheduled date and time for the campaign to be sent.
errors:
type: array
items:
$ref: "#/components/schemas/CampaignError"
description: A list of processing errors encountered, if any. Present when
status is 'changes_required'.
readOnly: true
reportURL:
type: string
format: uri
description: A temporary URL to download the processing report, available once
the campaign is in the `ready` status.
readOnly: true
description: Represents a bulk mail campaign.
CampaignChequeFields:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/ChequeSize"
description: The size of the cheque.
bankAccount:
type: string
description: ID of the bank account to use for the cheque.
currencyCode:
allOf:
- $ref: "#/components/schemas/CurrencyCode"
description: Currency code for the cheque.
memo:
type: string
description: Memo line text for the cheque.
message:
type: string
description: Message included on the cheque stub.
logo:
type: string
format: uri
description: A publicly accessible URL for the logo to print on the cheque.
letterTemplate:
type: string
description: ID of a template for an optional attached letter. Cannot be used
with `letterPDF`.
letterUploadedPDF:
type: string
format: uri
description: A signed URL to the attached letter PDF, if any.
readOnly: true
envelope:
type: string
description: The custom envelope ID or `"standard"`.
returnEnvelope:
type: string
description: ID of a return envelope to include.
letterSettings:
type: object
properties:
color:
type: boolean
description: Whether to print the attached letter in color.
description: Settings for the attached letter (e.g., color printing).
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the cheque.
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the cheque.
description: Inline cheque configuration for a campaign. All fields are optional
since campaigns may be in a partial state during drafting.
CampaignChequeFieldsCreate:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/ChequeSize"
description: The size of the cheque.
bankAccount:
type: string
description: ID of the bank account to use for the cheque.
currencyCode:
allOf:
- $ref: "#/components/schemas/CurrencyCode"
description: Currency code for the cheque.
memo:
type: string
description: Memo line text for the cheque.
message:
type: string
description: Message included on the cheque stub.
logo:
type: string
format: uri
description: A publicly accessible URL for the logo to print on the cheque.
letterTemplate:
type: string
description: ID of a template for an optional attached letter. Cannot be used
with `letterPDF`.
letterPDF:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: PDF file for an optional attached letter. Cannot be used with
`letterTemplate`.
envelope:
type: string
description: The custom envelope ID or `"standard"`.
returnEnvelope:
type: string
description: ID of a return envelope to include.
letterSettings:
type: object
properties:
color:
type: boolean
description: Whether to print the attached letter in color.
description: Settings for the attached letter (e.g., color printing).
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the cheque.
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the cheque.
description: Inline cheque configuration for a campaign. All fields are optional
since campaigns may be in a partial state during drafting.
CampaignCreate:
type: object
required:
- mailingList
properties:
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
defaultSenderContact:
type: string
description: The ID of the default sender contact to use for orders if not
specified per recipient.
mailingList:
type: string
description: The ID of the mailing list associated with this campaign.
letter:
allOf:
- $ref: "#/components/schemas/CampaignLetterFieldsCreate"
description: Inline letter configuration for this campaign. Only one collateral
type can be set.
postcard:
allOf:
- $ref: "#/components/schemas/CampaignPostcardFieldsCreate"
description: Inline postcard configuration for this campaign. Only one
collateral type can be set.
cheque:
allOf:
- $ref: "#/components/schemas/CampaignChequeFieldsCreate"
description: Inline cheque configuration for this campaign. Only one collateral
type can be set.
selfMailer:
allOf:
- $ref: "#/components/schemas/CampaignSelfMailerFieldsCreate"
description: Inline self-mailer configuration for this campaign. Only one
collateral type can be set.
snapPack:
allOf:
- $ref: "#/components/schemas/CampaignSnapPackFieldsCreate"
description: Inline snap pack configuration for this campaign. Only one
collateral type can be set.
sendDate:
type: string
format: date-time
description: The scheduled date and time for the campaign to be sent.
description: Parameters for creating a new campaign.
CampaignCreateMultiPart:
type: object
required:
- mailingList
properties:
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
defaultSenderContact:
type: string
description: The ID of the default sender contact to use for orders if not
specified per recipient.
mailingList:
type: string
description: The ID of the mailing list associated with this campaign.
letter:
allOf:
- $ref: "#/components/schemas/CampaignLetterFieldsCreate"
description: Inline letter configuration for this campaign. Only one collateral
type can be set.
postcard:
allOf:
- $ref: "#/components/schemas/CampaignPostcardFieldsCreate"
description: Inline postcard configuration for this campaign. Only one
collateral type can be set.
cheque:
allOf:
- $ref: "#/components/schemas/CampaignChequeFieldsCreate"
description: Inline cheque configuration for this campaign. Only one collateral
type can be set.
selfMailer:
allOf:
- $ref: "#/components/schemas/CampaignSelfMailerFieldsCreate"
description: Inline self-mailer configuration for this campaign. Only one
collateral type can be set.
snapPack:
allOf:
- $ref: "#/components/schemas/CampaignSnapPackFieldsCreate"
description: Inline snap pack configuration for this campaign. Only one
collateral type can be set.
sendDate:
type: string
format: date-time
description: The scheduled date and time for the campaign to be sent.
description: Parameters for creating a new campaign.
CampaignError:
type: object
required:
- type
- message
properties:
type:
allOf:
- $ref: "#/components/schemas/CampaignErrorType"
description: The type categorizing the error.
message:
type: string
description: A human-readable message describing the error.
description: Details of a specific error encountered during campaign processing.
CampaignErrorType:
type: string
enum:
- processing_error
- internal_error
description: Type of error encountered during campaign processing.
CampaignLetterFields:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/LetterSize"
description: The size of the letter.
color:
type: boolean
description: Whether to print in color.
doubleSided:
type: boolean
description: Whether to print on both sides of the paper.
envelope:
type: string
description: The custom envelope ID or `"standard"`.
envelopeType:
allOf:
- $ref: "#/components/schemas/LetterEnvelopeType"
description: The type of envelope for the letter.
perforatedPage:
type: number
enum:
- 1
description: Which page number should be perforated (if any).
addressPlacement:
allOf:
- $ref: "#/components/schemas/AddressPlacement"
description: How the delivery address is placed on the letter.
returnEnvelope:
type: string
description: ID of a return envelope to include.
attachedPDF:
allOf:
- $ref: "#/components/schemas/AttachedPDF"
description: An attached PDF to include with the letter. Cannot be used
alongside the `pdf` field.
template:
type: string
description: ID of a template for the letter content. Cannot be used with `pdf`.
uploadedPDF:
type: string
format: uri
description: A signed URL to the uploaded PDF, if any.
readOnly: true
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the letter.
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the letter.
paper:
allOf:
- $ref: "#/components/schemas/LetterPremiumPaperID"
description: Premium paper selection ("standard" or a premium paper ID). If
omitted, org default is used when configured; otherwise "standard".
description: Inline letter configuration for a campaign. All fields are optional
since campaigns may be in a partial state during drafting.
CampaignLetterFieldsCreate:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/LetterSize"
description: The size of the letter.
color:
type: boolean
description: Whether to print in color.
doubleSided:
type: boolean
description: Whether to print on both sides of the paper.
envelope:
type: string
description: The custom envelope ID or `"standard"`.
envelopeType:
allOf:
- $ref: "#/components/schemas/LetterEnvelopeType"
description: The type of envelope for the letter.
perforatedPage:
type: number
enum:
- 1
description: Which page number should be perforated (if any).
addressPlacement:
allOf:
- $ref: "#/components/schemas/AddressPlacement"
description: How the delivery address is placed on the letter.
returnEnvelope:
type: string
description: ID of a return envelope to include.
attachedPDF:
allOf:
- $ref: "#/components/schemas/AttachedPDF"
description: An attached PDF to include with the letter. Cannot be used
alongside the `pdf` field.
template:
type: string
description: ID of a template for the letter content. Cannot be used with `pdf`.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A PDF file or URL for the letter content. Cannot be used with
`template`.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the letter.
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the letter.
paper:
allOf:
- $ref: "#/components/schemas/LetterPremiumPaperID"
description: Premium paper selection ("standard" or a premium paper ID). If
omitted, org default is used when configured; otherwise "standard".
description: Inline letter configuration for a campaign. All fields are optional
since campaigns may be in a partial state during drafting.
CampaignList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Campaign"
description: A list of campaigns.
CampaignPostcardFields:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
frontTemplate:
type: string
description: ID of the template for the front side. Cannot be used with `pdf`.
backTemplate:
type: string
description: ID of the template for the back side. Cannot be used with `pdf`.
uploadedPDF:
type: string
format: uri
description: A signed URL to the uploaded PDF, if any.
readOnly: true
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: Premium paper selection ("standard" or a premium paper ID). If
omitted, org default is used when configured; otherwise "standard".
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the postcard.
description: Inline postcard configuration for a campaign. All fields are
optional since campaigns may be in a partial state during drafting.
CampaignPostcardFieldsCreate:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
frontTemplate:
type: string
description: ID of the template for the front side. Cannot be used with `pdf`.
backTemplate:
type: string
description: ID of the template for the back side. Cannot be used with `pdf`.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A 2-page PDF file for the postcard content (front and back). Cannot
be used with `frontTemplate`/`backTemplate`.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: Premium paper selection ("standard" or a premium paper ID). If
omitted, org default is used when configured; otherwise "standard".
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the postcard.
description: Inline postcard configuration for a campaign. All fields are
optional since campaigns may be in a partial state during drafting.
CampaignSelfMailerFields:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
insideTemplate:
type: string
description: ID of the template for the inside. Cannot be used with `pdf`.
outsideTemplate:
type: string
description: ID of the template for the outside. Cannot be used with `pdf`.
uploadedPDF:
type: string
format: uri
description: A signed URL to the uploaded PDF, if any.
readOnly: true
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the self-mailer.
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the self-mailer.
description: Inline self-mailer configuration for a campaign. All fields are
optional since campaigns may be in a partial state during drafting.
CampaignSelfMailerFieldsCreate:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
insideTemplate:
type: string
description: ID of the template for the inside. Cannot be used with `pdf`.
outsideTemplate:
type: string
description: ID of the template for the outside. Cannot be used with `pdf`.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A 2-page PDF file for the self-mailer content. Cannot be used with
`insideTemplate`/`outsideTemplate`.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the self-mailer.
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the self-mailer.
description: Inline self-mailer configuration for a campaign. All fields are
optional since campaigns may be in a partial state during drafting.
CampaignSend:
type: object
properties:
sendDate:
anyOf:
- type: string
format: date-time
- type: string
description: The date and time the campaign should be sent. Must be in the
future. If omitted, defaults to the earliest possible processing
date.
description: Parameters for sending a campaign. Only campaigns in 'draft' status
can be sent.
CampaignSnapPackFields:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/SnapPackSize"
description: The size of the snap pack.
insideTemplate:
type: string
description: ID of the template for the inside. Cannot be used with `pdf`.
outsideTemplate:
type: string
description: ID of the template for the outside. Cannot be used with `pdf`.
uploadedPDF:
type: string
format: uri
description: A signed URL to the uploaded PDF, if any.
readOnly: true
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the snap pack.
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the snap pack.
description: Inline snap pack configuration for a campaign. All fields are
optional since campaigns may be in a partial state during drafting.
CampaignSnapPackFieldsCreate:
type: object
properties:
size:
allOf:
- $ref: "#/components/schemas/SnapPackSize"
description: The size of the snap pack.
insideTemplate:
type: string
description: ID of the template for the inside. Cannot be used with `pdf`.
outsideTemplate:
type: string
description: ID of the template for the outside. Cannot be used with `pdf`.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A 2-page PDF file for the snap pack content. Cannot be used with
`insideTemplate`/`outsideTemplate`.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: Mailing class for the snap pack.
description:
type: string
description: An optional description.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata.
mergeVariables:
type: object
additionalProperties: {}
description: Default merge variables for the snap pack.
description: Inline snap pack configuration for a campaign. All fields are
optional since campaigns may be in a partial state during drafting.
CampaignStatus:
type: string
enum:
- drafting
- changes_required
- creating_orders
- draft
- ready
- printing
- processed_for_delivery
description: Status of the campaign lifecycle.
CampaignUpdate:
type: object
properties:
description:
type: string
nullable: true
description: An optional description for the campaign. Set to `null` to remove
the existing description.
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: Optional key-value data associated with the campaign. Set to `null`
to remove existing metadata.
mailingList:
type: string
description: The ID of the mailing list to associate with this campaign.
letter:
type: object
allOf:
- $ref: "#/components/schemas/CampaignLetterFieldsCreate"
nullable: true
description: Inline letter configuration. Setting this will remove other
collateral types. Set to `null` to remove.
postcard:
type: object
allOf:
- $ref: "#/components/schemas/CampaignPostcardFieldsCreate"
nullable: true
description: Inline postcard configuration. Setting this will remove other
collateral types. Set to `null` to remove.
cheque:
type: object
allOf:
- $ref: "#/components/schemas/CampaignChequeFieldsCreate"
nullable: true
description: Inline cheque configuration. Setting this will remove other
collateral types. Set to `null` to remove.
selfMailer:
type: object
allOf:
- $ref: "#/components/schemas/CampaignSelfMailerFieldsCreate"
nullable: true
description: Inline self-mailer configuration. Setting this will remove other
collateral types. Set to `null` to remove.
snapPack:
type: object
allOf:
- $ref: "#/components/schemas/CampaignSnapPackFieldsCreate"
nullable: true
description: Inline snap pack configuration. Setting this will remove other
collateral types. Set to `null` to remove.
defaultSenderContact:
type: string
nullable: true
description: The ID of the default sender contact. Set to `null` to remove.
description: Parameters for updating an existing campaign. Only campaigns in
'draft' or 'changes_required' status can be updated.
CancelReason:
type: string
enum:
- user_initiated
- invalid_content
- invalid_order_mailing_class
Cancellation:
type: object
required:
- reason
properties:
reason:
allOf:
- $ref: "#/components/schemas/CancelReason"
description: The reason for the cancellation.
readOnly: true
cancelledByUser:
type: string
description: The user ID who cancelled the order.
readOnly: true
note:
type: string
description: An optional note provided by the user who cancelled the order.
readOnly: true
Cheque:
type: object
required:
- status
- id
- live
- createdAt
- updatedAt
- sendDate
- mailingClass
- to
- object
- bankAccount
- amount
- from
- size
- currencyCode
properties:
status:
allOf:
- $ref: "#/components/schemas/OrderStatus"
description: See `OrderStatus` for more details on the status of this order.
mergeVariables:
type: object
additionalProperties: {}
description: 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.
trackingNumber:
type: string
description: The tracking number of this order. Populated after an
express/certified order has been processed for delivery.
imbStatus:
allOf:
- $ref: "#/components/schemas/OrderIMBStatus"
description: 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.
imbZIPCode:
type: string
description: The most recent ZIP code of the USPS facility that the order has
been processed through. Only populated when an `imbStatus` is
present.
imbDate:
type: string
format: date-time
description: The last date that the IMB status was updated. See `imbStatus` for
more details.
cancellation:
allOf:
- $ref: "#/components/schemas/Cancellation"
description: The cancellation details of this order. Populated if the order has
been cancelled.
url:
type: string
format: uri
description: >-
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.
id:
type: string
pattern: cheque_[a-zA-Z0-9]+
description: A unique ID prefixed with cheque_
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. This determines the speed and cost
of delivery. See `OrderMailingClass` for more details.
to:
allOf:
- $ref: "#/components/schemas/Contact"
description: The recipient of this order. This will be provided even if you
delete the underlying contact.
object:
type: string
enum:
- cheque
description: Always `cheque`.
bankAccount:
type: string
description: The bank account (ID) associated with the cheque.
amount:
type: integer
format: int32
description: The amount of the cheque in cents.
memo:
type: string
description: The memo of the cheque.
message:
type: string
description: The message of the cheque.
logo:
type: string
format: uri
description: 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).
letterHTML:
type: string
description: The raw HTML content for a letter attached to the cheque, if any.
You can supply _either_ this, `letterTemplate`, or `letterPDF`, but
not more than one.
letterTemplate:
type: string
description: A Template ID for the letter attached to the cheque, if any.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the cheque, if any. Note
that you must first order return envelopes using the Return
Envelopes API.
number:
type: integer
format: int32
description: 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.
envelope:
anyOf:
- type: string
enum:
- standard
- type: string
description: The envelope of the cheque. If a custom envelope ID is not
specified, defaults to `standard`.
digitalOnly:
allOf:
- $ref: "#/components/schemas/DigitalOnly"
description: The digitalOnly object contains data for digital-only cheques. A
watermark must be provided.
from:
allOf:
- $ref: "#/components/schemas/Contact"
description: The contact information of the sender.
size:
allOf:
- $ref: "#/components/schemas/ChequeSize"
description: The size of the cheque.
currencyCode:
anyOf:
- type: string
enum:
- USD
- type: string
enum:
- CAD
description: 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.
depositReadyPDFURL:
type: string
format: uri
description: A link to the deposit-ready PDF for a digital-only cheque, returned
if requested and available.
letterUploadedPDF:
type: string
format: uri
description: A signed URL pointing to the original PDF of the letter attached to
the cheque, if any.
ChequeAttachedLetterSettings:
type: object
properties:
placement:
allOf:
- $ref: "#/components/schemas/LetterPlacement"
description: Where the attached letter is placed relative to the cheque page.
description: Settings for a letter attached to a cheque.
ChequeBase:
type: object
required:
- object
- bankAccount
- amount
properties:
object:
type: string
enum:
- cheque
description: Always `cheque`.
readOnly: true
bankAccount:
type: string
description: The bank account (ID) associated with the cheque.
amount:
type: integer
format: int32
description: The amount of the cheque in cents.
memo:
type: string
description: The memo of the cheque.
message:
type: string
description: The message of the cheque.
logo:
type: string
format: uri
description: 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).
letterHTML:
type: string
description: The raw HTML content for a letter attached to the cheque, if any.
You can supply _either_ this, `letterTemplate`, or `letterPDF`, but
not more than one.
letterTemplate:
type: string
description: A Template ID for the letter attached to the cheque, if any.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the cheque, if any. Note
that you must first order return envelopes using the Return
Envelopes API.
number:
type: integer
format: int32
description: 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.
envelope:
anyOf:
- type: string
enum:
- standard
- type: string
description: The envelope of the cheque. If a custom envelope ID is not
specified, defaults to `standard`.
digitalOnly:
allOf:
- $ref: "#/components/schemas/DigitalOnly"
description: The digitalOnly object contains data for digital-only cheques. A
watermark must be provided.
description: >-
Represents a cheque resource, which may be physically mailed or
digital-only.
If digitalOnly is present, the cheque is treated as an eCheck and will
have its status set to cancelled.
depositReadyPDFURL is included if the cheque is digital and you request
the deposit-ready PDF route.
ChequeCreate:
type: object
required:
- to
- bankAccount
- amount
- from
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
bankAccount:
type: string
description: The bank account (ID) associated with the cheque.
amount:
type: integer
format: int32
description: The amount of the cheque in cents.
memo:
type: string
description: The memo of the cheque.
message:
type: string
description: The message of the cheque.
logo:
type: string
format: uri
description: 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).
letterHTML:
type: string
description: The raw HTML content for a letter attached to the cheque, if any.
You can supply _either_ this, `letterTemplate`, or `letterPDF`, but
not more than one.
letterTemplate:
type: string
description: A Template ID for the letter attached to the cheque, if any.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the cheque, if any. Note
that you must first order return envelopes using the Return
Envelopes API.
number:
type: integer
format: int32
description: 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.
envelope:
anyOf:
- type: string
enum:
- standard
- type: string
description: The envelope of the cheque. If a custom envelope ID is not
specified, defaults to `standard`.
digitalOnly:
allOf:
- $ref: "#/components/schemas/DigitalOnly"
description: The digitalOnly object contains data for digital-only cheques. A
watermark must be provided.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
redirectTo:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/ChequeSize"
description: The size of the cheque.
default: us_letter
currencyCode:
anyOf:
- type: string
enum:
- USD
- type: string
enum:
- CAD
description: 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.
letterPDF:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A URL pointing to a PDF for the letter attached to the cheque, or
the PDF file itself when uploaded via a multipart form request. You
can supply _either_ this, `letterHTML`, or `letterTemplate`, but not
more than one.
letterSettings:
allOf:
- $ref: "#/components/schemas/ChequeAttachedLetterSettings"
description: Settings for the letter attached to the cheque.
ChequeCreateMultiPart:
type: object
required:
- to
- bankAccount
- amount
- from
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
bankAccount:
type: string
description: The bank account (ID) associated with the cheque.
amount:
type: integer
format: int32
description: The amount of the cheque in cents.
memo:
type: string
description: The memo of the cheque.
message:
type: string
description: The message of the cheque.
logo:
type: string
format: uri
description: 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).
letterHTML:
type: string
description: The raw HTML content for a letter attached to the cheque, if any.
You can supply _either_ this, `letterTemplate`, or `letterPDF`, but
not more than one.
letterTemplate:
type: string
description: A Template ID for the letter attached to the cheque, if any.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the cheque, if any. Note
that you must first order return envelopes using the Return
Envelopes API.
number:
type: integer
format: int32
description: 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.
envelope:
anyOf:
- type: string
enum:
- standard
- type: string
description: The envelope of the cheque. If a custom envelope ID is not
specified, defaults to `standard`.
digitalOnly:
allOf:
- $ref: "#/components/schemas/DigitalOnly"
description: The digitalOnly object contains data for digital-only cheques. A
watermark must be provided.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
redirectTo:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/ChequeSize"
description: The size of the cheque.
default: us_letter
currencyCode:
anyOf:
- type: string
enum:
- USD
- type: string
enum:
- CAD
description: 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.
letterPDF:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A URL pointing to a PDF for the letter attached to the cheque, or
the PDF file itself when uploaded via a multipart form request. You
can supply _either_ this, `letterHTML`, or `letterTemplate`, but not
more than one.
letterSettings:
allOf:
- $ref: "#/components/schemas/ChequeAttachedLetterSettings"
description: Settings for the letter attached to the cheque.
ChequeList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Cheque"
ChequeSize:
type: string
enum:
- us_letter
- us_legal
description: Enum representing the supported cheque sizes.
Contact:
type: object
required:
- object
- addressLine1
- countryCode
- addressStatus
properties:
object:
type: string
enum:
- contact
description: Always `contact`.
readOnly: true
addressLine1:
type: string
description: The first line of the contact's address.
addressLine2:
type: string
description: Second line of the contact's address, if applicable.
city:
type: string
description: The city of the contact's address.
provinceOrState:
type: string
description: Province or state of the contact's address.
postalOrZip:
type: string
description: The postal or ZIP code of the contact's address.
countryCode:
type: string
description: The ISO 3611-1 country code of the contact's address.
addressStatus:
type: string
enum:
- verified
- corrected
- failed
description: One of `verified`, `corrected`, or `failed`.
readOnly: true
addressErrors:
type: string
description: A series of human-readable errors/warnings that were raised when
running the provided address through our address verification.
readOnly: true
companyName:
type: string
description: Company name of the contact.
firstName:
type: string
description: First name of the contact.
lastName:
type: string
description: Last name of the contact.
email:
type: string
description: Email of the contact.
phoneNumber:
type: string
description: Phone number of the contact.
jobTitle:
type: string
description: Job title of the contact.
skipVerification:
type: boolean
description: If `true`, PostGrid will skip running this contact's address
through our address verification system.
default: false
forceVerifiedStatus:
type: boolean
description: If `true`, PostGrid will force this contact to have an
`addressStatus` of `verified` even if our address verification
system says otherwise.
default: false
secret:
type: boolean
description: If `true`, the contact's details are hidden from the dashboard and
API responses apart from the final print. The contact ID can then be
used as a token for sending mail without giving access to the
underlying data.
allOf:
- type: object
required:
- id
- live
- createdAt
- updatedAt
properties:
id:
type: string
pattern: contact_[a-zA-Z0-9]+
description: A unique ID prefixed with contact_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
ContactCreate:
oneOf:
- $ref: "#/components/schemas/ContactCreateWithFirstName"
- $ref: "#/components/schemas/ContactCreateWithCompanyName"
ContactCreateWithCompanyName:
type: object
required:
- addressLine1
- countryCode
- companyName
properties:
addressLine1:
type: string
description: The first line of the contact's address.
addressLine2:
type: string
description: Second line of the contact's address, if applicable.
city:
type: string
description: The city of the contact's address.
provinceOrState:
type: string
description: Province or state of the contact's address.
postalOrZip:
type: string
description: The postal or ZIP code of the contact's address.
countryCode:
type: string
description: The ISO 3611-1 country code of the contact's address.
firstName:
type: string
description: First name of the contact.
lastName:
type: string
description: Last name of the contact.
email:
type: string
description: Email of the contact.
phoneNumber:
type: string
description: Phone number of the contact.
jobTitle:
type: string
description: Job title of the contact.
skipVerification:
type: boolean
description: If `true`, PostGrid will skip running this contact's address
through our address verification system.
default: false
forceVerifiedStatus:
type: boolean
description: If `true`, PostGrid will force this contact to have an
`addressStatus` of `verified` even if our address verification
system says otherwise.
default: false
secret:
type: boolean
description: If `true`, the contact's details are hidden from the dashboard and
API responses apart from the final print. The contact ID can then be
used as a token for sending mail without giving access to the
underlying data.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
companyName:
type: string
ContactCreateWithFirstName:
type: object
required:
- addressLine1
- countryCode
- firstName
properties:
addressLine1:
type: string
description: The first line of the contact's address.
addressLine2:
type: string
description: Second line of the contact's address, if applicable.
city:
type: string
description: The city of the contact's address.
provinceOrState:
type: string
description: Province or state of the contact's address.
postalOrZip:
type: string
description: The postal or ZIP code of the contact's address.
countryCode:
type: string
description: The ISO 3611-1 country code of the contact's address.
companyName:
type: string
description: Company name of the contact.
lastName:
type: string
description: Last name of the contact.
email:
type: string
description: Email of the contact.
phoneNumber:
type: string
description: Phone number of the contact.
jobTitle:
type: string
description: Job title of the contact.
skipVerification:
type: boolean
description: If `true`, PostGrid will skip running this contact's address
through our address verification system.
default: false
forceVerifiedStatus:
type: boolean
description: If `true`, PostGrid will force this contact to have an
`addressStatus` of `verified` even if our address verification
system says otherwise.
default: false
secret:
type: boolean
description: If `true`, the contact's details are hidden from the dashboard and
API responses apart from the final print. The contact ID can then be
used as a token for sending mail without giving access to the
underlying data.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
firstName:
type: string
ContactField:
type: string
enum:
- description
- firstName
- lastName
- email
- phoneNumber
- companyName
- addressLine1
- addressLine2
- jobTitle
- city
- postalOrZip
- provinceOrState
- countryCode
description: Contact fields that can be mapped from the import file.
CurrencyCode:
type: string
enum:
- CAD
- USD
description: Enum representing the supported currency codes.
DeletedResponse:
type: object
required:
- id
- deleted
properties:
id:
type: string
description: The ID of the deleted resource.
deleted:
type: boolean
enum:
- true
description: Indicates the resource was successfully deleted.
description: Generic response for delete operations.
DigitalOnly:
type: object
required:
- watermark
properties:
watermark:
type: string
description: Text to be displayed as a watermark on the digital cheque.
payee:
type: object
properties:
name:
type: string
description: The name of the payee.
required:
- name
description: >-
The payee of the digital cheque. Supplying `payee.name` lets you
create a
digital-only cheque without a `to` contact — when it is provided,
the
top-level `to` field may be omitted.
EmailPreferences:
type: object
properties:
orderPreviewSendPreference:
allOf:
- $ref: "#/components/schemas/OrderPreviewSendPreference"
description: |-
The preference for which the user should receive emails for order
previews.
description: A set of preferences for how a user should receive emails.
Event:
type: object
required:
- id
- object
- live
- type
- createdAt
properties:
id:
type: string
pattern: event_[a-zA-Z0-9]+
description: A unique ID prefixed with `event_`.
readOnly: true
object:
type: string
enum:
- event
description: Always `event`.
readOnly: true
live:
type: boolean
description: "`true` if this is a live mode event else `false`."
readOnly: true
type:
allOf:
- $ref: "#/components/schemas/WebhookEventType"
description: The type of this event.
readOnly: true
data:
type: object
additionalProperties: {}
description: The data of the resource associated with this event.
readOnly: true
updatedFields:
type: object
additionalProperties: {}
description: A record containing the updated fields of the resource associated
with this event.
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this event was created.
readOnly: true
EventList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Event"
FileType:
type: string
enum:
- csv
description: Type of file supported for mailing list imports.
Letter:
type: object
required:
- status
- id
- live
- createdAt
- updatedAt
- sendDate
- mailingClass
- to
- object
- from
- doubleSided
- color
- size
- addressPlacement
- envelope
properties:
status:
allOf:
- $ref: "#/components/schemas/OrderStatus"
description: See `OrderStatus` for more details on the status of this order.
mergeVariables:
type: object
additionalProperties: {}
description: 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.
trackingNumber:
type: string
description: The tracking number of this order. Populated after an
express/certified order has been processed for delivery.
imbStatus:
allOf:
- $ref: "#/components/schemas/OrderIMBStatus"
description: 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.
imbZIPCode:
type: string
description: The most recent ZIP code of the USPS facility that the order has
been processed through. Only populated when an `imbStatus` is
present.
imbDate:
type: string
format: date-time
description: The last date that the IMB status was updated. See `imbStatus` for
more details.
cancellation:
allOf:
- $ref: "#/components/schemas/Cancellation"
description: The cancellation details of this order. Populated if the order has
been cancelled.
url:
type: string
format: uri
description: >-
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.
id:
type: string
pattern: letter_[a-zA-Z0-9]+
description: A unique ID prefixed with letter_
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. This determines the speed and cost
of delivery. See `OrderMailingClass` for more details.
to:
allOf:
- $ref: "#/components/schemas/Contact"
description: The recipient of this order. This will be provided even if you
delete the underlying contact.
object:
type: string
enum:
- letter
description: Always `letter`.
perforatedPage:
type: number
enum:
- 1
description: If specified, indicates which letter page is perforated. Currently,
only the first page can be perforated.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the letter, if any.
attachedPDF:
allOf:
- $ref: "#/components/schemas/AttachedPDF"
description: You can attach a PDF to the content you supply for this letter.
This is useful if you have some stati
plasticCard:
allOf:
- $ref: "#/components/schemas/PlasticCard"
description: The plastic card sent out with the letter, if any.
pdfWorkflowRun:
type: string
description: The ID of the PDF workflow run that created the letter, if any.
paper:
allOf:
- $ref: "#/components/schemas/LetterPremiumPaperID"
description: >-
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when
configured; otherwise `standard`.
from:
allOf:
- $ref: "#/components/schemas/Contact"
description: The contact information of the sender.
doubleSided:
type: boolean
description: Indicates if the letter is double-sided.
color:
type: boolean
description: Indicates if the letter is in color.
size:
allOf:
- $ref: "#/components/schemas/LetterSize"
description: The size of the letter.
addressPlacement:
allOf:
- $ref: "#/components/schemas/AddressPlacement"
description: The placement of the address on the letter.
envelope:
type: string
description: The envelope (ID) for the letter or the default `standard` envelope.
html:
type: string
description: The HTML content for the letter. You can supply _either_ this or
`template` but not both.
template:
type: string
description: The template ID used for the letter. You can supply _either_ this
or `html` but not both.
uploadedPDF:
type: string
format: uri
description: If a PDF was uploaded for the letter, this will contain the signed
link to the uploaded PDF.
LetterBase:
type: object
required:
- object
properties:
object:
type: string
enum:
- letter
description: Always `letter`.
readOnly: true
perforatedPage:
type: number
enum:
- 1
description: If specified, indicates which letter page is perforated. Currently,
only the first page can be perforated.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the letter, if any.
attachedPDF:
allOf:
- $ref: "#/components/schemas/AttachedPDF"
description: You can attach a PDF to the content you supply for this letter.
This is useful if you have some stati
plasticCard:
allOf:
- $ref: "#/components/schemas/PlasticCard"
description: The plastic card sent out with the letter, if any.
pdfWorkflowRun:
type: string
description: The ID of the PDF workflow run that created the letter, if any.
readOnly: true
paper:
allOf:
- $ref: "#/components/schemas/LetterPremiumPaperID"
description: >-
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when
configured; otherwise `standard`.
LetterBuiltInPremiumPaperID:
type: string
enum:
- standard
- premium_paper_letter_standard_white_70lb
- premium_paper_letter_standard_white_80lb
description: Built-in paper IDs for letter products. Actual availability depends
on your organization settings.
LetterCreate:
anyOf:
- $ref: "#/components/schemas/LetterCreateWithHTML"
- $ref: "#/components/schemas/LetterCreateWithTemplate"
- $ref: "#/components/schemas/LetterCreateWithPDF"
LetterCreateBase:
type: object
required:
- to
- from
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
perforatedPage:
type: number
enum:
- 1
description: If specified, indicates which letter page is perforated. Currently,
only the first page can be perforated.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the letter, if any.
attachedPDF:
allOf:
- $ref: "#/components/schemas/AttachedPDF"
description: You can attach a PDF to the content you supply for this letter.
This is useful if you have some stati
plasticCard:
allOf:
- $ref: "#/components/schemas/PlasticCard"
description: The plastic card sent out with the letter, if any.
paper:
allOf:
- $ref: "#/components/schemas/LetterPremiumPaperID"
description: >-
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when
configured; otherwise `standard`.
doubleSided:
type: boolean
description: Indicates if the letter is double-sided.
default: false
color:
type: boolean
description: Indicates if the letter is in color.
default: false
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
size:
allOf:
- $ref: "#/components/schemas/LetterSize"
description: The size of the letter.
default: us_letter
addressPlacement:
allOf:
- $ref: "#/components/schemas/AddressPlacement"
description: The placement of the address on the letter.
default: top_first_page
envelope:
type: string
description: The envelope (ID) for the letter. You can either specify a custom
envelope ID or use the default `standard` envelope.
default: standard
LetterCreateFormMultiPart:
type: object
required:
- to
- from
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
perforatedPage:
type: number
enum:
- 1
description: If specified, indicates which letter page is perforated. Currently,
only the first page can be perforated.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the letter, if any.
attachedPDF:
allOf:
- $ref: "#/components/schemas/AttachedPDF"
description: You can attach a PDF to the content you supply for this letter.
This is useful if you have some stati
plasticCard:
allOf:
- $ref: "#/components/schemas/PlasticCard"
description: The plastic card sent out with the letter, if any.
paper:
allOf:
- $ref: "#/components/schemas/LetterPremiumPaperID"
description: >-
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when
configured; otherwise `standard`.
doubleSided:
type: boolean
description: Indicates if the letter is double-sided.
default: false
color:
type: boolean
description: Indicates if the letter is in color.
default: false
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
size:
allOf:
- $ref: "#/components/schemas/LetterSize"
description: The size of the letter.
default: us_letter
addressPlacement:
allOf:
- $ref: "#/components/schemas/AddressPlacement"
description: The placement of the address on the letter.
default: top_first_page
envelope:
type: string
description: The envelope (ID) for the letter. You can either specify a custom
envelope ID or use the default `standard` envelope.
default: standard
html:
type: string
description: The HTML content for the letter. You can supply _either_ this or
`template` but not both.
template:
type: string
description: The template ID for the letter. You can supply _either_ this or
`html` but not both.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A URL pointing to a PDF file for the letter or the PDF file itself.
description: "Multipart variant of the letter create body: the JSON variants'
fields, with the content fields optional."
LetterCreateWithHTML:
type: object
required:
- to
- from
- html
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
perforatedPage:
type: number
enum:
- 1
description: If specified, indicates which letter page is perforated. Currently,
only the first page can be perforated.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the letter, if any.
attachedPDF:
allOf:
- $ref: "#/components/schemas/AttachedPDF"
description: You can attach a PDF to the content you supply for this letter.
This is useful if you have some stati
plasticCard:
allOf:
- $ref: "#/components/schemas/PlasticCard"
description: The plastic card sent out with the letter, if any.
paper:
allOf:
- $ref: "#/components/schemas/LetterPremiumPaperID"
description: >-
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when
configured; otherwise `standard`.
doubleSided:
type: boolean
description: Indicates if the letter is double-sided.
default: false
color:
type: boolean
description: Indicates if the letter is in color.
default: false
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
size:
allOf:
- $ref: "#/components/schemas/LetterSize"
description: The size of the letter.
default: us_letter
addressPlacement:
allOf:
- $ref: "#/components/schemas/AddressPlacement"
description: The placement of the address on the letter.
default: top_first_page
envelope:
type: string
description: The envelope (ID) for the letter. You can either specify a custom
envelope ID or use the default `standard` envelope.
default: standard
html:
type: string
description: The HTML content for the letter. You can supply _either_ this or
`template` but not both.
LetterCreateWithPDF:
type: object
required:
- to
- from
- pdf
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
perforatedPage:
type: number
enum:
- 1
description: If specified, indicates which letter page is perforated. Currently,
only the first page can be perforated.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the letter, if any.
attachedPDF:
allOf:
- $ref: "#/components/schemas/AttachedPDF"
description: You can attach a PDF to the content you supply for this letter.
This is useful if you have some stati
plasticCard:
allOf:
- $ref: "#/components/schemas/PlasticCard"
description: The plastic card sent out with the letter, if any.
paper:
allOf:
- $ref: "#/components/schemas/LetterPremiumPaperID"
description: >-
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when
configured; otherwise `standard`.
doubleSided:
type: boolean
description: Indicates if the letter is double-sided.
default: false
color:
type: boolean
description: Indicates if the letter is in color.
default: false
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
size:
allOf:
- $ref: "#/components/schemas/LetterSize"
description: The size of the letter.
default: us_letter
addressPlacement:
allOf:
- $ref: "#/components/schemas/AddressPlacement"
description: The placement of the address on the letter.
default: top_first_page
envelope:
type: string
description: The envelope (ID) for the letter. You can either specify a custom
envelope ID or use the default `standard` envelope.
default: standard
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A URL pointing to a PDF file for the letter or the PDF file itself.
LetterCreateWithTemplate:
type: object
required:
- to
- from
- template
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
perforatedPage:
type: number
enum:
- 1
description: If specified, indicates which letter page is perforated. Currently,
only the first page can be perforated.
returnEnvelope:
type: string
description: The return envelope (ID) sent out with the letter, if any.
attachedPDF:
allOf:
- $ref: "#/components/schemas/AttachedPDF"
description: You can attach a PDF to the content you supply for this letter.
This is useful if you have some stati
plasticCard:
allOf:
- $ref: "#/components/schemas/PlasticCard"
description: The plastic card sent out with the letter, if any.
paper:
allOf:
- $ref: "#/components/schemas/LetterPremiumPaperID"
description: >-
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when
configured; otherwise `standard`.
doubleSided:
type: boolean
description: Indicates if the letter is double-sided.
default: false
color:
type: boolean
description: Indicates if the letter is in color.
default: false
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
size:
allOf:
- $ref: "#/components/schemas/LetterSize"
description: The size of the letter.
default: us_letter
addressPlacement:
allOf:
- $ref: "#/components/schemas/AddressPlacement"
description: The placement of the address on the letter.
default: top_first_page
envelope:
type: string
description: The envelope (ID) for the letter. You can either specify a custom
envelope ID or use the default `standard` envelope.
default: standard
template:
type: string
description: The template ID for the letter. You can supply _either_ this or
`html` but not both.
LetterEnvelopeType:
type: string
enum:
- standard_double_window
- flat
description: The type of envelope used for the letter.
LetterList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Letter"
LetterPlacement:
type: string
enum:
- before_cheque
- after_cheque
description: >-
Enum representing where a letter attached to a cheque is placed relative
to
the cheque page.
LetterPremiumPaperID:
anyOf:
- $ref: "#/components/schemas/LetterBuiltInPremiumPaperID"
- $ref: "#/components/schemas/PremiumPaperID"
LetterSize:
type: string
enum:
- us_letter
- a4
description: Enum representing the supported letter sizes.
MailboxAddress:
type: object
required:
- addressLine1
- countryCode
properties:
addressLine1:
type: string
description: The address line 1 of the mailbox.
readOnly: true
addressLine2:
type: string
description: The address line 2 of the mailbox.
readOnly: true
city:
type: string
description: The city of the mailbox.
readOnly: true
provinceOrState:
type: string
description: The province or state of the mailbox.
readOnly: true
postalOrZip:
type: string
description: The postal or ZIP code of the mailbox.
readOnly: true
countryCode:
allOf:
- $ref: "#/components/schemas/VirtualMailboxSupportedCountry"
description: The country code of the mailbox.
readOnly: true
description: The address information for a mailbox.
MailingList:
type: object
required:
- id
- live
- createdAt
- updatedAt
- status
properties:
id:
type: string
pattern: mailing_list_[a-zA-Z0-9]+
description: A unique ID prefixed with mailing_list_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
status:
allOf:
- $ref: "#/components/schemas/ProcessStatus"
description: The current status of the mailing list processing.
readOnly: true
errors:
type: array
items:
$ref: "#/components/schemas/ProcessError"
description: A list of processing errors encountered, if any.
readOnly: true
description: Represents a mailing list.
MailingListCreate:
type: object
properties:
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
description: Parameters for creating a new mailing list.
MailingListImport:
type: object
required:
- id
- live
- createdAt
- updatedAt
- file
- fileType
- status
- receiverAddressMapping
- errors
- notes
- validRowCount
- invalidRowCount
- receiverStatusCount
- organization
properties:
id:
type: string
pattern: mailing_list_import_[a-zA-Z0-9]+
description: A unique ID prefixed with mailing_list_import_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
file:
anyOf:
- type: string
format: uri
- type: string
format: byte
description: The CSV file for this import.
fileType:
allOf:
- $ref: "#/components/schemas/FileType"
description: The type of file uploaded, only CSV supported currently
status:
allOf:
- $ref: "#/components/schemas/MailingListImportProcessStatus"
description: The current status of the import process.
readOnly: true
receiverMergeVariableMapping:
type: object
additionalProperties:
type: string
description: Optional mapping of columns for receiver merge variables.
senderMergeVariableMapping:
type: object
additionalProperties:
type: string
description: Optional mapping of columns for sender merge variables.
receiverAddressMapping:
type: object
additionalProperties:
type: string
description: Mapping of columns for receiver addresses.
senderAddressMapping:
type: object
additionalProperties:
type: string
description: >-
Optional mapping of columns for sender addresses.
If this is present, then all receivers should have a corresponding
sender.
reportURL:
type: string
format: uri
description: A temporary URL to download the processing report, available once
the import is completed.
readOnly: true
errors:
type: array
items:
$ref: "#/components/schemas/MailingListImportProcessError"
description: A list of processing errors encountered, if any. Present when
status is 'changes_required'.
readOnly: true
notes:
type: array
items:
$ref: "#/components/schemas/Note"
description: Additional notes about the import process.
readOnly: true
validRowCount:
type: integer
format: int32
description: Number of valid rows processed from the file.
readOnly: true
invalidRowCount:
type: integer
format: int32
description: Number of invalid rows found in the file.
readOnly: true
receiverStatusCount:
allOf:
- $ref: "#/components/schemas/VerificationStatusCount"
description: Verification status counts for receiver contacts.
readOnly: true
senderStatusCount:
allOf:
- $ref: "#/components/schemas/VerificationStatusCount"
description: Verification status counts for sender contacts, if applicable.
readOnly: true
organization:
type: string
description: The organization that owns this import.
readOnly: true
description: Represents a mailing list import.
MailingListImportCreate:
type: object
required:
- file
- fileType
- receiverAddressMapping
properties:
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
file:
anyOf:
- type: string
format: uri
- type: string
format: byte
description: The CSV file for this import.
fileType:
allOf:
- $ref: "#/components/schemas/FileType"
description: The type of file uploaded, only CSV supported currently
receiverMergeVariableMapping:
type: object
additionalProperties:
type: string
description: Optional mapping of columns for receiver merge variables.
senderMergeVariableMapping:
type: object
additionalProperties:
type: string
description: Optional mapping of columns for sender merge variables.
receiverAddressMapping:
type: object
additionalProperties:
type: string
description: Mapping of columns for receiver addresses.
senderAddressMapping:
type: object
additionalProperties:
type: string
description: >-
Optional mapping of columns for sender addresses.
If this is present, then all receivers should have a corresponding
sender.
description: Parameters for creating a new mailing list import.
MailingListImportList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/MailingListImportResponse"
description: A list of mailing list imports.
MailingListImportProcessError:
type: object
required:
- type
- message
properties:
type:
allOf:
- $ref: "#/components/schemas/MailingListImportProcessErrorType"
description: The type categorizing the error.
message:
type: string
description: A human-readable message describing the error.
description: Details of a specific error encountered during import processing.
MailingListImportProcessErrorType:
type: string
enum:
- no_valid_contacts_error
- multiple_countries_error
- invalid_contact_count_error
- internal_service_error
description: Type of error encountered during import processing.
MailingListImportProcessStatus:
type: string
enum:
- validating
- completed
- changes_required
description: Status of the mailing list import process.
MailingListImportResponse:
type: object
required:
- id
- live
- createdAt
- updatedAt
- status
- errors
- notes
- validRowCount
- invalidRowCount
- receiverStatusCount
- organization
- file
properties:
id:
type: string
pattern: mailing_list_import_[a-zA-Z0-9]+
description: A unique ID prefixed with mailing_list_import_
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
status:
allOf:
- $ref: "#/components/schemas/MailingListImportProcessStatus"
description: The current status of the import process.
reportURL:
type: string
format: uri
description: A temporary URL to download the processing report, available once
the import is completed.
errors:
type: array
items:
$ref: "#/components/schemas/MailingListImportProcessError"
description: A list of processing errors encountered, if any. Present when
status is 'changes_required'.
notes:
type: array
items:
$ref: "#/components/schemas/Note"
description: Additional notes about the import process.
validRowCount:
type: integer
format: int32
description: Number of valid rows processed from the file.
invalidRowCount:
type: integer
format: int32
description: Number of invalid rows found in the file.
receiverStatusCount:
allOf:
- $ref: "#/components/schemas/VerificationStatusCount"
description: Verification status counts for receiver contacts.
senderStatusCount:
allOf:
- $ref: "#/components/schemas/VerificationStatusCount"
description: Verification status counts for sender contacts, if applicable.
organization:
type: string
description: The organization that owns this import.
file:
$ref: "#/components/schemas/MailingListImportResponseFile"
description: Read-only view of a MailingListImport
MailingListImportResponseFile:
type: object
required:
- fileType
- receiverAddressMapping
- url
properties:
fileType:
allOf:
- $ref: "#/components/schemas/FileType"
description: The type of file being imported.
receiverAddressMapping:
type: object
additionalProperties:
type: string
description: |-
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
receiverMergeVariableMapping:
type: object
additionalProperties:
type: string
description: Optional mapping of columns for receiver merge variables.
senderAddressMapping:
type: object
additionalProperties:
type: string
description: Optional mapping of columns for sender addresses.
senderMergeVariableMapping:
type: object
additionalProperties:
type: string
description: Optional mapping of columns for sender merge variables.
url:
type: string
format: uri
description: The signed URL your controller generates.
description: "The file object your controller returns: all the mappings plus a
signed URL."
MailingListImportUpdate:
type: object
properties:
description:
type: string
nullable: true
description: An optional description for the import. Set to `null` to remove the
existing description.
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: Optional key-value data associated with the import. Set to `null`
to remove existing metadata.
description: Parameters for updating an existing mailing list import.
MailingListJobsRequest:
type: object
properties:
addContacts:
type: array
items:
type: string
minItems: 1
maxItems: 500
description: List of contact IDs to add to the mailing list. Cannot be used with
other operations.
removeContacts:
type: array
items:
type: string
minItems: 1
maxItems: 500
description: List of contact IDs to remove from the mailing list. Cannot be used
with other operations.
addMailingListImports:
type: array
items:
type: string
minItems: 1
maxItems: 10
description: List of mailing list import IDs to add to the mailing list. Cannot
be used with other operations.
removeMailingListImports:
type: array
items:
type: string
minItems: 1
maxItems: 10
description: List of mailing list import IDs to remove from the mailing list.
Cannot be used with other operations.
description: Parameters for bulk operations on mailing list contacts.
MailingListList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/MailingList"
description: A list of mailing lists.
MailingListUpdate:
type: object
properties:
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
description: Parameters for updating an existing mailing list.
Note:
type: object
required:
- type
- message
properties:
type:
allOf:
- $ref: "#/components/schemas/NoteType"
description: The type of note.
message:
type: string
description: A human-readable message describing the note.
description: Details about a note in the import process.
NoteType:
type: string
enum:
- truncated_test_file
- skipped_invalid_contacts
description: Type of note attached to the import process.
OrderIMBStatus:
type: string
enum:
- entered_mail_stream
- out_for_delivery
- returned_to_sender
OrderMailingClass:
type: string
enum:
- 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
OrderPreviewSendPreference:
type: string
enum:
- do_not_send
- send_live_only
- send_live_and_test
description: The list of preferences for receiving order preview emails.
OrderStatus:
type: string
enum:
- ready
- printing
- processed_for_delivery
- completed
- cancelled
PlasticCard:
type: object
required:
- size
properties:
size:
allOf:
- $ref: "#/components/schemas/PlasticCardSize"
description: The size of the plastic card.
singleSided:
allOf:
- $ref: "#/components/schemas/PlasticCardSingleSided"
description: The single-sided plastic card details.
doubleSided:
allOf:
- $ref: "#/components/schemas/PlasticCardDoubleSided"
description: The double-sided plastic card details.
description: Model representing a plastic card.
PlasticCardDoubleSided:
type: object
properties:
frontHTML:
type: string
description: The HTML content for the front side of the double-sided plastic card.
backHTML:
type: string
description: The HTML content for the back side of the double-sided plastic card.
frontTemplate:
type: string
description: The template ID for the front side of the double-sided plastic card.
backTemplate:
type: string
description: The template ID for the back side of the double-sided plastic card.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A URL pointing to a PDF file for the double-sided plastic card or
the file itself.
description: Model representing a double-sided plastic card.
PlasticCardSingleSided:
type: object
properties:
html:
type: string
description: The HTML content for the single-sided plastic card. Can specify one
of this, `template`, or `pdf`.
template:
type: string
description: The template ID for the single-sided plastic card.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A URL pointing to a PDF file for the single-sided plastic card or
the PDF file itself.
description: Model representing a single-sided plastic card.
PlasticCardSize:
type: string
enum:
- standard
description: Enum representing the size of the plastic card.
Postcard:
type: object
required:
- status
- id
- live
- createdAt
- updatedAt
- sendDate
- mailingClass
- to
- object
- size
properties:
status:
allOf:
- $ref: "#/components/schemas/OrderStatus"
description: See `OrderStatus` for more details on the status of this order.
mergeVariables:
type: object
additionalProperties: {}
description: 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.
trackingNumber:
type: string
description: The tracking number of this order. Populated after an
express/certified order has been processed for delivery.
imbStatus:
allOf:
- $ref: "#/components/schemas/OrderIMBStatus"
description: 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.
imbZIPCode:
type: string
description: The most recent ZIP code of the USPS facility that the order has
been processed through. Only populated when an `imbStatus` is
present.
imbDate:
type: string
format: date-time
description: The last date that the IMB status was updated. See `imbStatus` for
more details.
cancellation:
allOf:
- $ref: "#/components/schemas/Cancellation"
description: The cancellation details of this order. Populated if the order has
been cancelled.
url:
type: string
format: uri
description: >-
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.
id:
type: string
pattern: postcard_[a-zA-Z0-9]+
description: A unique ID prefixed with postcard_
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. This determines the speed and cost
of delivery. See `OrderMailingClass` for more details.
to:
allOf:
- $ref: "#/components/schemas/Contact"
description: The recipient of this order. This will be provided even if you
delete the underlying contact.
object:
type: string
enum:
- postcard
description: Always `postcard`.
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: >-
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when
configured; otherwise `standard`.
from:
allOf:
- $ref: "#/components/schemas/Contact"
description: The contact information of the sender.
PostcardBase:
type: object
required:
- object
- size
properties:
object:
type: string
enum:
- postcard
description: Always `postcard`.
readOnly: true
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: >-
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when
configured; otherwise `standard`.
PostcardBuiltInPremiumPaperID:
type: string
enum:
- standard
- premium_paper_heavy_1_glossy
- premium_paper_postcard_uv_glossy_ss
- premium_paper_postcard_uv_glossy_ss_120lb
- premium_paper_postcard_satin_ds
description: Built-in paper IDs for postcard products. Actual availability
depends on your organization settings.
PostcardCreate:
anyOf:
- $ref: "#/components/schemas/PostcardCreateWithHTML"
- $ref: "#/components/schemas/PostcardCreateWithTemplate"
- $ref: "#/components/schemas/PostcardCreateWithPDFURL"
- $ref: "#/components/schemas/PostcardCreateWithPDFFile"
PostcardCreateBase:
type: object
required:
- to
- size
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: >-
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when
configured; otherwise `standard`.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
PostcardCreateFormMultiPart:
type: object
required:
- to
- size
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: >-
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when
configured; otherwise `standard`.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
frontHTML:
type: string
description: The HTML content for the front of the postcard. You can supply
_either_ this or `frontTemplate` but not both.
backHTML:
type: string
description: The HTML content for the back of the postcard. You can supply
_either_ this or `backTemplate` but not both.
frontTemplate:
type: string
description: The template ID for the front of the postcard. You can supply
_either_ this or `frontHTML` but not both.
backTemplate:
type: string
description: The template ID for the back of the postcard. You can supply
_either_ this or `backHTML` but not both.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A 2 page PDF file upload or URL (front, then back). Cannot be
combined with the HTML or template fields.
description: "Multipart variant of the postcard create body: the JSON variants'
fields, with the content fields optional."
PostcardCreateWithHTML:
type: object
required:
- to
- size
- frontHTML
- backHTML
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: >-
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when
configured; otherwise `standard`.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
frontHTML:
type: string
description: The HTML content for the front of the postcard. You can supply
_either_ this or `frontTemplate` but not both.
backHTML:
type: string
description: The HTML content for the back of the postcard. You can supply
_either_ this or `backTemplate` but not both.
PostcardCreateWithPDFFile:
type: object
required:
- to
- size
- pdf
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: >-
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when
configured; otherwise `standard`.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
pdf:
allOf:
- $ref: "#/components/schemas/BinaryFile"
description: 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).
PostcardCreateWithPDFURL:
type: object
required:
- to
- size
- pdf
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: >-
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when
configured; otherwise `standard`.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
pdf:
type: string
format: uri
description: 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).
PostcardCreateWithTemplate:
type: object
required:
- to
- size
- frontTemplate
- backTemplate
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/PostcardSize"
description: The size of the postcard.
paper:
allOf:
- $ref: "#/components/schemas/PostcardPremiumPaperID"
description: >-
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when
configured; otherwise `standard`.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
frontTemplate:
type: string
description: The template ID for the front of the postcard. You can supply
_either_ this or `frontHTML` but not both.
backTemplate:
type: string
description: The template ID for the back of the postcard. You can supply
_either_ this or `backHTML` but not both.
PostcardList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Postcard"
PostcardPremiumPaperID:
anyOf:
- $ref: "#/components/schemas/PostcardBuiltInPremiumPaperID"
- $ref: "#/components/schemas/PremiumPaperID"
PostcardSize:
type: string
enum:
- 6x4
- 9x6
- 11x6
description: Enum representing the supported postcard sizes.
PremiumPaperID:
type: string
pattern: ^(standard|premium_paper_[A-Za-z0-9_]+)$
description: |-
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
ProcessError:
type: object
required:
- type
- message
properties:
type:
allOf:
- $ref: "#/components/schemas/ProcessErrorType"
description: The type categorizing the error.
message:
type: string
description: A human-readable message describing the error.
description: Details of a specific error encountered during processing.
ProcessErrorType:
type: string
enum:
- mailing_list_imports_not_found_error
- download_file_error
- operational_error
- internal_service_error
description: Type of error encountered during mailing list processing.
ProcessStatus:
type: string
enum:
- creating_contacts
- removing_contacts
- counting_recipient_country_codes
- completed
description: Status of the mailing list processing.
Report:
type: object
required:
- id
- object
- live
- sqlQuery
- createdAt
- updatedAt
properties:
id:
type: string
description: Unique identifier for the report.
object:
type: string
enum:
- report
description: Always `report`.
live:
type: boolean
description: Indicates if the report is associated with the live or test
environment.
sqlQuery:
type: string
description: The SQL query defining the report.
description:
type: string
description: An optional user-friendly description for the report.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata associated with the report.
createdAt:
type: string
format: date-time
description: Timestamp when the report was created.
updatedAt:
type: string
format: date-time
description: Timestamp when the report was last updated.
description: Represents a saved Report definition.
ReportBase:
type: object
required:
- sqlQuery
properties:
sqlQuery:
type: string
description: The SQL query defining the report.
description:
type: string
description: An optional user-friendly description for the report.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata associated with the report.
description: Base properties shared between Report creation and retrieval.
ReportCreate:
type: object
allOf:
- $ref: "#/components/schemas/ReportBase"
description: Model for creating a new Report.
ReportExport:
type: object
required:
- id
- object
- live
- report
- createdAt
- updatedAt
properties:
id:
type: string
description: Unique identifier for the report export.
object:
type: string
enum:
- report_export
description: Always `report_export`.
live:
type: boolean
description: Indicates if the export is associated with the live or test
environment.
report:
type: object
properties:
id:
type: string
description: The ID of the report.
sqlQuery:
type: string
description: The SQL query used for this export (snapshotted at creation time).
required:
- id
- sqlQuery
description: Details of the report this export was generated from.
params:
type: array
items:
type: string
description: Optional parameters to bind to the SQL query of the associated
report.
description:
type: string
description: An optional user-friendly description for the export.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata associated with the export.
outputURL:
type: string
format: uri
description: A signed URL to download the exported data (CSV format). Available
when generation is complete and successful.
failureMessage:
type: string
description: If export generation failed, this contains the error message.
truncatedToBytes:
type: integer
format: int64
description: If the output was truncated, indicates the byte limit reached.
sizeInBytes:
type: integer
format: int64
description: The size of the generated export file in bytes.
rowCount:
type: integer
format: int64
description: The number of rows in the exported data.
createdAt:
type: string
format: date-time
description: Timestamp when the export was created.
updatedAt:
type: string
format: date-time
description: Timestamp when the export was last updated (e.g., finished
generation).
description: Represents a report export job and its results.
ReportExportBase:
type: object
properties:
params:
type: array
items:
type: string
description: Optional parameters to bind to the SQL query of the associated
report.
description:
type: string
description: An optional user-friendly description for the export.
metadata:
type: object
additionalProperties:
type: string
description: Optional key-value metadata associated with the export.
description: Base properties for a report export.
ReportExportCreate:
type: object
allOf:
- $ref: "#/components/schemas/ReportExportBase"
description: Model for creating a new Report Export.
ReportList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Report"
description: Represents a list of Reports.
ReportRecord:
type: object
additionalProperties: {}
description: Represents a single row/record from a report sample or export.
ReportSample:
type: object
required:
- id
- report
- records
properties:
id:
type: string
description: Unique identifier for the sample query result.
report:
type: string
nullable: true
description: The ID of the report this sample was generated from, or null for
ad-hoc samples.
records:
type: array
items:
$ref: "#/components/schemas/ReportRecord"
description: The actual data records returned by the sample query.
description: Represents the result of a report sample query.
ReportSampleCreateBase:
type: object
properties:
params:
type: array
items:
type: string
description: Optional parameters to bind to the SQL query (e.g., for
placeholders like ? or $1).
limit:
type: integer
format: int32
maximum: 1000
description: Maximum number of rows to return in the sample.
default: 100
description: Base properties for creating a report sample.
ReportUpdate:
type: object
properties:
sqlQuery:
type: string
description: The SQL query defining the report.
description:
type: string
nullable: true
description: An optional user-friendly description for the report. Set to null
to remove.
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: Optional key-value metadata associated with the report. Set to null
to remove.
description: Model for updating an existing Report.
ReturnEnvelope:
type: object
required:
- object
- to
- available
properties:
object:
type: string
enum:
- return_envelope
description: Always `return_envelope`.
readOnly: true
to:
allOf:
- $ref: "#/components/schemas/ReturnEnvelopeContact"
description: The contact whose address will be printed onto the return envelope.
readOnly: true
available:
type: integer
format: int32
description: >-
The number of return envelopes available to use in your orders
immediately. This increases when a return envelope order is filled
and
decreases as you send orders which include this return envelope.
readOnly: true
allOf:
- type: object
required:
- id
- live
- createdAt
- updatedAt
properties:
id:
type: string
pattern: return_envelope_[a-zA-Z0-9]+
description: A unique ID prefixed with return_envelope_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
ReturnEnvelopeContact:
type: object
required:
- addressLine1
- countryCode
- addressStatus
- id
properties:
addressLine1:
type: string
description: The first line of the contact's address.
addressLine2:
type: string
description: Second line of the contact's address, if applicable.
city:
type: string
description: The city of the contact's address.
provinceOrState:
type: string
description: Province or state of the contact's address.
postalOrZip:
type: string
description: The postal or ZIP code of the contact's address.
countryCode:
type: string
description: The ISO 3611-1 country code of the contact's address.
addressStatus:
type: string
enum:
- verified
- corrected
- failed
description: One of `verified`, `corrected`, or `failed`.
readOnly: true
addressErrors:
type: string
description: A series of human-readable errors/warnings that were raised when
running the provided address through our address verification.
readOnly: true
companyName:
type: string
description: Company name of the contact.
firstName:
type: string
description: First name of the contact.
lastName:
type: string
description: Last name of the contact.
email:
type: string
description: Email of the contact.
phoneNumber:
type: string
description: Phone number of the contact.
jobTitle:
type: string
description: Job title of the contact.
skipVerification:
type: boolean
description: If `true`, PostGrid will skip running this contact's address
through our address verification system.
default: false
forceVerifiedStatus:
type: boolean
description: If `true`, PostGrid will force this contact to have an
`addressStatus` of `verified` even if our address verification
system says otherwise.
default: false
secret:
type: boolean
description: If `true`, the contact's details are hidden from the dashboard and
API responses apart from the final print. The contact ID can then be
used as a token for sending mail without giving access to the
underlying data.
id:
type: string
pattern: contact_[a-zA-Z0-9]+
description: A unique ID prefixed with contact_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
description: >-
The contact denormalized onto a return envelope when it is created.
Unlike
a full contact it is not a standalone resource, so it has no `object`,
`live`, `createdAt`, or `updatedAt` fields.
ReturnEnvelopeCreate:
type: object
required:
- to
properties:
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: |-
A contact ID or a contact object containing the address that will be
printed onto the return envelope.
ReturnEnvelopeList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/ReturnEnvelope"
ReturnEnvelopeOrder:
type: object
required:
- object
- returnEnvelope
- quantityOrdered
- status
properties:
object:
type: string
enum:
- return_envelope_order
description: Always `return_envelope_order`.
readOnly: true
returnEnvelope:
anyOf:
- type: string
- $ref: "#/components/schemas/ReturnEnvelope"
description: >-
The ID of the return envelope that this order replenishes. Expanded
into the full return envelope object on the individual order
retrieval
and cancellation endpoints when `expand[]=returnEnvelope` is
supplied.
readOnly: true
quantityOrdered:
type: integer
format: int32
minimum: 5000
description: The quantity of return envelopes ordered. Minimum 5000.
quantityFilled:
type: integer
format: int32
description: >-
The quantity of return envelopes that were filled for this order.
Only
returned once the order's status is `filled`.
readOnly: true
status:
allOf:
- $ref: "#/components/schemas/ReturnEnvelopeOrderStatus"
description: The status of this order.
readOnly: true
allOf:
- type: object
required:
- id
- live
- createdAt
- updatedAt
properties:
id:
type: string
pattern: return_envelope_order_[a-zA-Z0-9]+
description: A unique ID prefixed with return_envelope_order_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
ReturnEnvelopeOrderList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/ReturnEnvelopeOrder"
ReturnEnvelopeOrderStatus:
type: string
enum:
- placed
- filled
- cancelled
description: The status of a return envelope order.
SavedReportSampleCreate:
type: object
allOf:
- $ref: "#/components/schemas/ReportSampleCreateBase"
description: Model for creating a sample from a saved report.
SelfMailer:
type: object
required:
- status
- id
- live
- createdAt
- updatedAt
- sendDate
- mailingClass
- to
- object
- size
- from
properties:
status:
allOf:
- $ref: "#/components/schemas/OrderStatus"
description: See `OrderStatus` for more details on the status of this order.
mergeVariables:
type: object
additionalProperties: {}
description: 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.
trackingNumber:
type: string
description: The tracking number of this order. Populated after an
express/certified order has been processed for delivery.
imbStatus:
allOf:
- $ref: "#/components/schemas/OrderIMBStatus"
description: 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.
imbZIPCode:
type: string
description: The most recent ZIP code of the USPS facility that the order has
been processed through. Only populated when an `imbStatus` is
present.
imbDate:
type: string
format: date-time
description: The last date that the IMB status was updated. See `imbStatus` for
more details.
cancellation:
allOf:
- $ref: "#/components/schemas/Cancellation"
description: The cancellation details of this order. Populated if the order has
been cancelled.
url:
type: string
format: uri
description: >-
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.
id:
type: string
pattern: self_mailer_[a-zA-Z0-9]+
description: A unique ID prefixed with self_mailer_
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. This determines the speed and cost
of delivery. See `OrderMailingClass` for more details.
to:
allOf:
- $ref: "#/components/schemas/Contact"
description: The recipient of this order. This will be provided even if you
delete the underlying contact.
object:
type: string
enum:
- self_mailer
description: Always `self_mailer`.
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
from:
allOf:
- $ref: "#/components/schemas/Contact"
description: The contact information of the sender.
SelfMailerBase:
type: object
required:
- object
- size
properties:
object:
type: string
enum:
- self_mailer
description: Always `self_mailer`.
readOnly: true
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
SelfMailerCreate:
anyOf:
- $ref: "#/components/schemas/SelfMailerCreateWithHTML"
- $ref: "#/components/schemas/SelfMailerCreateWithTemplate"
- $ref: "#/components/schemas/SelfMailerCreateWithPDFURL"
- $ref: "#/components/schemas/SelfMailerCreateWithPDFFile"
SelfMailerCreateBase:
type: object
required:
- to
- size
- from
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
SelfMailerCreateFormMultiPart:
type: object
required:
- to
- size
- from
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
insideHTML:
type: string
description: The HTML content for the inside of the self-mailer. You can supply
_either_ this or `insideTemplate` but not both.
outsideHTML:
type: string
description: The HTML content for the outside of the self-mailer. You can supply
_either_ this or `outsideTemplate` but not both.
insideTemplate:
type: string
description: The template ID for the inside of the self-mailer. You can supply
_either_ this or `insideHTML` but not both.
outsideTemplate:
type: string
description: The template ID for the outside of the self-mailer. You can supply
_either_ this or `outsideHTML` but not both.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A 2 page PDF file upload or URL (inside, then outside). Cannot be
combined with the HTML or template fields.
description: "Multipart variant of the self-mailer create body: the JSON
variants' fields, with the content fields optional."
SelfMailerCreateWithHTML:
type: object
required:
- to
- size
- from
- insideHTML
- outsideHTML
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
insideHTML:
type: string
description: The HTML content for the inside of the self-mailer. You can supply
_either_ this or `insideTemplate` but not both.
outsideHTML:
type: string
description: The HTML content for the outside of the self-mailer. You can supply
_either_ this or `outsideTemplate` but not both.
SelfMailerCreateWithPDFFile:
type: object
required:
- to
- size
- from
- pdf
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
pdf:
allOf:
- $ref: "#/components/schemas/BinaryFile"
description: 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).
SelfMailerCreateWithPDFURL:
type: object
required:
- to
- size
- from
- pdf
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
pdf:
type: string
format: uri
description: 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).
SelfMailerCreateWithTemplate:
type: object
required:
- to
- size
- from
- insideTemplate
- outsideTemplate
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SelfMailerSize"
description: The size of the self-mailer.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to`.
insideTemplate:
type: string
description: The template ID for the inside of the self-mailer. You can supply
_either_ this or `insideHTML` but not both.
outsideTemplate:
type: string
description: The template ID for the outside of the self-mailer. You can supply
_either_ this or `outsideHTML` but not both.
SelfMailerList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/SelfMailer"
SelfMailerSize:
type: string
enum:
- 8.5x11_bifold
- 8.5x11_trifold
- 9.5x16_trifold
description: Enum representing the supported self-mailer sizes.
SnapPack:
type: object
required:
- status
- id
- live
- createdAt
- updatedAt
- sendDate
- mailingClass
- to
- object
- size
- from
properties:
status:
allOf:
- $ref: "#/components/schemas/OrderStatus"
description: See `OrderStatus` for more details on the status of this order.
mergeVariables:
type: object
additionalProperties: {}
description: 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.
trackingNumber:
type: string
description: The tracking number of this order. Populated after an
express/certified order has been processed for delivery.
imbStatus:
allOf:
- $ref: "#/components/schemas/OrderIMBStatus"
description: 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.
imbZIPCode:
type: string
description: The most recent ZIP code of the USPS facility that the order has
been processed through. Only populated when an `imbStatus` is
present.
imbDate:
type: string
format: date-time
description: The last date that the IMB status was updated. See `imbStatus` for
more details.
cancellation:
allOf:
- $ref: "#/components/schemas/Cancellation"
description: The cancellation details of this order. Populated if the order has
been cancelled.
url:
type: string
format: uri
description: >-
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.
id:
type: string
pattern: snap_pack_[a-zA-Z0-9]+
description: A unique ID prefixed with snap_pack_
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. This determines the speed and cost
of delivery. See `OrderMailingClass` for more details.
to:
allOf:
- $ref: "#/components/schemas/Contact"
description: The recipient of this order. This will be provided even if you
delete the underlying contact.
object:
type: string
enum:
- snap_pack
description: Always `snap_pack`.
size:
allOf:
- $ref: "#/components/schemas/SnapPackSize"
description: The size of the snap pack.
from:
allOf:
- $ref: "#/components/schemas/Contact"
description: The contact information of the sender.
insideHTML:
type: string
description: The HTML content for the inside of the snap pack, when provided
instead of a template or PDF.
outsideHTML:
type: string
description: The HTML content for the outside of the snap pack, when provided
instead of a template or PDF.
insideTemplate:
type: string
description: The template ID for the inside of the snap pack, when provided
instead of HTML or PDF.
outsideTemplate:
type: string
description: The template ID for the outside of the snap pack, when provided
instead of HTML or PDF.
uploadedPDF:
type: string
format: uri
description: A signed URL to the uploaded PDF provided at creation time, if a
PDF was supplied.
SnapPackBase:
type: object
required:
- object
- size
properties:
object:
type: string
enum:
- snap_pack
description: Always `snap_pack`.
readOnly: true
size:
allOf:
- $ref: "#/components/schemas/SnapPackSize"
description: The size of the snap pack.
SnapPackCapabilities:
type: object
required:
- sizes
- mailingClasses
properties:
sizes:
type: array
items:
$ref: "#/components/schemas/SnapPackSize"
mailingClasses:
type: array
items:
$ref: "#/components/schemas/OrderMailingClass"
SnapPackCreate:
anyOf:
- $ref: "#/components/schemas/SnapPackCreateWithHTML"
- $ref: "#/components/schemas/SnapPackCreateWithTemplate"
- $ref: "#/components/schemas/SnapPackCreateWithPDF"
SnapPackCreateBase:
type: object
required:
- to
- size
- from
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SnapPackSize"
description: The size of the snap pack.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to` contact.
SnapPackCreateFormMultiPart:
type: object
required:
- to
- size
- from
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SnapPackSize"
description: The size of the snap pack.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to` contact.
insideHTML:
type: string
description: The HTML content for the inside of the snap pack. You can supply
_either_ this or `insideTemplate` but not both.
outsideHTML:
type: string
description: The HTML content for the outside of the snap pack. You can supply
_either_ this or `outsideTemplate` but not both.
insideTemplate:
type: string
description: The template ID for the inside of the snap pack. You can supply
_either_ this or `insideHTML` but not both.
outsideTemplate:
type: string
description: The template ID for the outside of the snap pack. You can supply
_either_ this or `outsideHTML` but not both.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A URL or a multipart-uploaded two-page PDF (first page is the
outside, second page is the inside) that matches the selected snap
pack size.
description: "Multipart variant of the snap pack create body: the JSON variants'
fields, with the content fields optional."
SnapPackCreateWithHTML:
type: object
required:
- to
- size
- from
- insideHTML
- outsideHTML
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SnapPackSize"
description: The size of the snap pack.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to` contact.
insideHTML:
type: string
description: The HTML content for the inside of the snap pack. You can supply
_either_ this or `insideTemplate` but not both.
outsideHTML:
type: string
description: The HTML content for the outside of the snap pack. You can supply
_either_ this or `outsideTemplate` but not both.
SnapPackCreateWithPDF:
type: object
required:
- to
- size
- from
- pdf
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SnapPackSize"
description: The size of the snap pack.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to` contact.
pdf:
oneOf:
- type: string
format: uri
- $ref: "#/components/schemas/BinaryFile"
description: A URL or a multipart-uploaded two-page PDF (first page is the
outside, second page is the inside) that matches the selected snap
pack size.
SnapPackCreateWithTemplate:
type: object
required:
- to
- size
- from
- insideTemplate
- outsideTemplate
properties:
mergeVariables:
type: object
additionalProperties: {}
description: 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.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
sendDate:
type: string
format: date-time
description: 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.
mailingClass:
allOf:
- $ref: "#/components/schemas/OrderMailingClass"
description: The mailing class of this order. If not provided, automatically set
to `first_class`.
to:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: 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.
size:
allOf:
- $ref: "#/components/schemas/SnapPackSize"
description: The size of the snap pack.
from:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: The contact information of the sender. You can pass contact
information inline here just like you can for the `to` contact.
insideTemplate:
type: string
description: The template ID for the inside of the snap pack. You can supply
_either_ this or `insideHTML` but not both.
outsideTemplate:
type: string
description: The template ID for the outside of the snap pack. You can supply
_either_ this or `outsideHTML` but not both.
SnapPackList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/SnapPack"
SnapPackSize:
type: string
enum:
- 8.5x11_bifold_v
description: Enum representing the supported snap pack sizes.
StructuredSearchQuery:
type: string
description: >-
You can supply a structured search query instead of supplying
unstructured text to any list endpoint help refine your search for a
resource.
For example, let's say you created a series of letters that all had
`metadata: { campaignID: 'abc' }`. You could search for all those
letters by passing in `{ "metadata.campaignID": "abc" }` into the
`search` parameter.
Note that this string must be valid JSON.
SubOrganization:
type: object
required:
- id
- object
- name
- countryCode
- limit
- spend
- usage
- createdAt
- updatedAt
properties:
id:
type: string
description: A unique ID prefixed with `sub_org_`.
object:
type: string
enum:
- sub_org
description: Always `sub_org`.
name:
type: string
description: The name of the sub-organization.
countryCode:
type: string
description: The country code of the sub-organization.
limit:
type: integer
description: >-
The limit of mailings the sub-organization can send before being
charged
overages for the month.
spend:
type: integer
description: >-
The current rolling charge for the sub-organization for the month,
in
cents.
usage:
type: integer
description: The amount of mail the sub-organization has sent out this month.
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last update.
description: The Sub-Organization object.
SubOrganizationCreate:
type: object
required:
- name
- email
- password
- organizationName
- countryCode
properties:
name:
type: string
description: The name of the user to be created alongside the sub-organization.
email:
type: string
description: The email of the user to be created alongside the sub-organization.
password:
type: string
description: The password of the user to be created alongside the
sub-organization.
phoneNumber:
type: string
description: |-
The phone number of the user to be created alongside the
sub-organization.
organizationName:
type: string
description: The name of the sub-organization.
countryCode:
type: string
description: The country code of the sub-organization.
SubOrganizationList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/SubOrganization"
TargetedListBuild:
type: object
required:
- id
- live
- createdAt
- updatedAt
- organization
- status
properties:
id:
type: string
pattern: targeted_list_build_[a-zA-Z0-9]+
description: A unique ID prefixed with targeted_list_build_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
organization:
type: string
description: The ID of the organization that owns this list build.
readOnly: true
status:
allOf:
- $ref: "#/components/schemas/TargetedListBuildStatus"
description: The current status of the list build.
readOnly: true
usConsumers:
allOf:
- $ref: "#/components/schemas/USConsumerListFilters"
description: |-
Filters for targeting US consumers (B2C). Mutually exclusive with
`usCompanies`.
usCompanies:
allOf:
- $ref: "#/components/schemas/USCompanyListFilters"
description: |-
Filters for targeting US companies (B2B). Mutually exclusive with
`usConsumers`.
limit:
type: integer
format: int32
minimum: 1
description: |-
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
quote:
allOf:
- $ref: "#/components/schemas/TargetedListBuildQuote"
description: |-
The generated quote for this list build. Present once `status`
transitions to `quote_ready`.
readOnly: true
previewRecords:
type: array
items:
$ref: "#/components/schemas/TargetedListBuildPreviewRecord"
description: |-
A small number of masked sample records for the configured filters,
populated alongside `quote`.
readOnly: true
confirmedAt:
type: string
format: date-time
description: The UTC time at which the build was confirmed, if any.
readOnly: true
completedAt:
type: string
format: date-time
description: |-
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
readOnly: true
buildProgressPercent:
type: number
format: float
minimum: 0
maximum: 100
description: |-
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
readOnly: true
mailingList:
type: string
description: |-
The ID of the mailing list that was built. Present once `status` is
`completed`.
readOnly: true
errors:
type: array
items:
$ref: "#/components/schemas/TargetedListBuildError"
description: Any errors encountered while generating a quote or building the list.
readOnly: true
description: >-
A targeted list build represents a request to build a new mailing list
by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
TargetedListBuildAutocompleteField:
type: string
enum:
- industry
description: A field that can be autocompleted when configuring list build filters.
TargetedListBuildAutocompleteItem:
type: object
required:
- value
- type
properties:
value:
type: string
description: The suggested value (e.g., an industry name).
type:
allOf:
- $ref: "#/components/schemas/TargetedListBuildAutocompleteField"
description: The field this suggestion corresponds to.
description: A single autocomplete suggestion.
TargetedListBuildAutocompleteRequest:
type: object
required:
- field
properties:
field:
allOf:
- $ref: "#/components/schemas/TargetedListBuildAutocompleteField"
description: |-
The field being autocompleted. Results will be values that can be
supplied to the corresponding filter on a list build.
text:
type: string
description: Optional text prefix to narrow the autocomplete suggestions.
size:
type: integer
format: int32
minimum: 1
maximum: 100
description: |-
Maximum number of suggestions to return. Between 1 and 100.
Defaults to 25 if omitted.
description: Parameters for an autocomplete query.
TargetedListBuildAutocompleteResponse:
type: object
required:
- object
- data
properties:
object:
type: string
enum:
- list
data:
type: array
items:
$ref: "#/components/schemas/TargetedListBuildAutocompleteItem"
description: The list of suggestions returned by an autocomplete query.
TargetedListBuildCreate:
type: object
properties:
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
usConsumers:
allOf:
- $ref: "#/components/schemas/USConsumerListFilters"
description: |-
Filters for targeting US consumers (B2C). Mutually exclusive with
`usCompanies`.
usCompanies:
allOf:
- $ref: "#/components/schemas/USCompanyListFilters"
description: |-
Filters for targeting US companies (B2B). Mutually exclusive with
`usConsumers`.
limit:
type: integer
format: int32
minimum: 1
description: |-
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
description: Parameters for creating a new targeted list build.
TargetedListBuildError:
type: object
required:
- type
- message
properties:
type:
allOf:
- $ref: "#/components/schemas/TargetedListBuildErrorType"
description: The type categorizing the error.
message:
type: string
description: A human-readable message describing the error.
description: Details of an error encountered while processing a targeted list build.
TargetedListBuildErrorType:
type: string
enum:
- not_enough_info_to_quote
- insufficient_credits
- internal_service_error
description: Type of error encountered while generating a quote or building the list.
TargetedListBuildList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/TargetedListBuild"
description: A list of targeted list builds.
TargetedListBuildPreviewRecord:
type: object
required:
- name
- formattedAddress
properties:
name:
type: string
description: The masked name of the contact or business.
formattedAddress:
type: string
description: The masked, comma-joined formatted address of the contact.
description: |-
A single masked preview record returned with a quote so you can sanity
check the kind of contacts that will end up in the mailing list before
confirming the build.
TargetedListBuildQuote:
type: object
required:
- generatedAt
- count
- pricePerContactCents
properties:
generatedAt:
type: string
format: date-time
description: The UTC time at which the quote was generated.
count:
type: integer
format: int32
description: |-
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
pricePerContactCents:
type: number
format: double
description: >-
The price per contact, in cents. Multiply by `count` to get the
total
cost of building the list.
description: Details of the quote generated for a targeted list build.
TargetedListBuildStatus:
type: string
enum:
- generating_quote
- quote_ready
- creating_list
- completed
- failed
description: Status of a targeted list build.
TargetedListBuildUpdate:
type: object
properties:
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
usConsumers:
allOf:
- $ref: "#/components/schemas/USConsumerListFilters"
description: |-
Filters for targeting US consumers (B2C). Mutually exclusive with
`usCompanies`.
usCompanies:
allOf:
- $ref: "#/components/schemas/USCompanyListFilters"
description: |-
Filters for targeting US companies (B2B). Mutually exclusive with
`usConsumers`.
limit:
type: integer
format: int32
minimum: 1
description: |-
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
description: >-
Parameters for updating an existing targeted list build. Updates may
only
be made while the build has not yet been confirmed.
Changing `usConsumers` or `usCompanies` will reset the build's `status`
back to `generating_quote` and clear the previously generated `quote`
and
preview records. Providing `usConsumers` while the build had
`usCompanies`
(or vice versa) will clear the other side.
Template:
type: object
required:
- object
properties:
object:
type: string
enum:
- template
description: Always `template`.
readOnly: true
html:
type: string
description: The HTML content of this template.
allOf:
- type: object
required:
- id
- live
- createdAt
- updatedAt
properties:
id:
type: string
pattern: template_[a-zA-Z0-9]+
description: A unique ID prefixed with template_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
TemplateCreate:
type: object
properties:
html:
type: string
description: The HTML content of this template.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
TemplateEditorSession:
type: object
required:
- id
- object
- live
- template
- url
- createdAt
properties:
id:
type: string
pattern: template_editor_session_[a-zA-Z0-9]+
description: A unique ID prefixed with `template_editor_session_`.
readOnly: true
object:
type: string
enum:
- template_editor_session
description: Always `template_editor_session`.
readOnly: true
live:
type: boolean
description: "`true` if this is a live mode session else `false`."
readOnly: true
template:
type: string
description: ID of the underlying template that this edits.
backURL:
type: string
format: uri
description: The URL supplied when this editor session was created.
title:
type: string
description: The title supplied when this editor session was created.
trackers:
allOf:
- $ref: "#/components/schemas/VisibleTrackers"
description: Controls which Trackers are displayed in the template editor.
styles:
allOf:
- $ref: "#/components/schemas/TemplateEditorSessionStyles"
description: Style overrides for the template editor.
url:
type: string
format: uri
description: A URL that can be iframed or redirected to for editing the template.
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this session was created.
readOnly: true
TemplateEditorSessionCanvasStyles:
type: object
properties:
backgroundColor:
type: string
description: The canvas background color.
description: Style overrides for the template editor canvas.
TemplateEditorSessionCreate:
type: object
required:
- template
properties:
template:
type: string
description: ID of the underlying template that this edits.
backURL:
type: string
format: uri
description: The URL supplied when this editor session was created.
title:
type: string
description: The title supplied when this editor session was created.
trackers:
allOf:
- $ref: "#/components/schemas/VisibleTrackers"
description: Controls which Trackers are displayed in the template editor.
styles:
allOf:
- $ref: "#/components/schemas/TemplateEditorSessionStyles"
description: Style overrides for the template editor.
TemplateEditorSessionList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/TemplateEditorSession"
TemplateEditorSessionPanelTextStyles:
type: object
properties:
color:
type: string
description: The panel text color.
description: Style overrides for template editor panel text.
TemplateEditorSessionSaveButtonStyles:
type: object
properties:
backgroundColor:
type: string
description: The save button background color.
textColor:
type: string
description: The save button text color.
description: Style overrides for the template editor save button.
TemplateEditorSessionStyles:
type: object
properties:
canvas:
allOf:
- $ref: "#/components/schemas/TemplateEditorSessionCanvasStyles"
description: Style overrides for the editor canvas.
saveButton:
allOf:
- $ref: "#/components/schemas/TemplateEditorSessionSaveButtonStyles"
description: Style overrides for the editor save button.
panelText:
allOf:
- $ref: "#/components/schemas/TemplateEditorSessionPanelTextStyles"
description: Style overrides for the editor panel text.
description: Style overrides for the template editor session.
TemplateList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Template"
TemplateUpdate:
type: object
properties:
html:
type: string
description: The HTML content of this template.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
Tracker:
type: object
required:
- object
- redirectURLTemplate
- urlExpireAfterDays
- visitCount
- uniqueVisitCount
properties:
object:
type: string
enum:
- tracker
description: Always `tracker`.
readOnly: true
redirectURLTemplate:
type: string
description: The base template for URLs generated by this Tracker.
urlExpireAfterDays:
allOf:
- $ref: "#/components/schemas/TrackerURLExpiryDays"
description: The number of days generated Tracker URLs remain valid.
visitCount:
type: integer
format: int32
description: The total number of interactions the Tracker has had.
readOnly: true
uniqueVisitCount:
type: integer
format: int32
description: The unique number of interactions the Tracker has had.
readOnly: true
allOf:
- type: object
required:
- id
- live
- createdAt
- updatedAt
properties:
id:
type: string
pattern: tracker_[a-zA-Z0-9]+
description: A unique ID prefixed with tracker_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
TrackerCreate:
type: object
required:
- redirectURLTemplate
- urlExpireAfterDays
properties:
redirectURLTemplate:
type: string
description: The base template for URLs generated by this Tracker.
urlExpireAfterDays:
allOf:
- $ref: "#/components/schemas/TrackerURLExpiryDays"
description: The number of days generated Tracker URLs remain valid.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
TrackerList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Tracker"
TrackerURLExpiryDays:
type: number
enum:
- 30
- 60
- 90
- 180
- 365
description: The number of days generated Tracker URLs remain valid.
TrackerUpdate:
type: object
required:
- redirectURLTemplate
- urlExpireAfterDays
properties:
redirectURLTemplate:
type: string
description: The base template for URLs generated by this Tracker.
urlExpireAfterDays:
allOf:
- $ref: "#/components/schemas/TrackerURLExpiryDays"
description: The number of days generated Tracker URLs remain valid.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
TrackerVisit:
type: object
required:
- id
- object
- live
- tracker
- orderID
- device
- ipAddress
- createdAt
- updatedAt
properties:
id:
type: string
pattern: tracker_visit_[a-zA-Z0-9]+
description: A unique ID prefixed with `tracker_visit_`.
readOnly: true
object:
type: string
enum:
- tracker_visit
description: Always `tracker_visit`.
readOnly: true
live:
type: boolean
description: Indicates if the visit was used in a live order or not.
readOnly: true
tracker:
type: string
description: The ID of the tracker related to this visit.
readOnly: true
orderID:
type: string
description: The ID of the order where the interaction occurred.
readOnly: true
device:
type: string
description: The type of device associated with the visit.
readOnly: true
ipAddress:
type: string
description: The IP address associated with the visit.
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this visit was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this visit was last updated.
readOnly: true
TrackerVisitList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/TrackerVisit"
USCompanyEmployeeCount:
type: integer
format: int32
minimum: 1
maximum: 1000000
description: A number of employees at a US company. Between 1 and 1,000,000.
USCompanyFoundedYear:
type: integer
format: int32
minimum: 1600
maximum: 2100
description: A year in which a US company was founded. Between 1600 and 2100.
USCompanyListFilters:
type: object
required:
- postalCodes
properties:
postalCodes:
type: array
items:
type: string
minItems: 1
description: Required list of five-digit US ZIP codes to target.
companyTypes:
type: array
items:
$ref: "#/components/schemas/USCompanyType"
description: Filter by ownership structure of the company.
industries:
type: array
items:
type: string
description: Filter by free-form industry names (see the autocomplete endpoint).
tags:
type: array
items:
type: string
description: Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
naicsCodes:
type: array
items:
type: string
description: |-
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
employeeCount:
type: array
items:
$ref: "#/components/schemas/USCompanyEmployeeCount"
minItems: 2
maxItems: 2
description: |-
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
foundedYear:
type: array
items:
$ref: "#/components/schemas/USCompanyFoundedYear"
minItems: 2
maxItems: 2
description: |-
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
description: Filters used to target US companies (B2B) when building a list.
USCompanyType:
type: string
enum:
- public
- private
- educational
- government
- nonprofit
- public_subsidiary
description: Type of US business by ownership structure.
USConsumerAge:
type: integer
format: int32
minimum: 18
maximum: 80
description: An age, in years, of a US consumer. Between 18 and 80.
USConsumerEducationLevel:
type: string
enum:
- high_school
- college
- grad_school
- vocational_training
description: Highest level of education completed by a US consumer.
USConsumerGender:
type: string
enum:
- male
- female
description: Gender filter for US consumer list builds.
USConsumerHomeValueUSD:
type: integer
format: int32
minimum: 0
maximum: 1000000
description: A home value, in US dollars, of a US consumer. Between 0 and 1,000,000.
USConsumerIncomeUSD:
type: integer
format: int32
minimum: 0
maximum: 200000
description: >-
An annual household income, in US dollars, of a US consumer. Between 0
and
200,000.
USConsumerListFilters:
type: object
properties:
zipCodesAround:
allOf:
- $ref: "#/components/schemas/USZipsAroundFilter"
description: Include all ZIP codes within a given radius of a center ZIP code.
cityStates:
type: array
items:
type: string
description: A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
zipCodes:
type: array
items:
type: string
description: A list of five-digit US ZIP codes to target.
ageRange:
type: array
items:
$ref: "#/components/schemas/USConsumerAge"
minItems: 2
maxItems: 2
description: Inclusive `[min, max]` age range. Values must be between 18 and 80.
incomeRange:
type: array
items:
$ref: "#/components/schemas/USConsumerIncomeUSD"
minItems: 2
maxItems: 2
description: |-
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
gender:
allOf:
- $ref: "#/components/schemas/USConsumerGender"
description: Filter by consumer gender.
educationLevels:
type: array
items:
$ref: "#/components/schemas/USConsumerEducationLevel"
description: Filter by highest level of education completed.
occupations:
type: array
items:
$ref: "#/components/schemas/USConsumerOccupation"
description: Filter by occupation classification.
numChildrenRange:
type: array
items:
$ref: "#/components/schemas/USConsumerNumChildren"
minItems: 2
maxItems: 2
description: >-
Inclusive `[min, max]` number of children in the household. Values
must
be between 0 and 8.
homeValueRange:
type: array
items:
$ref: "#/components/schemas/USConsumerHomeValueUSD"
minItems: 2
maxItems: 2
description: >-
Inclusive `[min, max]` home value range, in US dollars. Values must
be
between 0 and 1,000,000.
description: |-
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
USConsumerNumChildren:
type: integer
format: int32
minimum: 0
maximum: 8
description: A number of children in a US consumer household. Between 0 and 8.
USConsumerOccupation:
type: string
enum:
- professional_technical
- administration_management
- sales_service
- clerical_white_collar
- craftsmen_blue_collar
- student
- homemaker
- retired
- farmer
- military
- religious
- self_employed
- self_employed_professional_technical
- self_employed_administration_management
- self_employed_sales_service
- self_employed_clerical_white_collar
- self_employed_craftsmen_blue_collar
- self_employed_student
- self_employed_homemaker
- self_employed_retired
- self_employed_other
- educator
- financial_professional
- legal_professional
- medical_professional
- other
description: Occupation classification for a US consumer.
USZipsAroundFilter:
type: object
required:
- zipCode
- radiusInMiles
properties:
zipCode:
type: string
description: The five-digit ZIP code at the center of the search circle.
radiusInMiles:
type: number
format: float
minimum: 0.1
maximum: 100
description: The radius in miles around `zipCode` to include. Between 0.1 and 100.
description: >-
A geographic filter that selects all ZIP codes within a given radius of
a
center ZIP code.
User:
type: object
required:
- id
- organization
- pendingInvite
- email
- name
- verifiedEmail
- roles
- apiKeys
properties:
id:
type: string
description: A unique ID prefixed with `user_`.
organization:
type: string
description: A unique ID prefixed with `user_`.
pendingInvite:
type: boolean
description: Indicates if the user has a pending invite.
email:
type: string
description: The email of the user.
name:
type: string
description: The name of the user.
phoneNumber:
type: string
description: The phone number of the user.
lastLoginTime:
type: string
format: date-time
description: The date and time at which the user last logged in.
verifiedEmail:
type: boolean
description: Indicates if the user has a verified email or not.
roles:
type: array
items:
type: string
description: >-
The roles given to the user. Roles can be used to restrict access
for
users.
previousEmails:
type: array
items:
type: string
description: >-
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.
emailPreferences:
allOf:
- $ref: "#/components/schemas/EmailPreferences"
description: A set of preferences for receiving emails.
apiKeys:
type: array
items:
$ref: "#/components/schemas/APIKey"
description: The user's API keys. Contains live and test mode API keys.
description: The user object.
UserWithoutAPIKeys:
type: object
allOf:
- $ref: "#/components/schemas/BaseUser"
description: The user object.
VerificationStatusCount:
type: object
required:
- verifiedCount
- correctedCount
- failedCount
properties:
verifiedCount:
type: integer
format: int32
description: Number of contacts that were verified without changes.
correctedCount:
type: integer
format: int32
description: Number of contacts that were corrected during verification.
failedCount:
type: integer
format: int32
description: Number of contacts that failed verification.
description: Count of contact verification statuses.
Versions:
type: string
enum:
- "1.0"
VirtualMailbox:
type: object
required:
- id
- live
- createdAt
- updatedAt
- object
- capabilities
- status
- countryCode
properties:
id:
type: string
pattern: virtual_mailbox_[a-zA-Z0-9]+
description: A unique ID prefixed with virtual_mailbox_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
object:
type: string
enum:
- virtual_mailbox
description: Always "virtual_mailbox".
capabilities:
allOf:
- $ref: "#/components/schemas/VirtualMailboxCapabilities"
description: The capabilities of the virtual mailbox.
status:
allOf:
- $ref: "#/components/schemas/VirtualMailboxStatus"
description: The status of the virtual mailbox.
countryCode:
allOf:
- $ref: "#/components/schemas/VirtualMailboxSupportedCountry"
description: The country code of the virtual mailbox.
description: The virtual mailbox object.
VirtualMailboxCapabilities:
type: object
required:
- envelopeScans
properties:
envelopeScans:
type: boolean
description: Indicates if the virtual mailbox can produce scans of envelopes.
forwardMailTo:
allOf:
- $ref: "#/components/schemas/Contact"
description: A contact to forward any returned mail to.
description: All of the capabilities a virtual mailbox may have.
VirtualMailboxCreate:
type: object
required:
- countryCode
properties:
capabilities:
type: object
properties:
envelopeScans:
type: boolean
description: If the virtual mailbox should support envelope scans or not.
forwardMailTo:
anyOf:
- $ref: "#/components/schemas/ContactCreate"
- type: string
description: A contact ID or contact object.
required:
- envelopeScans
description: The capabilities the virtual mailbox should support.
countryCode:
allOf:
- $ref: "#/components/schemas/VirtualMailboxSupportedCountry"
description: The country of the virtual mailbox.
VirtualMailboxItem:
type: object
required:
- id
- live
- createdAt
- updatedAt
- object
- virtualMailbox
properties:
id:
type: string
pattern: virtual_mailbox_item_[a-zA-Z0-9]+
description: A unique ID prefixed with virtual_mailbox_item_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
object:
type: string
enum:
- virtual_mailbox_item
description: Always "virtual_mailbox_item".
virtualMailbox:
type: string
description: The ID of the virtual mailbox associated with this item.
fileURL:
type: string
description: A URL of the envelope scan PDF.
matchedLetter:
type: string
description: The ID of the letter this item was matched to.
description: The virtual mailbox item object.
VirtualMailboxItemTestCreate:
type: object
properties:
description:
type: string
description: The description of the item.
metadata:
type: object
additionalProperties: {}
description: The metadata of the item.
matchedLetter:
type: string
description: The ID of a letter to match this test item to.
description: Create body for a test virtual mailbox item.
VirtualMailboxStatus:
type: string
enum:
- active
- pending_assignment
description: The possible statuses of virtual mailboxes.
VirtualMailboxSupportedCountry:
type: string
enum:
- US
description: All of the supported countries for virtual mailboxes.
VisibleTrackers:
anyOf:
- type: string
enum:
- all
- none
- type: array
items:
type: string
description: Controls which Trackers are displayed in the template editor session.
Webhook:
type: object
required:
- object
- url
- enabledEvents
- enabled
properties:
object:
type: string
enum:
- webhook
description: Always `webhook`.
readOnly: true
url:
allOf:
- $ref: "#/components/schemas/WebhookURL"
description: The trigger URL of the webhook. Must be HTTPS.
enabledEvents:
type: array
items:
$ref: "#/components/schemas/WebhookEventType"
description: The list of event types this webhook listens for.
payloadFormat:
allOf:
- $ref: "#/components/schemas/WebhookPayloadFormat"
description: The format in which the event payload is delivered. Defaults to
`jwt`.
default: jwt
enabled:
type: boolean
description: Whether this webhook is enabled. Disabled webhooks are not triggered.
default: true
secret:
allOf:
- $ref: "#/components/schemas/WebhookSecret"
description: >-
The secret used to sign the payload of every event delivered to this
webhook.
You may supply your own secret on create or update; if omitted on
create, one
is generated for you.
allOf:
- type: object
required:
- id
- live
- createdAt
- updatedAt
properties:
id:
type: string
pattern: webhook_[a-zA-Z0-9]+
description: A unique ID prefixed with webhook_
readOnly: true
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
live:
type: boolean
description: "`true` if this is a live mode resource else `false`."
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this resource was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this resource was last updated.
readOnly: true
WebhookCreate:
type: object
required:
- url
- enabledEvents
properties:
url:
allOf:
- $ref: "#/components/schemas/WebhookURL"
description: The trigger URL of the webhook. Must be HTTPS.
enabledEvents:
type: array
items:
$ref: "#/components/schemas/WebhookEventType"
description: The list of event types this webhook listens for.
payloadFormat:
allOf:
- $ref: "#/components/schemas/WebhookPayloadFormat"
description: The format in which the event payload is delivered. Defaults to
`jwt`.
default: jwt
secret:
allOf:
- $ref: "#/components/schemas/WebhookSecret"
description: >-
The secret used to sign the payload of every event delivered to this
webhook.
You may supply your own secret on create or update; if omitted on
create, one
is generated for you.
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
WebhookEventType:
type: string
enum:
- letter.created
- letter.updated
- postcard.created
- postcard.updated
- self_mailer.created
- self_mailer.updated
- cheque.created
- cheque.updated
- box.created
- box.updated
- snap_pack.created
- snap_pack.updated
- return_envelope_order.created
- return_envelope_order.updated
- tracker.visited
- campaign.created
- campaign.updated
- virtual_mailbox_item.created
- postal_statement.created
- document.created
- document.updated
description: The type of event that a Webhook can listen for and that an Event
represents.
WebhookInvocation:
type: object
required:
- id
- object
- webhook
- event
- type
- statusCode
- createdAt
- updatedAt
properties:
id:
type: string
pattern: webhook_invocation_[a-zA-Z0-9]+
description: A unique ID prefixed with `webhook_invocation_`.
readOnly: true
object:
type: string
enum:
- webhook_invocation
description: Always `webhook_invocation`.
readOnly: true
webhook:
type: string
pattern: webhook_[a-zA-Z0-9]+
description: The ID of the webhook that was invoked.
readOnly: true
event:
type: string
pattern: event_[a-zA-Z0-9]+
description: The ID of the event that was delivered in this invocation.
readOnly: true
orderID:
type: string
description: The ID of the order associated with this invocation, if the event
was order-related.
readOnly: true
type:
allOf:
- $ref: "#/components/schemas/WebhookEventType"
description: The type of event that triggered this invocation.
readOnly: true
statusCode:
type: integer
format: int32
description: The HTTP status code returned by your endpoint for this invocation.
readOnly: true
createdAt:
type: string
format: date-time
description: The UTC time at which this invocation was created.
readOnly: true
updatedAt:
type: string
format: date-time
description: The UTC time at which this invocation was last updated.
readOnly: true
WebhookInvocationList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/WebhookInvocation"
WebhookList:
type: object
required:
- object
- totalCount
- skip
- limit
- data
properties:
object:
type: string
enum:
- list
totalCount:
type: integer
format: int32
skip:
type: integer
format: int32
limit:
type: integer
format: int32
data:
type: array
items:
$ref: "#/components/schemas/Webhook"
WebhookPayloadFormat:
type: string
enum:
- jwt
- json
description: The format in which a Webhook's event payload is delivered.
WebhookSecret:
type: string
minLength: 20
pattern: ^[^\s]+$
description: A webhook signing secret with at least 20 non-whitespace characters.
WebhookURL:
type: string
format: uri
pattern: ^https://
description: An HTTPS URL that PostGrid can invoke for webhook deliveries.
WebhookUpdate:
type: object
properties:
description:
type: string
description: An optional string describing this resource. Will be visible in the
API and the dashboard.
metadata:
type: object
additionalProperties: {}
description: See the section on Metadata.
url:
allOf:
- $ref: "#/components/schemas/WebhookURL"
description: The trigger URL of the webhook. Must be HTTPS.
enabledEvents:
type: array
items:
$ref: "#/components/schemas/WebhookEventType"
description: The list of event types this webhook listens for.
payloadFormat:
allOf:
- $ref: "#/components/schemas/WebhookPayloadFormat"
description: The format in which the event payload is delivered. Defaults to
`jwt`.
enabled:
type: boolean
description: Whether this webhook is enabled. Disabled webhooks are not triggered.
secret:
allOf:
- $ref: "#/components/schemas/WebhookSecret"
description: The secret used to sign the payload of every event delivered to
this webhook.
securitySchemes:
PrintMailApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
servers:
- url: https://api.postgrid.com
description: Primary endpoint for all of PostGrid's APIs
variables: {}