API Documentation

Integrate physical mail directly into your software. Our REST API uses JSON requests and standard HTTP response codes.

Base URL: https://shipapostcard.com/api/v1

Machine-readable contract (import it into Postman, Insomnia or a code generator): OpenAPI 3.1 spec

Runnable examples in cURL, Node.js, PHP and Python: GitHub repository

Try every request without writing code: Postman collection

Authentication

Every request is authenticated with an API key sent as a Bearer token. Getting started takes three steps:

  1. Open API Keys in the Developer Hub and create a key. Copy it right away: it is shown only once.
  2. A key belongs to the workspace you had open when you created it. Orders made with it go to that workspace and are billed to its owner, so make sure the owner has a payment method on file.
  3. Send the key in the Authorization: Bearer YOUR_API_KEY header of every request, together with Accept: application/json.

Check that your key works by asking who you are:

Test your key
curl https://shipapostcard.com/api/v1/user \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Keep keys on your server and never put them in browser or mobile code. If a key leaks, revoke it in the Developer Hub and create a new one.

Send a Postcard

Queues a new postcard for daily batch processing. Postcards are printed on 120lb gloss cover stock and handed off to USPS. Recipients must have a US address. Senders can be anywhere.

POSThttps://shipapostcard.com/api/v1/postcards

Body Parameters

messagestring • required

The message printed on the back of the card. Maximum 350 characters.

recipient_details.namestring • required

Recipient name. Maximum 40 characters.

recipient_details.address_line1string • required

Street address. Maximum 64 characters.

recipient_details.citystring • required

City.

recipient_details.statestring • required

Two-letter state code, e.g. CA.

recipient_details.zipstring • required

ZIP code: 12345 or 12345-6789.

recipient_details.countrystring • required

Two-letter country code. Use US.

design_details.image_urlstring • required

A publicly accessible URL to a high-resolution JPG or PNG image. Must be under 20MB.

design_details.sizestring • optional

Defaults to 4x6. Accepted values: 4x6, 5x7, 6x9.

design_details.orientationstring • optional

landscape or portrait.

Request
curl -X POST https://shipapostcard.com/api/v1/postcards \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "message": "Thanks for signing up for our enterprise plan!",
    "recipient_details": {
      "name": "Jane Doe",
      "address_line1": "123 Tech Blvd",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "design_details": {
      "image_url": "https://example.com/images/art.jpg",
      "size": "4x6",
      "orientation": "landscape"
    }
  }'
201 Created
{
  "id": "sap_order_94812",
  "status": "pending_batch",
  "amount": 2.25,
  "message": "Postcard queued for daily batch processing."
}

amount is the single-card price in USD. The final price is set by volume when the nightly batch runs.

List postcards

Returns the postcards of your workspace, 10 per page. Use the page query parameter to move through the results.

GEThttps://shipapostcard.com/api/v1/postcards?page=1
200 OK
{
  "current_page": 1,
  "data": [ { "id": "sap_order_94812", "status": "in_transit", ... } ],
  "per_page": 10,
  "total": 37,
  "next_page_url": "https://shipapostcard.com/api/v1/postcards?page=2"
}

Retrieve a postcard

Use the id returned when you created the postcard. Both sap_order_94812 and the plain number work.

GEThttps://shipapostcard.com/api/v1/postcards/sap_order_94812
200 OK
{
  "id": "sap_order_94812",
  "status": "in_transit",
  "amount": 2.25,
  "message": "Thanks for signing up for our enterprise plan!",
  "recipient_details": {
    "name": "Jane Doe",
    "address_line1": "123 Tech Blvd",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "country": "US"
  },
  "design_details": {
    "image_url": "https://example.com/images/art.jpg",
    "size": "4x6",
    "orientation": "landscape"
  },
  "tracking": {
    "expected_delivery_date": "2026-10-22",
    "events": [
      { "event": "sent_to_printer", "timestamp": "2026-10-16 23:59:41" },
      { "event": "postcard.in_transit", "timestamp": "2026-10-18 09:12:05" }
    ]
  },
  "created_at": "2026-10-16T14:03:11+00:00",
  "updated_at": "2026-10-18T09:12:05+00:00"
}

amount is in USD, as in the create response. tracking fills in once the card is sent to the printer.

Cancel a postcard

You can cancel a postcard until the nightly batch picks it up (status pending_batch or ready_for_batch). Success returns 204 with no body; after that point the API returns 403.

DELETEhttps://shipapostcard.com/api/v1/postcards/sap_order_94812

Order lifecycle and billing

  1. pending_batch: received. We check the address, the message and the image.
  2. ready_for_batch: ready for tonight's batch. Problems end here instead as invalid_address, flagged_for_review or image_download_failed.
  3. Every night at 23:59 UTC, all ready postcards of a workspace are billed together to the owner's card, priced by volume (see pricing). If the card is declined, they wait as payment_failed until the payment method is updated.
  4. Then sent_to_printer, in_transit and finally delivered, as USPS reports progress.

Webhooks

Instead of polling, register an endpoint and we will POST these events to it:

  • postcard.created
  • postcard.sent_to_printer
  • postcard.delivered
  • postcard.failed
  • batch.payment_failed

Each request is signed with your endpoint's secret. The Webhooks page explains how to verify the signature.

Errors and rate limits

  • 401 missing, invalid or revoked API key.
  • 403 the key cannot do this, for example cancel a postcard that is already printing.
  • 404 the postcard does not exist in your workspace.
  • 422 invalid parameters. The response lists every invalid field.
  • 429 too many requests. The limit is 600 requests per minute per user.
422 when creating a postcard
{
  "error": "Validation Failed",
  "details": {
    "recipient_details.zip": ["The recipient details.zip field format is invalid."]
  }
}
401 on any endpoint
{
  "success": false,
  "message": "Unauthenticated",
  "errors": null,
  "error_code": "AUTH_ERROR"
}

Every request you make is listed with its response in API Request Logs.