Skip to main content
POST
/
letters
Create letter
curl --request POST \
  --url https://api.posta.co/letters \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "sender": {
    "address": {
      "addressLine1": "1900 Reston Metro Plz",
      "urbanization": "<string>",
      "addressLine2": "Ste 600",
      "city": "Reston",
      "state": "VA",
      "zipCode": "20190",
      "plus4Code": "5952"
    },
    "individual": {
      "fullName": "TODO",
      "prefix": "TODO",
      "firstName": "TODO",
      "middleName": "TODO",
      "lastName": "TODO",
      "postfix": "TODO",
      "title": "TODO"
    },
    "organization": "Veezla, Inc."
  },
  "recipient": {
    "address": {
      "addressLine1": "1900 Reston Metro Plz",
      "urbanization": "<string>",
      "addressLine2": "Ste 600",
      "city": "Reston",
      "state": "VA",
      "zipCode": "20190",
      "plus4Code": "5952"
    },
    "nonAddressData": "<string>",
    "individual": {
      "fullName": "TODO",
      "prefix": "TODO",
      "firstName": "TODO",
      "middleName": "TODO",
      "lastName": "TODO",
      "postfix": "TODO",
      "title": "TODO"
    },
    "organization": "Posta Customer, Inc."
  },
  "content": {
    "type": "asset",
    "assetId": "ast_1234567890abcdef"
  },
  "useType": "marketing"
}
'
{
  "id": "ltr_9a32a8b5a96c880c",
  "status": "queued",
  "sender": {
    "address": {
      "addressLine1": "1900 Reston Metro Plz",
      "addressLine2": "Ste 600",
      "lastLine": "Reston, VA 20194-5952"
    },
    "individual": {
      "fullName": "TODO",
      "prefix": "TODO",
      "firstName": "TODO",
      "middleName": "TODO",
      "lastName": "TODO",
      "postfix": "TODO",
      "title": "TODO"
    },
    "organization": "Veezla, Inc.",
    "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": {
    "address": {
      "addressLine1": "1900 Reston Metro Plz",
      "addressLine2": "Ste 600",
      "lastLine": "Reston, VA 20194-5952"
    },
    "nonAddressData": "<string>",
    "individual": {
      "fullName": "TODO",
      "prefix": "TODO",
      "firstName": "TODO",
      "middleName": "TODO",
      "lastName": "TODO",
      "postfix": "TODO",
      "title": "TODO"
    },
    "organization": "Posta Customer, Inc.",
    "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"
  },
  "useType": "marketing",
  "events": [
    {
      "id": "evt_1234567890abcdef",
      "createdAt": "2023-11-07T05:31:56Z",
      "modifiedAt": "2023-11-07T05:31:56Z",
      "type": "tracking",
      "status": "inTransit",
      "trackingEventDetails": {
        "notes": "TODO",
        "facility": "TODO",
        "facilityType": "TODO",
        "facilityZip": "TODO",
        "additionalData": {}
      },
      "timestamp": "2023-11-07T05:31:56Z",
      "description": "TODO",
      "operationCode": "TODO",
      "actionRequired": true,
      "location": "TODO"
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "modifiedAt": "2023-11-07T05:31:56Z",
  "externalId": "0013i00002YyVvSAAV",
  "sendDate": "2023-12-25",
  "description": "Compliance notice",
  "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"
    ]
  },
  "issueMessage": "Recipient address could not be validated",
  "metadata": [
    {
      "key": "salesforceId",
      "value": "0013i00002YyVvSAAV"
    }
  ]
}

Authorizations

​
X-Api-Key
string
header
required

Headers

​
Idempotency-Key
string

Unique idempotency key for each request (e.g., V4 UUID).

Body

application/json

A letter.

​
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.

​
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.

​
content
object
required

Content of the letter.

​
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"

​
externalId
string

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

Maximum string length: 99999
Example:

"0013i00002YyVvSAAV"

​
sendDate
string<date>

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

​
description
string

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

Maximum string length: 99999
Example:

"Compliance notice"

​
variables
object[]

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

Maximum array length: 128
​
options
object

Customization options for letter production and delivery, including:

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

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

​
metadata
object[] | null

A key-value store for custom metadata.

Limitations:

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

Response

The request has succeeded and a new resource has been created as a result

A letter.

​
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"

​
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"

​
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.

​
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.

​
content
object
required

Content of the letter.

​
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"

​
events
object[]
required

Array of events in the letter's lifecycle.

Maximum array length: 999

Represents a lifecycle event for a letter.

​
createdAt
string<date-time>
required

The timestamp the resource was created at (UTC).

​
modifiedAt
string<date-time>
required

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

​
externalId
string

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

Maximum string length: 99999
Example:

"0013i00002YyVvSAAV"

​
sendDate
string<date>

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

​
description
string

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

Maximum string length: 99999
Example:

"Compliance notice"

​
url
string

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

Maximum string length: 99999
Example:

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

​
variables
object[]

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

Maximum array length: 128
​
options
object

Customization options for letter production and delivery, including:

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

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

​
issueMessage
string

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

Maximum string length: 99999
Example:

"Recipient address could not be validated"

​
metadata
object[] | null

A key-value store for custom metadata.

Limitations:

  1. Up to 20 metadata key-value pairs
  2. Key must be no more than 64 characters
  3. Value must be no more than 512 characters
Last modified on December 23, 2025