Certified Mail Workflows

Certified-mail shipments use the same public shipment API as every other Corvo shipment. You enable the USPS-specific workflow with shipping options on draft creation.

Relevant request fields

• shipping_options.certified_mail requests USPS Certified Mail.
• shipping_options.return_receipt requests USPS Return Receipt service and requires certified_mail=true. Carrier-native receipt artifact availability still depends on the carrier data returned for that shipment.
• shipping_options.carrier can be set to USPS if you want to filter quotes to USPS-only results.

const response = await fetch("https://corvo.to/api/v1/shipments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CORVO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    document_key: "documents/org-id/notice.pdf",
    to_address: {
      name: "Jordan Reed",
      street1: "123 Main St",
      city: "Austin",
      state: "TX",
      zip: "78701",
    },
    print_options: { color: false, duplex: false },
    shipping_options: {
      carrier: "USPS",
      certified_mail: true,
      return_receipt: true,
    },
  }),
});

Detail fields to watch

Certified-mail shipments surface the same core shipment fields as every other shipment, plus explicit mailing-record state that matters to USPS evidence workflows.

• usps_accepted_at when USPS acceptance is recorded.
• mailing_records for acceptance, delivery, return-receipt, and retention state.
• artifacts for downloadable summary, bundle, SCAN form, return-receipt artifact when available, and other retained files. Artifact and return-receipt states can become expired when evidence retention elapses.
• delivered_at when the shipment is delivered.
• signer_name when signer data is available.

Return-receipt state semantics

• requested means USPS Return Receipt service was purchased but no delivery or native artifact has been recorded yet.
• delivery_recorded means delivery is recorded and Corvo is still checking retained carrier payloads for a native return-receipt artifact.
• artifact_available means Corvo retained a carrier-native return-receipt PDF and exposes it through the artifact list.
• unavailable means the carrier-native artifact did not materialize for the shipment, including clear final nondelivery outcomes or 30 days after delivery without a native artifact source.
• expired means evidence retention elapsed. The state remains visible in detail responses, but download URLs are omitted.

{
  "data": {
    "shipping_options": {
      "delivery_confirmation": null,
      "certified_mail": true,
      "return_receipt": true
    },
    "tracking_number": "9405511899223033005084",
    "usps_accepted_at": "2026-03-10T18:04:11.000Z",
    "delivered_at": "2026-03-12T15:33:42.000Z",
    "signer_name": "J REED",
    "mailing_records": {
      "acceptance": {
        "requested": true,
        "manifested": true,
        "accepted_at": "2026-03-10T18:04:11.000Z",
        "source": "carrier_event",
        "scan_form_available": true
      },
      "return_receipt": {
        "requested": true,
        "status": "artifact_available",
        "artifact_id": "34cbbe0e-3f1f-4fe9-a4fc-bf9d8d7908fa",
        "available_at": "2026-03-18T14:05:02.000Z"
      }
    },
    "artifacts": [
      {
        "id": "mailing-record-summary",
        "kind": "mailing_record_summary_pdf",
        "provenance": "corvo_generated",
        "status": "available",
        "download_url": "/api/v1/shipments/f47ac10b-58cc-4372-a567-0e02b2c3d479/proof"
      },
      {
        "id": "34cbbe0e-3f1f-4fe9-a4fc-bf9d8d7908fa",
        "kind": "carrier_return_receipt_pdf",
        "provenance": "carrier_native",
        "status": "available",
        "download_url": "/api/v1/shipments/f47ac10b-58cc-4372-a567-0e02b2c3d479/artifacts/34cbbe0e-3f1f-4fe9-a4fc-bf9d8d7908fa"
      }
    ]
  }
}

Proof retrieval

Use the mailing-record endpoints to list retained artifacts, download a Corvo-generated mailing-record summary, or export an evidence bundle once the shipment has a tracking number. If the evidence retention window has elapsed, these download routes return 410 EVIDENCE_EXPIRED.