PostTimely API Reference
60 tools for automated direct mail campaigns, brand analysis, audience targeting, and more.
Authentication
All requests require a Bearer token in the Authorization header.
Authorization: Bearer pt_live_...Credit System
Each tool has a credit cost (some are free). Credits are deducted from your account balance. Signup includes 1,000 free credits.
Rate Limits
Per-key rate limits apply (default: 30/min for free tier). Check X-RateLimit-Remaining response headers.
Error Codes
INVALID_API_KEYAPI key is missing, invalid, or expiredINSUFFICIENT_CREDITSNot enough credits for this operationRATE_LIMITEDToo many requests — retry after X-RateLimit-ResetINVALID_INPUTRequest body failed validation (details has field errors)TOOL_NOT_FOUNDUnknown tool name in URLINTERNAL_ERRORUnexpected server errorgetSubscriptionStatus
Get Subscription Status
Returns listing subscription details: status, billing period, monthly estimate.
POST /api/v1/getSubscriptionStatusmanageListingSubscription
Manage Listing Subscription
Manages listing mailer subscription: pause, resume, cancel, or update payment.
POST /api/v1/manageListingSubscriptionupgradeAccountPlan
Upgrade Account Plan
Initiates account plan change. Returns Stripe checkout session for paid plans.
POST /api/v1/upgradeAccountPlangetCampaignAnalytics
Get Campaign Analytics
Returns campaign performance: delivery breakdown, QR engagement, total cost, cost per piece.
POST /api/v1/getCampaignAnalyticsgetMailingStatuses
Get Mailing Statuses
Returns individual mailing statuses with recipient address and tracking info.
POST /api/v1/getMailingStatusesconfigureNeighborhoodMail
Configure Neighbourhood Mail
Configures neighbourhood blanket mail (Canada Post / Stannp). Radius-based delivery to all homes in area. Min 500 pieces, step 100.
POST /api/v1/configureNeighborhoodMailestimateSearchCost
Estimate Search Cost
Pre-search cost estimation. Returns estimated lead count and credit cost before committing to a search.
POST /api/v1/estimateSearchCostgetAvailableMailSizes
Get Available Mail Sizes
Returns available mail sizes for a country and channel.
POST /api/v1/getAvailableMailSizespreviewNewListings
Preview New Listings
Returns listing statistics for an area: 7-day count, daily average, monthly estimate, 20 sample listings.
POST /api/v1/previewNewListingssearchBusinessLeads
Search Business Leads
Searches Google Places for businesses by type in a geographic area. Returns contacts with address, rating, phone, website, coordinates. Costs 1 credit per lead returned.
POST /api/v1/searchBusinessLeadssearchHomeownerLeads
Search Homeowner Leads
Searches Houski for homeowners by intent: pool_owners, older_homes, homes_with_yards, higher_value_homeowners, family_oriented_homeowners. Costs 1 credit per lead.
POST /api/v1/searchHomeownerLeadsuploadLeadsCsv
Upload Leads CSV
Imports leads from CSV with column mapping. Costs 1 credit per lead imported.
POST /api/v1/uploadLeadsCsvcheckCanSpend
Check Can Spend
Checks if customer has sufficient credits for an operation.
POST /api/v1/checkCanSpendcreateListingSubscription
Create Listing Subscription
Creates recurring Stripe subscription for a listing campaign. Returns clientSecret.
POST /api/v1/createListingSubscriptioncreatePaymentIntent
Create Payment Intent
Creates Stripe PaymentIntent for a campaign. Returns clientSecret.
POST /api/v1/createPaymentIntentgetAccountPlans
Get Account Plans
Returns available account plans: Starter, Growth, Agency.
POST /api/v1/getAccountPlansgetCreditBalance
Get Credit Balance
Returns current credit balance, lifetime earned, and lifetime spent for a customer.
POST /api/v1/getCreditBalancegetMailingEstimate
Get Mailing Estimate
Returns tiered pricing breakdown for a campaign.
POST /api/v1/getMailingEstimategetNeighborhoodPricing
Get Neighbourhood Pricing
Returns neighbourhood mail pricing tiers.
POST /api/v1/getNeighborhoodPricinggetTriggeredPricing
Get Triggered Pricing
Returns triggered/listing campaign pricing with generous tier qualification.
POST /api/v1/getTriggeredPricingpostal.get_quote
Get Quote
Current per-piece pricing for your account, including volume-tier details.
POST /api/v1/postal.get_quotepostal.get_usage
Get Usage
Month-to-date piece counts, verified/unverified split, and accrued charges.
POST /api/v1/postal.get_usagepurchaseCredits
Purchase Credits
Initiates credit top-up. Returns Stripe PaymentIntent clientSecret.
POST /api/v1/purchaseCreditscreateCampaign
Create Campaign
Creates a draft campaign. Size defaults to 4x6 for postcards.
POST /api/v1/createCampaigncreateListingCampaign
Create Listing Campaign
Creates new listing mailer campaign with preview stats and brand.
POST /api/v1/createListingCampaigngetCampaignStatus
Get Campaign Status
Returns current campaign state: status, contacts count, designs, payment state, send progress.
POST /api/v1/getCampaignStatusscheduleSend
Schedule Send
Schedules campaign for a future send date.
POST /api/v1/scheduleSendvalidateCampaignRouting
Validate Campaign Routing
Validates multitype campaigns — checks template assignments, neighborhood config, required fields.
POST /api/v1/validateCampaignRoutinggetContactSummary
Get Contact Summary
Returns summary counts: total, selected, deselected, by business type.
POST /api/v1/getContactSummarylistCampaignContacts
List Campaign Contacts
Returns paginated list of contacts for a campaign.
POST /api/v1/listCampaignContactstoggleContactSelection
Toggle Contact Selection
Soft-selects or deselects contacts. Does NOT delete.
POST /api/v1/toggleContactSelectiondesignLetter
Design Letter
Creates letter design (US Letter XL Window format). Sections: paragraphs, bullets, CTAs, dividers, images.
POST /api/v1/designLetterdesignPostcardBack
Design Postcard Back
Generates back design with address block compositing.
POST /api/v1/designPostcardBackdesignPostcardFront
Design Postcard Front
Generates front postcard design via Gemini at the correct bleed-inclusive resolution for the selected size.
POST /api/v1/designPostcardFronteditDesign
Edit Design
Edits an existing front design using Gemini image editing mode with natural language instructions.
POST /api/v1/editDesigngenerateQrCode
Generate QR Code
Generates QR code PNG. Auto-prepends https://, validates max 100 chars. Uses brand color if contrast >= 4:1.
POST /api/v1/generateQrCoderenderLetterPdf
Render Letter PDF
Renders letter design to PDF via @react-pdf/renderer, uploads to storage, returns URL.
POST /api/v1/renderLetterPdfgeocodeLocation
Geocode Location
Geocodes an address to coordinates and bounding box for area targeting.
POST /api/v1/geocodeLocationplaceSelfLookup
Place Self-Lookup
Finds own business location and address via Google Places. Used for neighborhood mail center point.
POST /api/v1/placeSelfLookuppostal.validate_address
Validate Address
Validate and normalize a recipient address. Verified addresses qualify for the lower per-piece rate.
POST /api/v1/postal.validate_addressgetListingCampaignStats
Get Listing Campaign Stats
Returns postcards sent, period, monthly estimate, subscription status.
POST /api/v1/getListingCampaignStatsgetListingPreview
Get Listing Preview
Returns listing stats: 7-day count, daily avg, monthly estimate, sample listings.
POST /api/v1/getListingPreviewcheckSlugAvailability
Check Slug Availability
Checks if a playbook slug is available.
POST /api/v1/checkSlugAvailabilityconfigurePlaybookAudience
Configure Playbook Audience
Configures audience targeting for playbook.
POST /api/v1/configurePlaybookAudiencecreatePlaybook
Create Playbook
Creates playbook from an existing campaign. Auto-generates slug.
POST /api/v1/createPlaybookcreatePlaybookFromScratch
Create Playbook from Scratch
Auto-generates a source campaign then creates a playbook from it.
POST /api/v1/createPlaybookFromScratchgeneratePlaybookCopy
Generate Playbook Copy
AI-generates launch page copy using brand/leads/area context.
POST /api/v1/generatePlaybookCopypreviewPlaybook
Preview Playbook
Loads full playbook preview.
POST /api/v1/previewPlaybookupdatePlaybook
Update Playbook
Updates playbook configuration.
POST /api/v1/updatePlaybookpostal.cancel_mailing
Cancel Mailing
Cancel a postcard. Guaranteed while held; best-effort after submission to print.
POST /api/v1/postal.cancel_mailingpostal.get_mailing
Get Mailing
Fetch one mailing with current status and proof PDF.
POST /api/v1/postal.get_mailingpostal.get_specs
Get Print Specs
Print specifications for available products: pixel dimensions at 300dpi including bleed, safe zones, and the reserved address area.
POST /api/v1/postal.get_specspostal.list_mailings
List Mailings
List your mailings, newest first.
POST /api/v1/postal.list_mailingspostal.send_postcard
Send Postcard
Create a 4x6 postcard send. Artwork is fetched from your URLs, quality-checked, and held for your cancel window before printing. Priced per piece on your account rates.
POST /api/v1/postal.send_postcardprocessCampaignSend
Process Campaign Send
Triggers full send pipeline. Awards +10 credits per postcard sent.
POST /api/v1/processCampaignSendsendTestMailing
Send Test Mailing
Sends a single test postcard/letter to verify design before full campaign send.
POST /api/v1/sendTestMailingvalidateAddresses
Validate Addresses
Pre-send address validation via Google Address Validation API. Costs 5 credits per address.
POST /api/v1/validateAddressesanalyzeBusiness
Analyze Business
AI analysis of a business using web search. Returns business type, description, target audiences, and service areas.
POST /api/v1/analyzeBusinessbrandLookup
Brand Lookup
Scrapes a business website and extracts brand identity: logo URL, brand colors, tagline, voice, visual style, and contact info. Returns a brandId for use in design tools.
POST /api/v1/brandLookupgenerateDescription
Generate Description
AI-generates a 1-2 sentence business description using Gemini with Google Search grounding.
POST /api/v1/generateDescription