API docs

Use MailThisForMe to create Letter-size PDF mail jobs from software workflows or from the customer dashboard. The current endpoints are intentionally small while the payment, validation, print, physical postage custody, and mailing pipeline is still being built.

Authentication

Authenticated endpoints use bearer API keys in the Authorization header. Raw API keys are shown once when created and are stored only as hashes.

Protected endpoints require bearer API keys linked to a user with a verified email address. API keys for banned accounts cannot use protected customer endpoints.

Signup and email verification happen on the platform website, not through the public API. Create an API key after verification, then contact an admin for account credit while payment deposits remain limited.

Duplicate-safe request key

Mail creation requests require a duplicate-safe request key. Send X-MailThisForMe-Request-Key or the standards-oriented Idempotency-Key header. Repeating the same request with the same key returns the original response without creating duplicate jobs or duplicate balance reservations; changing the payload with the same key returns a conflict.

Beginner path

Create an account in the browser.
Verify email.
Ask an admin to add account credit while payment deposits remain limited.
Create a default return address template.
Create a mail job from /mail-jobs/create or create an API key for software submission.
Submit API mail with POST /v1/mail/send when you need integration access.
Track status from the dashboard, by polling, or by webhook.

Customer browser flow

Verified customers can create jobs at /mail-jobs/create by selecting a saved return address, entering the recipient address, uploading a PDF, reviewing the calculated page count and price, and confirming the queued job. The browser flow uses the same sender resolution, PDF validation, pricing, balance reservation, cancellation, and webhook event rules as API-created jobs.

PDFs must be PDF only, US Letter 8.5 x 11 inches, 10 pages or fewer, and no more than 10 MB. Pricing is currently $2.25 for 1-4 pages and $4.50 for 5-10 pages. Uploading and confirming a job queues it for admin review; it does not print, purchase postage, charge live payment providers, or physically mail automatically.

Return address templates

Saved sender profiles reduce repeated payload fields. Use POST /v1/return-addresses to create one, POST /v1/return-addresses/{id}/default to make it the default, and GET /v1/return-addresses to list templates. Template ids use the public raddr_... format.

Submit a mail job with a PDF

Quote is optional. Most integrations can submit a validated PDF directly and let MailThisForMe calculate the final page count and price.

curl -X POST "https://api.mailthisforme.com/v1/mail/send" \
  -H "Authorization: Bearer mtfm_live_xxx" \
  -H "X-MailThisForMe-Request-Key: order-1001-send-1" \
  -F "document=@letter.pdf;type=application/pdf" \
  -F "recipient[name]=Example Recipient" \
  -F "recipient[address1]=123 Example St" \
  -F "recipient[city]=Kansas City" \
  -F "recipient[state]=MO" \
  -F "recipient[postal_code]=64101" \
  -F "return_address_id=raddr_example123"

Direct sender fields still work. If no direct sender or template id is provided, the API uses the user's default return address template when one exists. Without any sender source, the request returns 422.

Endpoints

POST /v1/mail/send submits a PDF mail job, validates the PDF, calculates page count and price, creates a queued test-mode job, and reserves prepaid balance.
GET /v1/return-addresses, POST /v1/return-addresses, PATCH /v1/return-addresses/{id}, DELETE /v1/return-addresses/{id}, and POST /v1/return-addresses/{id}/default manage return address templates.
POST /v1/mail/quote is optional. Use it when you want a price estimate before submitting.
POST /v1/mail creates a queued test-mode mail job for advanced staged workflows and reserves prepaid test balance.
POST /v1/mail/{id}/document uploads a private PDF for a queued staged job, validates every page as US Letter 8.5 x 11, and stores checksum plus validation metadata.
GET /v1/mail/{id} returns visible status fields, safe document metadata, cancellation eligibility, and a safe webhook delivery summary for that job.
POST /v1/mail/{id}/cancel cancels jobs while they are still queued and releases reservations.
GET /v1/balance returns available and reserved balance.
GET /v1/transactions returns recent ledger entries.

Status values include queued, processing, mailed, failed, cancelled, and rejected. Status responses do not include private storage paths, document URLs, internal database ids, secrets, or raw webhook payloads.

Cancelled, rejected, and failed jobs may release reserved balance when applicable, but refunds, disputes, failed fulfillment review, and account-credit corrections are manual operational reviews. mailed means handed off to USPS, not recipient delivery, and consumers should not assume tracking for standard stamped mail. Review the refund policy and mailing policy.

Address handling

Job creation trims address strings and normalizes state and country codes to uppercase before storing the job. Provider-certified USPS address validation remains limited pending provider evidence.

Documents

Queued jobs can receive one or more PDF uploads. Files are stored privately, limited to 10 MB each, checksummed with SHA-256, and validated immediately. Every page must be US Letter size: 8.5 x 11 inches, 612 x 792 PDF points in portrait or 792 x 612 in landscape, with a 2-point tolerance for generator quirks. Documents may not exceed 10 pages.

A4, legal, custom, mixed-size, encrypted, corrupted, zero-page, and non-PDF documents are rejected. Letter landscape PDFs are accepted for the MVP and flagged for operator review. Rejected documents are not mailed, and physical mail is sent only after admin fulfillment review during public access readiness.

Webhooks

The platform dashboard can store webhook endpoints and process signed outbound delivery attempts for active endpoints. Mail job events include mail.queued, mail.cancelled, mail.rejected, mail.processing, mail.mailed, and mail.failed. Event payloads include safe mail status, price, page count, document status, cancellation eligibility, and timestamps. They do not include document URLs, private storage paths, raw PDFs, or secrets.

Deliveries use HMAC SHA-256 headers, low timeouts, retry metadata, and production private-network blocking. Customer-facing manual retry controls are not part of the current public access readiness surface.

Errors

Common API errors include 401 for missing or invalid API keys, 402 for insufficient prepaid balance, 403 for banned or unverified accounts, 409 for duplicate-safe request key conflicts or invalid job state, and 422 for validation failures.

OpenAPI YAML

The current spec is available at https://api.mailthisforme.com/openapi.yaml.