List letters

GET

letters

curl --request GET \
  --url https://api.posta.co/letters \
  --header 'X-Api-Key: <api-key>'

{
  "items": [
    {
      "id": "ltr_9a32a8b5a96c880c",
      "status": "queued",
      "externalId": "0013i00002YyVvSAAV",
      "sendDate": "2023-12-25",
      "description": "Compliance notice",
      "sender": {
        "individual": {
          "fullName": "TODO",
          "prefix": "TODO",
          "firstName": "TODO",
          "middleName": "TODO",
          "lastName": "TODO",
          "postfix": "TODO",
          "title": "TODO"
        },
        "organization": "Veezla, Inc.",
        "address": {
          "addressLine1": "1900 Reston Metro Plz",
          "addressLine2": "Ste 600",
          "lastLine": "Reston, VA 20194-5952"
        },
        "addressComponents": {
          "cassType": "none",
          "urbanization": "TODO",
          "city": "TODO",
          "state": "TODO",
          "zipCode": "TODO",
          "plus4Code": "TODO"
        },
        "addressAnalysis": {
          "dpvMatchCode": "TODO",
          "dpvFootnotes": [
            "TODO"
          ],
          "dpvCmra": "TODO",
          "dpvVacant": "TODO",
          "dpvNoStat": "TODO",
          "dpvActive": "TODO",
          "dpvInactiveReason": "TODO",
          "dpvThrowback": "TODO",
          "dpvNonDeliveryDayIndicator": "TODO",
          "dpvNonDeliveryDayValues": "TODO",
          "dpvNoSecureLocation": "TODO",
          "dpvDoorNotAccessible": "TODO",
          "lacslinkCode": "TODO",
          "lacslinkIndicator": "TODO",
          "suitelinkIndicator": "TODO",
          "ewsIndicator": true
        },
        "addressCorrections": [
          {
            "name": "TODO",
            "input": "TODO",
            "corrected": "TODO"
          }
        ],
        "addressMetadata": {
          "recordType": "TODO",
          "addressType": "TODO",
          "zipCodeType": "TODO",
          "county": "TODO",
          "countyFips": "TODO",
          "carrierRoute": "TODO",
          "carrierRouteType": "TODO",
          "congressionalDistrict": "TODO",
          "defaultBuildingAddress": true,
          "elotSequence": "TODO",
          "elotSort": "TODO",
          "latitude": 0,
          "longitude": 0,
          "precision": "TODO",
          "uspsFinanceNumber": "TODO",
          "timeZone": "TODO"
        }
      },
      "recipient": {
        "nonAddressData": "<string>",
        "individual": {
          "fullName": "TODO",
          "prefix": "TODO",
          "firstName": "TODO",
          "middleName": "TODO",
          "lastName": "TODO",
          "postfix": "TODO",
          "title": "TODO"
        },
        "organization": "Posta Customer, Inc.",
        "address": {
          "addressLine1": "1900 Reston Metro Plz",
          "addressLine2": "Ste 600",
          "lastLine": "Reston, VA 20194-5952"
        },
        "addressComponents": {
          "cassType": "none",
          "urbanization": "TODO",
          "city": "TODO",
          "state": "TODO",
          "zipCode": "TODO",
          "plus4Code": "TODO"
        },
        "addressAnalysis": {
          "dpvMatchCode": "TODO",
          "dpvFootnotes": [
            "TODO"
          ],
          "dpvCmra": "TODO",
          "dpvVacant": "TODO",
          "dpvNoStat": "TODO",
          "dpvActive": "TODO",
          "dpvInactiveReason": "TODO",
          "dpvThrowback": "TODO",
          "dpvNonDeliveryDayIndicator": "TODO",
          "dpvNonDeliveryDayValues": "TODO",
          "dpvNoSecureLocation": "TODO",
          "dpvDoorNotAccessible": "TODO",
          "lacslinkCode": "TODO",
          "lacslinkIndicator": "TODO",
          "suitelinkIndicator": "TODO",
          "ewsIndicator": true
        },
        "addressCorrections": [
          {
            "name": "TODO",
            "input": "TODO",
            "corrected": "TODO"
          }
        ],
        "addressMetadata": {
          "recordType": "TODO",
          "addressType": "TODO",
          "zipCodeType": "TODO",
          "county": "TODO",
          "countyFips": "TODO",
          "carrierRoute": "TODO",
          "carrierRouteType": "TODO",
          "congressionalDistrict": "TODO",
          "defaultBuildingAddress": true,
          "elotSequence": "TODO",
          "elotSort": "TODO",
          "latitude": 0,
          "longitude": 0,
          "precision": "TODO",
          "uspsFinanceNumber": "TODO",
          "timeZone": "TODO"
        }
      },
      "content": {
        "type": "asset",
        "assetId": "ast_1234567890abcdef",
        "assetVersionId": "astv_1234567890abcdef"
      },
      "url": "https://api.posta.co/letters/ltr_9a32a8b5a96c880c/download",
      "variables": [
        {
          "name": "customerName",
          "value": "John Doe"
        }
      ],
      "options": {
        "print": {
          "color": true
        },
        "mail": {
          "service": "firstClass",
          "extraServices": [
            "acs"
          ]
        },
        "variableHandling": {
          "validationScope": "asset"
        },
        "addressProcessing": {
          "cassSender": {
            "type": "basic",
            "casing": "proper"
          },
          "cassRecipient": {
            "type": "basic",
            "casing": "proper"
          },
          "ncoaRecipient": "newAddress"
        },
        "deliverabilityThreshold": "normal",
        "deliverabilityValues": [
          "deliverable"
        ]
      },
      "useType": "marketing",
      "events": [
        {
          "id": "evt_1234567890abcdef",
          "timestamp": "2023-11-07T05:31:56Z",
          "createdAt": "2023-11-07T05:31:56Z",
          "modifiedAt": "2023-11-07T05:31:56Z",
          "type": "tracking",
          "status": "inTransit",
          "description": "TODO",
          "operationCode": "TODO",
          "actionRequired": true,
          "trackingEventDetails": {
            "notes": "TODO",
            "facility": "TODO",
            "facilityType": "TODO",
            "facilityZip": "TODO",
            "additionalData": {}
          },
          "location": "TODO"
        }
      ],
      "issueMessage": "Recipient address could not be validated",
      "metadata": [
        {
          "key": "salesforceId",
          "value": "0013i00002YyVvSAAV"
        }
      ],
      "createdAt": "2023-11-07T05:31:56Z",
      "modifiedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "nextToken": "<string>"
}

Authorizations

X-Api-Key

string

header

required

Query Parameters

includeCass

boolean

default:false

Include CASS processing details in the response.

pageSize

integer

The number of items to return per page. The maximum pageSize is 100 items.

nextToken

string

A cursor for the next page of results.

Response

200

application/json

The request has succeeded.

items

object[]

required

Array of items for the current page.

A letter.

items.id

string

required

A unique identifier for the letter, prefixed with ltr_. Use this ID to retrieve, update, or delete the letter.

Required string length: 1 - 99999

Example:

"ltr_9a32a8b5a96c880c"

items.status

enum<string>

required

Represents the current status of a letter in the mailing process:

queued: Awaiting processing
ready: Processed and ready for printing
inProduction: Being printed and prepared for mailing
mailed: Handed off to postal service for delivery
issue: Problem that needs addressing
canceled: Letter will not be mailed

Available options:

queued,

ready,

inProduction,

mailed,

issue,

canceled

Example:

"queued"

items.sender

object

required

An object containing the sender's information for the letter. It must include:

Either an individual object, an organization string, or both.

If individual is provided, it can contain either a fullName string or name components (at minimum firstName and lastName).
If only name components are provided, they will be used in the order specified in our API for addressing.
If both fullName and name components are provided, fullName will be used for addressing.

An address object with the sender's complete address details.

This information is used to populate the return address on the letter. Ensure all provided details are accurate to facilitate any potential return mail handling.

items.sender.address

object

required

Address information for sender or recipient.

items.sender.individual

object

Name of the individual, if applicable. Must be 40 characters or less.

items.sender.organization

string

Name of the organization, if applicable. Must be 40 characters or less.

Maximum length: 99999

Example:

"Veezla, Inc."

items.sender.addressComponents

object

Parsed components of the sender's address.

items.sender.addressAnalysis

object

Analysis of the sender's address.

items.sender.addressAnalysis.dpvMatchCode

string

DPV (Delivery Point Validation) match code

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvFootnotes

string[]

DPV footnotes

Example:

["TODO"]

items.sender.addressAnalysis.dpvCmra

string

DPV CMRA indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvVacant

string

DPV vacant indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvNoStat

string

DPV no-stat indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvActive

string

DPV active indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvInactiveReason

string

DPV inactive reason

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvThrowback

string

DPV throwback indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvNonDeliveryDayIndicator

string

DPV non-delivery day indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvNonDeliveryDayValues

string

DPV non-delivery day values

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvNoSecureLocation

string

DPV no secure location indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.dpvDoorNotAccessible

string

DPV door not accessible indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.lacslinkCode

string

LACSLink code

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.lacslinkIndicator

string

LACSLink indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.suitelinkIndicator

string

SuiteLink indicator

Maximum length: 99999

Example:

"TODO"

items.sender.addressAnalysis.ewsIndicator

boolean

Early Warning System indicator

items.sender.addressCorrections

object[]

Corrections made to the sender's address.

Represents a correction made to an address component

items.sender.addressMetadata

object

Metadata about the sender's address.

items.recipient

object

required

Recipient information for the letter. Either individual or organization is required; both can be provided. For accurate NCOA processing, provide name components when available.

items.recipient.address

object

required

Address information for sender or recipient.

items.recipient.nonAddressData

string

Additional non-address data for the recipient. It will be printed as the first line of the recipient information. Must be 40 characters or less.s Eg. Private & Confidential.

Maximum length: 99999

items.recipient.individual

object

Name of the individual, if applicable. Must be 40 characters or less.

items.recipient.organization

string

Name of the organization, if applicable. Must be 40 characters or less.

Maximum length: 99999

Example:

"Posta Customer, Inc."

items.recipient.addressComponents

object

Parsed components of the recipient's address.

items.recipient.addressAnalysis

object

Analysis of the recipient's address.

items.recipient.addressAnalysis.dpvMatchCode

string

DPV (Delivery Point Validation) match code

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvFootnotes

string[]

DPV footnotes

Example:

["TODO"]

items.recipient.addressAnalysis.dpvCmra

string

DPV CMRA indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvVacant

string

DPV vacant indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvNoStat

string

DPV no-stat indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvActive

string

DPV active indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvInactiveReason

string

DPV inactive reason

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvThrowback

string

DPV throwback indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvNonDeliveryDayIndicator

string

DPV non-delivery day indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvNonDeliveryDayValues

string

DPV non-delivery day values

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvNoSecureLocation

string

DPV no secure location indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.dpvDoorNotAccessible

string

DPV door not accessible indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.lacslinkCode

string

LACSLink code

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.lacslinkIndicator

string

LACSLink indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.suitelinkIndicator

string

SuiteLink indicator

Maximum length: 99999

Example:

"TODO"

items.recipient.addressAnalysis.ewsIndicator

boolean

Early Warning System indicator

items.recipient.addressCorrections

object[]

Corrections made to the recipient's address.

Represents a correction made to an address component

items.recipient.addressMetadata

object

Metadata about the recipient's address.

items.content

object

required

Content of the letter.

items.useType

enum<string>

required

Indicates the letter's purpose: 'marketing' or 'transactional'. Affects eligibility for USPS promotions and sales tax compliance.

Available options:

marketing,

transactional

Example:

"marketing"

items.events

object[]

required

Array of events in the letter's lifecycle.

Represents a lifecycle event for a letter.

items.createdAt

string

required

The timestamp the resource was created at (UTC).

items.modifiedAt

string

required

The timestamp the resource was last modified at (UTC).

items.externalId

string

Optional client-defined identifier for referencing this letter in external systems. Not used by Posta for processing.

Maximum length: 99999

Example:

"0013i00002YyVvSAAV"

items.sendDate

string

Specifies the Send Date in ISO 8601 format (YYYY-MM-DD). Time portion, if provided, is ignored.

If omitted:

SLA begins after the daily cutoff and we auto-assign a date based on our SLA:
Before cutoff: Earliest production date (e.g., same day if sent 9 am Tuesday).
After cutoff: Next production date (e.g., next day if sent 11 am Tuesday).
Non-production day: Next production date.

If specified:

Must be between current date and 180 days in future.
If specified date is a production day, value remains as-is.
If not a production day, next production day is assigned.

Daily cutoff: 10 am ET on production days (Monday - Friday, exluding national holidays)

Note: All letters are cancelable on or before the Send Date's daily cutoff.

Example: 2023-08-15

items.description

string

Optional description for internal reference. Does not affect processing or delievery.

Maximum length: 99999

Example:

"Compliance notice"

items.url

string

Temporary URL to download the rendered letter PDF. Expires after a set period.

Maximum length: 99999

Example:

"https://api.posta.co/letters/ltr_9a32a8b5a96c880c/download"

items.variables

object[]

Key-value pairs for personalizing letter content when using handlebars in HTML content.

Represents a variable with a name and optional value for dynamic personalization.

items.options

object

Customization options for letter production and delivery, including:

Printing preferences (e.g., color, simplex/duplex)
Mailing preferences (e.g., mail class, extra services)
Data processing preferences (e.g., CASS, NCOA)
Other preferences

Defaults apply if not specified. See Option documentation for details. Note: Some options may affect pricing or production time.

items.options.print

object

Print options for the letter.

items.options.mail

object

Mail options for the letter.

items.options.mail.service

enum<string>

default:firstClass

Mailing service to use for the letter. We currently support firstClass only.

Available options:

firstClass

Example:

"firstClass"

items.options.mail.extraServices

enum<string>[]

Additional services for firstClass mail. We will offer support for ACS and Secure Destruction soon, currently no extra services available.

Additional mailing services that can be applied to letters.

Available options:

acs,

secureDestruction

Example:

["acs"]

items.options.variableHandling

object

Variable handling options for the letter.

items.options.addressProcessing

object

Address processing options for the letter.

items.options.deliverabilityThreshold

enum<string>

default:normal

Deliverability threshold for the letter.

Available options:

none,

normal,

strict

Example:

"normal"

items.options.deliverabilityValues

enum<string>[]

You can speficy explicit deliverability values as a threashold insteead of our presets. The letter will only be send when the recipient's address' deliverability is among the specified values.

The deliverability status of an address

Available options:

deliverable,

deliverableUnnecessaryUnit,

deliverableIncorrectUnit,

deliverableMissingUnit,

undeliverable

items.issueMessage

string

Human-readable description of any issues encountered with the letter.

Maximum length: 99999

Example:

"Recipient address could not be validated"

items.metadata

object[] | null

A key-value store for custom metadata.

Limitations:

Up to 20 metadata key-value pairs
Key must be no more than 64 characters
Value must be no more than 512 characters

nextToken

string

A cursor for the next page of results.

Letter object Create letter

curl --request GET \
  --url https://api.posta.co/letters \
  --header 'X-Api-Key: <api-key>'

{
  "items": [
    {
      "id": "ltr_9a32a8b5a96c880c",
      "status": "queued",
      "externalId": "0013i00002YyVvSAAV",
      "sendDate": "2023-12-25",
      "description": "Compliance notice",
      "sender": {
        "individual": {
          "fullName": "TODO",
          "prefix": "TODO",
          "firstName": "TODO",
          "middleName": "TODO",
          "lastName": "TODO",
          "postfix": "TODO",
          "title": "TODO"
        },
        "organization": "Veezla, Inc.",
        "address": {
          "addressLine1": "1900 Reston Metro Plz",
          "addressLine2": "Ste 600",
          "lastLine": "Reston, VA 20194-5952"
        },
        "addressComponents": {
          "cassType": "none",
          "urbanization": "TODO",
          "city": "TODO",
          "state": "TODO",
          "zipCode": "TODO",
          "plus4Code": "TODO"
        },
        "addressAnalysis": {
          "dpvMatchCode": "TODO",
          "dpvFootnotes": [
            "TODO"
          ],
          "dpvCmra": "TODO",
          "dpvVacant": "TODO",
          "dpvNoStat": "TODO",
          "dpvActive": "TODO",
          "dpvInactiveReason": "TODO",
          "dpvThrowback": "TODO",
          "dpvNonDeliveryDayIndicator": "TODO",
          "dpvNonDeliveryDayValues": "TODO",
          "dpvNoSecureLocation": "TODO",
          "dpvDoorNotAccessible": "TODO",
          "lacslinkCode": "TODO",
          "lacslinkIndicator": "TODO",
          "suitelinkIndicator": "TODO",
          "ewsIndicator": true
        },
        "addressCorrections": [
          {
            "name": "TODO",
            "input": "TODO",
            "corrected": "TODO"
          }
        ],
        "addressMetadata": {
          "recordType": "TODO",
          "addressType": "TODO",
          "zipCodeType": "TODO",
          "county": "TODO",
          "countyFips": "TODO",
          "carrierRoute": "TODO",
          "carrierRouteType": "TODO",
          "congressionalDistrict": "TODO",
          "defaultBuildingAddress": true,
          "elotSequence": "TODO",
          "elotSort": "TODO",
          "latitude": 0,
          "longitude": 0,
          "precision": "TODO",
          "uspsFinanceNumber": "TODO",
          "timeZone": "TODO"
        }
      },
      "recipient": {
        "nonAddressData": "<string>",
        "individual": {
          "fullName": "TODO",
          "prefix": "TODO",
          "firstName": "TODO",
          "middleName": "TODO",
          "lastName": "TODO",
          "postfix": "TODO",
          "title": "TODO"
        },
        "organization": "Posta Customer, Inc.",
        "address": {
          "addressLine1": "1900 Reston Metro Plz",
          "addressLine2": "Ste 600",
          "lastLine": "Reston, VA 20194-5952"
        },
        "addressComponents": {
          "cassType": "none",
          "urbanization": "TODO",
          "city": "TODO",
          "state": "TODO",
          "zipCode": "TODO",
          "plus4Code": "TODO"
        },
        "addressAnalysis": {
          "dpvMatchCode": "TODO",
          "dpvFootnotes": [
            "TODO"
          ],
          "dpvCmra": "TODO",
          "dpvVacant": "TODO",
          "dpvNoStat": "TODO",
          "dpvActive": "TODO",
          "dpvInactiveReason": "TODO",
          "dpvThrowback": "TODO",
          "dpvNonDeliveryDayIndicator": "TODO",
          "dpvNonDeliveryDayValues": "TODO",
          "dpvNoSecureLocation": "TODO",
          "dpvDoorNotAccessible": "TODO",
          "lacslinkCode": "TODO",
          "lacslinkIndicator": "TODO",
          "suitelinkIndicator": "TODO",
          "ewsIndicator": true
        },
        "addressCorrections": [
          {
            "name": "TODO",
            "input": "TODO",
            "corrected": "TODO"
          }
        ],
        "addressMetadata": {
          "recordType": "TODO",
          "addressType": "TODO",
          "zipCodeType": "TODO",
          "county": "TODO",
          "countyFips": "TODO",
          "carrierRoute": "TODO",
          "carrierRouteType": "TODO",
          "congressionalDistrict": "TODO",
          "defaultBuildingAddress": true,
          "elotSequence": "TODO",
          "elotSort": "TODO",
          "latitude": 0,
          "longitude": 0,
          "precision": "TODO",
          "uspsFinanceNumber": "TODO",
          "timeZone": "TODO"
        }
      },
      "content": {
        "type": "asset",
        "assetId": "ast_1234567890abcdef",
        "assetVersionId": "astv_1234567890abcdef"
      },
      "url": "https://api.posta.co/letters/ltr_9a32a8b5a96c880c/download",
      "variables": [
        {
          "name": "customerName",
          "value": "John Doe"
        }
      ],
      "options": {
        "print": {
          "color": true
        },
        "mail": {
          "service": "firstClass",
          "extraServices": [
            "acs"
          ]
        },
        "variableHandling": {
          "validationScope": "asset"
        },
        "addressProcessing": {
          "cassSender": {
            "type": "basic",
            "casing": "proper"
          },
          "cassRecipient": {
            "type": "basic",
            "casing": "proper"
          },
          "ncoaRecipient": "newAddress"
        },
        "deliverabilityThreshold": "normal",
        "deliverabilityValues": [
          "deliverable"
        ]
      },
      "useType": "marketing",
      "events": [
        {
          "id": "evt_1234567890abcdef",
          "timestamp": "2023-11-07T05:31:56Z",
          "createdAt": "2023-11-07T05:31:56Z",
          "modifiedAt": "2023-11-07T05:31:56Z",
          "type": "tracking",
          "status": "inTransit",
          "description": "TODO",
          "operationCode": "TODO",
          "actionRequired": true,
          "trackingEventDetails": {
            "notes": "TODO",
            "facility": "TODO",
            "facilityType": "TODO",
            "facilityZip": "TODO",
            "additionalData": {}
          },
          "location": "TODO"
        }
      ],
      "issueMessage": "Recipient address could not be validated",
      "metadata": [
        {
          "key": "salesforceId",
          "value": "0013i00002YyVvSAAV"
        }
      ],
      "createdAt": "2023-11-07T05:31:56Z",
      "modifiedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "nextToken": "<string>"
}

Getting started

Assets

Postal

Authorizations

Query Parameters

Response