Postally
Log InGet Started

Send your first postcard with the Postally API

This walks a new account from signup to a rendered test postcard, then to live mail. Every request below works as written with the test key from your welcome email. Postally sends postcards only today; letters and self-mailers are coming soon.

Before you start

  • Your test API key starts with dm_test_. It was shown once when you signed up, and it is in the welcome email Postally sent you; it is shown nowhere else. If you no longer have it, sign in to the dashboard and create another test key under Settings → API Keys; a new key is shown once.
  • Send the key as Authorization: Bearer <key> to https://api.postally.ca.
  • A test key renders your card but never prints, mails or charges it. No live key is issued at signup; step 5 creates one.

Step 0: verify your email

Click the link in the verification email. Until your email is verified, every send door answers 403 email_not_verified, even with a test key: POST /v1/postcards/create, batch sends, campaigns, orders, postcard mailings, triggers and the Zapier/Make send actions (API reference section 2.7 lists every request it blocks). The link expires after 24 hours. For a new one, sign in to the dashboard and click "Resend verification email" in the banner at the top (at most three an hour).

You can check your key while you wait. This request works before verification, and its answer carries "email_verified": true once you have clicked the link:

curl https://api.postally.ca/v1/users/me \
  -H "Authorization: Bearer dm_test_your_key"

Step 1: send a test postcard

One request: an inline recipient and two sample PDFs that Postally hosts. The Front is the address side: Postally prints the recipient address, postage and barcode area on it. The Back is the picture side.

curl -X POST https://api.postally.ca/v1/postcards/create \
  -H "Authorization: Bearer dm_test_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-test-card-1" \
  -d '{
    "size": "postcard_4x6",
    "front_pdf_url": "https://postally.ca/samples/postcard-4x6-front.pdf",
    "back_pdf_url": "https://postally.ca/samples/postcard-4x6-back.pdf",
    "recipient": {
      "first_name": "Jane",
      "last_name": "Smith",
      "address_line1": "100 King St W",
      "city": "Toronto",
      "state": "ON",
      "postal_code": "M5X 1A9",
      "country": "CA"
    }
  }'

The answer is 201 with the piece's id, "status": "created" and "is_test": true. A test piece stays at created: it is never printed, mailed or charged. Postally downloads and checks both PDFs before it creates the piece; a file that fails is refused with 422 pdf_compliance_failed, which lists the failed checks, and nothing is created.

The Idempotency-Key header is optional but recommended: for 24 hours, repeating the same request with the same key returns the first answer instead of creating a second card, and the same key with a different body is refused. Use a new key for each new card.

Step 2: look at the rendered card

Rendering runs after the 201 and takes a few seconds. Fetch the piece until has_pdf is true or status is failed:

curl https://api.postally.ca/v1/mailpieces/get/MAILPIECE_ID \
  -H "Authorization: Bearer dm_test_your_key"

Then download a PNG preview of the front (/preview/2 is the back) or the print PDF:

curl -o front.png https://api.postally.ca/v1/mailpieces/MAILPIECE_ID/preview/1 \
  -H "Authorization: Bearer dm_test_your_key"
curl -o card.pdf https://api.postally.ca/v1/mailpieces/MAILPIECE_ID/pdf \
  -H "Authorization: Bearer dm_test_your_key"

Stop polling after a few minutes. A test piece whose render fails moves to failed, and its failure_reason says why. Artwork and rendered PDFs for test pieces are deleted 30 days after the piece is created.

A test send with neither front_pdf_url nor template_id is accepted, but nothing is rendered and the 201 carries a no_artwork warning. Send artwork whenever you want to see the card.

Step 3: use your own artwork

  • One PDF page per side. For postcard_4x6 the page is 6.25 × 4.25 in (450 × 306 pt): the 6 × 4 in card plus 0.125 in of bleed on every edge. The other sizes are 7.25 × 5.25 in (postcard_5x7), 9.25 × 6.25 in (postcard_6x9) and 11.25 × 6.25 in (postcard_6x11).
  • Landscape and not rotated. A page saved with a 90° or 270° rotation is refused.
  • Keep the bottom right of the Front clear: the address box goes there. The design guide for each size marks every zone, for example https://api.postally.ca/v1/docs/download/postcard-design-guide-4x6.
  • Host the files on any public HTTPS address, or upload them to Postally: call POST /v1/uploads/presign, PUT the file to the upload_url it returns, then send its file_url as front_pdf_url or back_pdf_url. API reference sections 11.1.1 and 19 show the requests.

Step 4: webhooks

Webhooks are never sent for test pieces. You can register your endpoint now with POST /v1/webhooks/create, but deliveries start only with live mail, so check your signature verification against API reference section 17.3 rather than with a test send.

Step 5: go live

  • In the dashboard, open Settings → API Keys → Create Key and choose Live. A Live key can only be created once your email is verified (otherwise 403 live_keys_require_email_verification). The key is shown once.
  • Open Billing → Add Credits (minimum $20). Credits can be added once a Live key exists. Cards sent through the API are paid from these prepaid credits.
  • Send the same request with your dm_live_ key and your own artwork. A live piece is created at status queued, is paid from your credits and goes to the print partner in the next nightly batch. Until 11:59 pm Vancouver time on the day you sent it, you can cancel it with POST /v1/mailpieces/cancel.

Common mistakes

  • A US Letter or A4 page, or one PDF with both sides on two pages. Each side is its own one-page file at the size above.
  • Front and Back swapped. The Front is the address side.
  • "mail_class": "standard" on a single card. Personalized Mail needs 125 or more pieces in one mailing; leave mail_class out and a single card goes first class (Lettermail within Canada, Letter-post to the USA and abroad).
  • Sending a template before it is published. The path above needs no template at all.

Next