canonical: https://jentic.com/apis/cleverreach.com/cleverreach-main # CleverReach REST API A curated, agent-optimized Jentic OpenAPI 3.0 specification for the CleverReach REST API, kept validated and agent-ready. CleverReach also publishes its own Swagger 2.0 document from the API explorer on its REST host, and that vendor document is the canonical source, covering a slightly wider operation set; the Jentic variant restates that surface in OpenAPI 3.0 and shapes it for agent discovery. The CleverReach REST API is the full v3 surface for CleverReach's email marketing platform, with 120 endpoints covering clients, groups, receivers, mailings, forms, attributes, filters, advanced statistics, and the blacklist. It exposes much deeper coverage than the slim cleverreach-api spec - including segmentation filters, group-level orders and events, form management, and client-level limits and plan data. Agents can use it to drive end-to-end email marketing operations including segmentation, campaign release, and analytics. ## For AI agents Operate CleverReach end-to-end - manage groups, receivers, segmentation filters, mailings, forms, and advanced campaign statistics across a v3 surface of 120 endpoints. ## Scope Does not handle SMS, push notifications, or transactional email delivery - use for CleverReach marketing list, segmentation, and mailing operations only. ## Capabilities - Segment recipients with group-level filters and read filtered receiver counts and stats - Sync receivers in and out of groups, including order and event history per recipient - Manage forms attached to a CleverReach group for sign-up capture - Read advanced mailing statistics, including per-group performance breakdowns - Configure custom group attributes used to enrich receiver records - Validate addresses against and write entries to the global and group-level blacklists - Read client-level limits, plan, contingent, and next invoice date for billing oversight ## Use cases ### Behavioural Segmentation and Targeted Sends Build dynamic segments inside CleverReach by saving group-level filters and reading the resulting receiver lists and stats before triggering a targeted mailing. The `/v3/groups/{group_id}/filters` family of endpoints lets an automation create, count, and read filtered receivers, which feeds straight into a targeted send. Standing up a basic segmentation flow takes a day or two of integration work. Example prompt: Create a filter on group_id 1234 that selects receivers with a specific tag, read `/v3/groups/1234/filters/{filter_id}/count`, and confirm the segment size before releasing a mailing ### Receiver Order and Event History Pull per-receiver order and event histories from CleverReach to power a personalised email or to feed a downstream CRM. The `/v3/groups/{group_id}/receivers/{pool_id}/orders` and /events endpoints expose this data per recipient, which is useful for transactional re-engagement campaigns and lifecycle automation. A working sync job takes under a day. Example prompt: Fetch `/v3/groups/1234/receivers/{pool_id}/orders` for a specific receiver and surface the order count back to the caller ### Sign-Up Form Management Read and manage the sign-up forms attached to CleverReach groups so that an external site builder or CMS can render or update them programmatically. The `/v3/groups/{id}/forms` endpoint exposes the form metadata, which is enough to drive an embedded sign-up widget. A simple integration takes a few hours. Example prompt: List forms for group_id 1234 via `/v3/groups/1234/forms` and return the form ids and names ### Agent-Driven CleverReach Operations via Jentic Hand CleverReach to an AI agent through Jentic so a marketing operator can describe an outcome - 'segment last month's bouncers and remove them' - and have the agent compose the right calls. Jentic isolates the OAuth credentials and surfaces only the relevant operations for the intent. A working integration takes well under an hour. Example prompt: Search Jentic for 'segment cleverreach receivers', load the filter creation operation, and execute it against group_id 1234 ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v3/groups/{group_id}/filters/{filter_id}/receivers` | List receivers matching a saved filter | | GET | `/v3/groups/{group_id}/advancedstats` | Read advanced statistics for a group | | GET | `/v3/groups/{group_id}/receivers/{pool_id}/orders` | List orders for a receiver | | GET | `/v3/groups/{group_id}/receivers/{pool_id}/events` | List events for a receiver | | POST | `/v3/blacklist` | Add an email address to the blacklist | | GET | `/v3/clients/{id}/limits` | Read account limits for a client | ## Key resources - **Clients** — Read client metadata, limits, plan, contingent, invoice address, and next invoice date - **Groups** — Manage groups, attributes, filters, advanced stats, and forms - **Receivers** — Manage receivers within groups including event and order histories - **Mailings** — Manage mailings and read mailing-level statistics - **Forms** — Read sign-up forms attached to groups - **Blacklist** — Read, write, and validate against the global and group-level blacklist ## Why Jentic - **Setup:** Wiring the CleverReach REST API by hand means running its OAuth2 flow and threading group, filter, and receiver ids through calls to rest.cleverreach.com across its large operation set. Through Jentic you install once, import CleverReach from the API Directory, store the credential once, and your agent calls it. - **Permission scoping:** CleverReach puts the group id and pool id in the URL path (`/v3/groups/{group_id}/receivers/{pool_id}/orders`), so a rule can pin your agent to one group: it can read that group's receivers, stats, and orders and nothing else. You choose the operations it may call, so writing to the blacklist is not included unless you add it. - **Credential handling:** Your CleverReach OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'read a group's advanced stats' or 'list a receiver's orders in CleverReach', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **CleverReach API (slim)** — A 19-endpoint subset of the CleverReach v3 API focused on the most common operations - **Mailchimp Marketing API** — US-hosted email marketing platform with deeper journey tooling - **Mandrill API** — Transactional email delivery service ## FAQ ### Which OpenAPI specification does this CleverReach REST API page describe? A curated, agent-optimized Jentic specification covering 120 CleverReach endpoints, converted to OpenAPI 3.0 and validated against the live API so agents and developers can call it through structured tooling. CleverReach also publishes its own Swagger 2.0 document, served from its API explorer reference at https://rest.cleverreach.com/v3/explorer/swagger.json, and that vendor document is the canonical source: it describes 132 operations across 100 paths, including tag, OAuth token revoke, and batch blacklist calls the Jentic variant does not include. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the CleverReach REST API use? The CleverReach REST API uses OAuth 2.0 against rest.cleverreach.com. You exchange your client credentials for an access token and pass it as a bearer token in the Authorization header. Through Jentic, the OAuth client secret is held in your Jentic One instance and never exposed to the agent context. ### Can I build receiver segments with the CleverReach REST API? Yes. Group-level filters at `/v3/groups/{group_id}/filters` allow you to create and store filter definitions, count matched receivers via /count, and pull the list via /receivers - which is enough to drive a targeted send. ### Can I read per-receiver order and event history? Yes. `/v3/groups/{group_id}/receivers/{pool_id}/orders` and the matching /events endpoint return the orders and tracked events attached to a receiver, which supports lifecycle and re-engagement campaigns. ### What are the rate limits for the CleverReach REST API? CleverReach does not document fixed numeric rate limits in the public spec. In practice, keep batch operations under a few hundred receivers per call and avoid tight polling loops on `/v3/clients/{id}/contingent` - once per minute is typically enough. ### How do I segment a CleverReach list through Jentic? Run pip install jentic, search for 'segment cleverreach receivers', load the filter creation operation, and execute it against the target group_id. Jentic handles the OAuth token exchange and returns the API response. ### Can I limit what my agent is allowed to do with the CleverReach REST API? Yes. Because your Jentic One instance is self-hosted, your own rules decide which CleverReach operations and credentials the agent can use. Since CleverReach puts the group id and pool id in the URL path, such as `/v3/groups/{group_id}/receivers/{pool_id}/orders`, you can pin the agent to a single group so it only reads that group's receivers, stats, and orders. You also choose the exact operations it may call, so a write to `/v3/blacklist` is excluded unless you explicitly grant it.