API Documentation

Using the uploadletters.com enterprise API, you can send First-Class Mail®, Certified Mail® and Priority Mail® letters easily and instantly.
This document page is intended as a guide for developers who would like to integrate their web and mobile applications.

    Main Object: Batch

  • The core object in this API is a "batch." A new batch can be created using the POST /batches endpoint. Once created, the batch can be modified by referencing its unique batchId.

    • Available Batch Types (batch_type)

  • letter: This type of batch processes letters only
  • letter_and_check: This batch type processes both letters and checks together.
  • check: This type processes checks only.

    • Available Batch Options

    When creating or updating a batch through the API, the following optional parameters can be included to configure specific mailing services.

  • Same Day Mailing (same_day_mailing)
  • Certificate of Mailing (certificate_of_mailing) — Only available for First-Class (FC) service type
  • Restricted Delivery (restricted_delivery) — Only available for Certified Mail (CM) and Certified Mail with RRE (CM RRE) service types
  • Note:
  • All parameters accept boolean values (true or false).
  • All parameters should be added to a batch level.
  • These options are optional. If enabled, the selected settings apply to all recipients within the same batch.
  • Invalid combinations (e.g., restricted_delivery with FC service type) will result in a validation error.

    • Available USPS® Service Types (service_type)

  • First-Class Mail® ( fc )
  • Certified Mail® (cm)
  • Certified Mail® with Return Receipt Electronic® (cm-rre)
  • Priority Mail® (pm)
  • Priority Mail Box® (pm-box)

    • Available Envelope Sizes (envelope_type)

  • #10 Envelope: (10)
  • 9 x 12 Envelope: (9x12)
  • Pressure Seal Envelope: (ps)
    Note: Pressure Seal envelope should be user only with First-Class Mail® and support only batch-type: “check”
  • Note: For Priority Mail®, the envelope size is not required, as all mail will be sent using a Flat Rate 12.5 x 9.5 envelope.

    • Available Affidavit Mailing Options (affidavit_option)

  • AOM Signature Only (batch level): (sb)
  • AOM Signature Only (letter level): (sl)
  • AOM Notarized (batch level): (nb)
  • AOM Notarized (letter level): (nl)
  • Note: Affidavit mailing options are optional. If selected, the chosen option must be the same for all recipients within a single batch.

    • Available Return Envelope Options (return_envelope_type)

  • Standard Return Envelope: (no prepaid postage, no preprinted address) — (9npna)
  • Prepaid Envelope: (prepaid postage, no preprinted address) — (9pna)
  • Prepaid & Preaddressed Envelope: (prepaid postage, preprinted addresses) — (9pa)
  • Note: Return Envelope options are optional and can vary for each recipient within a batch.

    • File and Recipient Mapping

  • Letters and recipients are linked by pdf_name in the pdf_file_config. Ensure that all file names are unique.

    • Processing a Batch

  • To initiate processing of a configured batch, use the POST /batches/{batchId}/fulfil endpoint.

    • API Key

  • You can generate your API key from your account settings by visiting https://uploadletters.com.
Endpoints:

POST https://api.uploadletters.com/batches

PATCH https://api.uploadletters.com/batches/{batchId}/recipients

GET https://api.uploadletters.com/batches/{batchId}/recipients

PATCH https://api.uploadletters.com/batches/{batchId}/letters

PUT https://api.uploadletters.com/batches/{batchId}/fulfill

GET https://api.uploadletters.com/batches

GET https://api.uploadletters.com/batches/{batchId}/letters