Card Mailer

Use this when the user wants to mail printed cards to people at US postal addresses and gives the addresses as pasted text, a CSV, or an .xlsx spreadsheet. Reads names and addresses, checks required fields and US address format, and saves them as a recipient list. USPS verification runs only when it is configured; usps_checked in the result says whether it ran. Format checks alone do not confirm that an address is deliverable. Returns a list_id, how many rows are ready, and the problem for each row that needs fixing. Up to 300 recipients; pass list_id to append rows to an existing list. US addresses only. Not for e-cards or email, addresses outside the US, or advertising mail to purchased or rented lists.

Use this to correct or remove one recipient in a list from import_address_list, by row number. Given fields replace the stored values and omitted fields keep theirs; if the row's problem says it could not be read, pass name, line1, city, state and zip together. Re-runs the required-field and US address format checks, plus USPS verification when it is configured. Format checks alone do not confirm that an address is deliverable. remove: true takes the recipient out of the mailing. Rows in a list that belongs to a paid order cannot be changed.

Use this to create or edit the printed 5x7 postcard: a greeting on the front over or under the photo, and a message and sign-off on the back. Pass the photo the user attached as photo, or a public https image URL as photo_url; the image is downloaded and stored on cards.onmax.me. Without a photo the front is the greeting on a solid color. Pass design_id to edit a design: given fields replace the old values and omitted fields keep them. Use the message the user wrote or approved, up to 500 characters. Places the user's photo and text in a print template; does not generate images.

Use this when the user asks what mailing a card to an imported list costs or when it will arrive. Returns the price per card (First-Class postage included), the total for the ready recipients, the send date and the expected arrival window. For a card preview with the price, first create or edit it with design_card, then pass that exact design_id here. This shows the current saved front and back above the quote. design_id is required: use null only when the user requested a price-only quote without a design. Never claim a preview is shown when preview_included is false. If the cards must arrive by a date, pass arrive_by; the result gives the latest safe send date and whether that date can be met. Does not create an order or charge anything.

Use this when the user has seen the card and the quote and says they want to order. Creates an unpaid order for the ready recipients in list_id with design_id and returns a link to cards.onmax.me, where the user reviews the recipients and pays. Nothing is printed, mailed or charged until the user pays on that page. Recipients that still need fixing are left out. Each call creates a separate order link, so call it once per order. Optional sender is printed as the US return address.

Use this when the user asks whether a Card Mailer order was paid, printed, mailed or delivered. Takes the mailing_id returned by create_mailing (also the last part of the order link). Returns the status, send date, expected arrival and per-recipient counts. Does not change the order or track other USPS mail.