API Documentation

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

Authentication

Authenticate your API requests by including your secret API key in the Authorization header as a Bearer token.

Manage your API keys →

Send a Postcard

Queues a new postcard for daily batch processing. Postcards are printed on 120lb gloss cover stock and handed off to USPS.

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

Body Parameters

toobject • required

The recipient's destination address. Must include: name, address_line1, city, state, and zip.

front.image_urlstring • required

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

back.messagestring • required

The message to print on the back of the card. Maximum 350 characters.

sizestring • optional

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

cURL Request
curl -X POST https://shipapostcard.com/api/v1/postcards \
  -H "Authorization: Bearer sap_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "name": "Jane Doe",
      "address_line1": "123 Tech Blvd",
      "address_line2": "Suite 400",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105"
    },
    "front": {
      "image_url": "https://example.com/images/art.jpg"
    },
    "back": {
      "message": "Thanks for signing up for our enterprise plan!"
    },
    "size": "4x6"
  }'
201 Created
{
  "id": "sap_order_94812",
  "status": "pending_batch",
  "amount": 1.75,
  "message": "Postcard queued for daily batch processing."
}