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:
- Open API Keys in the Developer Hub and create a key. Copy it right away: it is shown only once.
- 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.
- Send the key in the
Authorization: Bearer YOUR_API_KEYheader of every request, together withAccept: application/json.
Check that your key works by asking who you are:
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.
https://shipapostcard.com/api/v1/postcardsBody Parameters
messagestring • requiredThe message printed on the back of the card. Maximum 350 characters.
recipient_details.namestring • requiredRecipient name. Maximum 40 characters.
recipient_details.address_line1string • requiredStreet address. Maximum 64 characters.
recipient_details.citystring • requiredCity.
recipient_details.statestring • requiredTwo-letter state code, e.g. CA.
recipient_details.zipstring • requiredZIP code: 12345 or 12345-6789.
recipient_details.countrystring • requiredTwo-letter country code. Use US.
design_details.image_urlstring • requiredA publicly accessible URL to a high-resolution JPG or PNG image. Must be under 20MB.
design_details.sizestring • optionalDefaults to 4x6. Accepted values: 4x6, 5x7, 6x9.
design_details.orientationstring • optionallandscape or portrait.
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"
}
}'{
"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.
https://shipapostcard.com/api/v1/postcards?page=1{
"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.
https://shipapostcard.com/api/v1/postcards/sap_order_94812{
"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.
https://shipapostcard.com/api/v1/postcards/sap_order_94812Order lifecycle and billing
pending_batch: received. We check the address, the message and the image.ready_for_batch: ready for tonight's batch. Problems end here instead asinvalid_address,flagged_for_revieworimage_download_failed.- 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_faileduntil the payment method is updated. - Then
sent_to_printer,in_transitand finallydelivered, as USPS reports progress.
Webhooks
Instead of polling, register an endpoint and we will POST these events to it:
postcard.createdpostcard.sent_to_printerpostcard.deliveredpostcard.failedbatch.payment_failed
Each request is signed with your endpoint's secret. The Webhooks page explains how to verify the signature.
Errors and rate limits
401missing, invalid or revoked API key.403the key cannot do this, for example cancel a postcard that is already printing.404the postcard does not exist in your workspace.422invalid parameters. The response lists every invalid field.429too many requests. The limit is 600 requests per minute per user.
{
"error": "Validation Failed",
"details": {
"recipient_details.zip": ["The recipient details.zip field format is invalid."]
}
}{
"success": false,
"message": "Unauthenticated",
"errors": null,
"error_code": "AUTH_ERROR"
}Every request you make is listed with its response in API Request Logs.