canonical: https://jentic.com/apis/click2mail.com/click2mail # Click2Mail REST API Jentic publishes the only available OpenAPI specification for Click2Mail REST API, keeping it validated and agent-ready. Click2Mail provides programmatic print-and-mail - letters, postcards, and direct mail pieces dispatched through the US Postal Service via a REST interface. The API is built around three primary resources: documents that hold the printable content, address lists that hold the recipients, and jobs that combine the two into a physical mailing. Agents can use it to upload a PDF, attach a recipient list, submit the job, and read the account credit balance, all behind HTTP Basic auth. ## For AI agents Send physical mail through Click2Mail - upload documents, attach address lists, submit jobs, and check account credits without leaving an agent workflow. ## Scope Does not handle email, SMS, or fax delivery, and does not generate PDF content from templates - use for Click2Mail document upload, address list, and physical mailing job submission only. ## Capabilities - Upload print-ready documents and read or delete document records - Create and manage address lists of recipients to be paired with mailing jobs - Compose mailing jobs that bind a document to an address list - Submit a prepared job for printing and dispatch through Click2Mail - Read account credit balance to confirm sufficient funds before submitting - Inspect a single job, document, or address list by id ## Use cases ### Programmatic Direct Mail Drop Send physical mail from a backend system by uploading a document, attaching an address list, creating a job that pairs them, and submitting that job for print and dispatch. Click2Mail handles printing, addressing, and USPS handoff. Standing up a basic flow takes a day or two of integration work, including PDF generation upstream. Example prompt: Upload a PDF to /documents, create an address list at /addressLists with one recipient, create a job at /jobs that pairs them, then call `/jobs/{id}/submit` ### Compliance and Notice Mailings Drive compliance-driven mailings (annual privacy notices, regulatory disclosures, debt collection letters) directly from a backend service so that volume changes do not require manual intervention. The /jobs and `/jobs/{id}/submit` endpoints make the actual dispatch deterministic, and `/account/credits` lets the system pre-check funding. A working flow takes a few days to harden for production volumes. Example prompt: Read `/account/credits` to confirm balance is greater than 1000, then submit each pending job in turn via `/jobs/{id}/submit` ### Address List Maintenance Keep recipient address lists in Click2Mail aligned with a source-of-truth CRM by creating, updating, and deleting lists from an automation. /addressLists and `/addressLists/{id}` cover the full lifecycle, which is enough to drive a nightly sync job. Setup is typically under a day. Example prompt: Replace the contents of address list id 5678 with the latest 250 customers from the upstream CRM via DELETE then POST against /addressLists ### Agent-Driven Direct Mail via Jentic Expose Click2Mail to an AI agent through Jentic so an operator can describe an outcome - 'mail this PDF to these 50 customers tomorrow' - and have the agent compose the right document, address list, job, and submit calls. Jentic isolates the Basic auth credentials and surfaces only the relevant operations for the intent. A working integration takes well under an hour. Example prompt: Search Jentic for 'send a physical letter via click2mail', load the chained operations, and execute the upload-create-submit sequence for a single recipient ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/documents` | Upload a print-ready document | | POST | `/addressLists` | Create an address list | | POST | `/jobs` | Create a mailing job | | POST | `/jobs/{id}/submit` | Submit a job for print and dispatch | | GET | `/account/credits` | Read account credit balance | | GET | `/jobs/{id}` | Read a single mailing job | ## Key resources - **Documents** — Upload, list, retrieve, and delete print-ready documents - **Address Lists** — Create and manage recipient address lists used in mailings - **Jobs** — Compose and submit mailing jobs that bind documents to address lists - **Account** — Read account-level metadata such as remaining mailing credits ## Why Jentic - **Setup:** Wiring Click2Mail by hand means setting up HTTP Basic auth, targeting the right rest.click2mail.com host versus the staging host, and chaining document upload, address list, and job creation yourself before a mailing goes out. Through Jentic you install once, import the Click2Mail REST API from the API Directory, store the username and password once, and your agent calls it. - **Permission scoping:** Click2Mail puts the job id in the URL path (`/jobs/{id}/submit`, `/jobs/{id}`), so a rule can pin your agent to work with a specific mailing job and read its status. You choose the operations it may call, so you can allow document upload and job status reads without granting job submission unless you add it. - **Credential handling:** Your Click2Mail username and password are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'send a physical letter via Click2Mail' or 'check a mailing job status', and Jentic returns the matching Click2Mail operation with its input schema so the agent can chain document upload, list creation, job creation, and submission without browsing the reference docs. ## Related APIs - **PDFMonkey API** — Generate templated PDFs ready to be uploaded to Click2Mail - **SendGrid Mail** — Email delivery service for digital correspondence - **Mailchimp API** — Email marketing and automation platform ## FAQ ### Why is there no official OpenAPI spec for Click2Mail REST API? Click2Mail does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Click2Mail REST API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Click2Mail REST API use? Click2Mail uses HTTP Basic authentication against rest.click2mail.com/molpro. You pass your username and password via the standard Authorization header. Through Jentic, those credentials are stored in your Jentic One instance and never exposed to the agent context. ### Can I send a physical letter end-to-end with this API? Yes. Upload a PDF to POST /documents, create recipients via POST /addressLists, bind them with POST /jobs, then call POST `/jobs/{id}/submit.` Click2Mail handles printing, addressing, and USPS dispatch from there. ### Can I check my account balance before submitting jobs? Yes. GET `/account/credits` returns the remaining credit balance, which is the right pre-check before a bulk `/jobs/{id}/submit` call to avoid mid-batch failures. ### What are the rate limits for the Click2Mail REST API? Click2Mail does not document fixed numeric rate limits in the public spec. In practice, document uploads are the slowest call (multipart payloads up to several MB), so cap concurrency to a handful of parallel uploads per account. ### How do I send a letter through Jentic? Run pip install jentic, search for 'send a physical letter via click2mail', load the document upload, address list create, job create, and job submit operations in sequence, and execute them. Jentic handles the Basic auth header on every call. ### Can I limit what my agent is allowed to do with the Click2Mail REST API? Yes. Jentic One is self-hosted, so your own rules decide which Click2Mail operations and credentials your agent may use. You can allow document uploads to POST /documents and job status reads on GET `/jobs/{id}` while withholding job submission on POST `/jobs/{id}/submit` until you explicitly grant it. Because Click2Mail puts the job id in the URL path, a rule can also pin the agent to a specific mailing job rather than acting across the whole account.