ManyReach
Audience: Engineering · Where in app: ManyReach card under Settings → Integrations; the Add to ManyReach campaign step in Agent K workflows · Gating: none beyond an authenticated company user — the agent_k_beta_enabled super-admin flag was removed 2026-09-25 (f1d39fb38)
ManyReach is an external cold-email sender used by Agent K tenants. Knock Knock never sends the email — it mints per-recipient kk_tokens, writes each token (and each campaign link, pre-tokenized) into ManyReach prospect custom fields, and pushes the prospects into a chosen campaign. Clicks stitch back through the kk-click endpoint.
Routes
All under the authenticated Nox action router (backend/app/routes/noxActionRoutes.js), each resolving the company via NoxActionUserController._resolveCompany:
| Action | Route |
|---|---|
| Connect (validate + store API key) | POST /knox/agent-k/manyreach/connect |
| Disconnect (clear the key) | POST /knox/agent-k/manyreach/disconnect |
| List campaigns (+ connection state, token field, links) | GET /knox/agent-k/manyreach/campaigns |
| Set token custom field (+ its ManyReach variable name) | POST /knox/agent-k/manyreach/token-field |
| Replace the campaign-link list | POST /knox/agent-k/manyreach/links |
| Push prospects into a campaign | POST /knox/agent-k/manyreach/push |
| Mint tokens for an external/CSV send | POST /knox/agent-k/campaign-tokens |
Connect validates the key by listing campaigns before storing it in the credential vault (CredentialVault.set({ company_id }, 'manyreach', { api_key }, { hint: last 4 }), 43ae39ef8); disconnect calls vault.remove. Every reader — the campaigns/push endpoints, the workflow step, Agent K rule validation and Nox automation capabilities (manyreach_connected) — goes through vault.get / vault.status. The legacy plaintext fallback and the old ai_agent_k.manyreach.api_key field were removed when the vault's dual-write window closed (856f5b145, 2026-11-12) — deploy that only once the "Move secrets" migration showed 0. A 401/406 from ManyReach maps to "reconnect": the campaigns endpoint answers { connected: false, key_rejected: true }, push returns the reconnect error.
Config (companies.ai_agent_k.manyreach)
| Field | Notes |
|---|---|
api_key | Removed from the schema (856f5b145) — the key lives only in the credential vault (provider manyreach, see Routes). |
token_field | Prospect custom field the kk token is written to — custom1..custom20 (MANYREACH_FIELD_RE), default custom20 |
token_field_name | The variable's name as renamed in ManyReach — display only (the API pushes by slot), ≤100 chars |
links[] | { field, url, name } — each pushed per prospect as field = url?kk=<token>&utm_source=manyreach&utm_medium=email&utm_campaign=<campaign_id>. Works around ManyReach's editor URL-encoding {{ }} inside hrefs (templates paste the variable as plain text). A link keeps its field for life so template tags never renumber. |
Service
backend/app/services/ManyReachService.js — thin axios client:
listCampaigns(api_key)— first page, newest 100 (picker-sized); normalizes{ id, name, status }.prospect({ email, name, token, token_field, links, campaign_id, extra })— one prospect row:firstName/lastNamesplit fromname,extrafields, the token intoken_field, every campaign link pre-tokenized. Campaign identity rides on the link (utm_campaign), not the token — the token is reused across campaigns. Shared by the push endpoint and the workflow step (4658caa97).pushProspects(api_key, campaign_id, prospects)—POST /prospects/bulk?campaignId=in chunks of 500, 60s timeout. ManyReach merges by email (non-destructive), so re-pushing the same list is safe.
Token minting & CSV path
NoxActionUserController._mintCampaignTokens mints via KkTokenModel.ensure({ company_id, email, name }) — idempotent per email (resubmitting returns the same tokens). Emails are lowercased, regex-validated, and deduped; invalid ones come back in skipped. Max 10,000 recipients per batch.
- ManyReach push (
manyreachPush): oneprospect()row per recipient, plus any per-recipient variables sent with the list. - CSV path (
POST /knox/agent-k/campaign-tokens): mints tokens for campaigns sent from any outside tool (recipients need not exist in the CRM) and returns{ email, token }pairs plusskippedfor CSV export.
Workflow step — "Add to ManyReach campaign"
Agent K rules and bulk runs have a manyreach action (AgentKActionRunner._manyreach, 4658caa97; frontend workflow/StepSettings.vue campaign picker from GET …/manyreach/campaigns, options.campaign_id + options.campaign_name so the saved name still shows when ManyReach is disconnected or the campaign is gone). Per lead:
- Skipped
no_emailwithout an email,manyreach_not_connectedwhen the vault has no key. Saving a rule with this step is refused ("Connect ManyReach in Integrations first") unlessvault.status(…, 'manyreach').connected. - No approval queue exists for a campaign add, so a lead the auto-send grid / rule
cold_limitwouldn't let be emailed unasked is skippedcold_limit(reaching cold leads needs cold consent on the rule, like any send); the email gate (DND, suppression) applies. - Mints/reuses a kk token with
source: 'agent_k'keyed on the lead's CRM contact (ghl_contact_idorhubspot_contact_id) + email. - Pushes one
prospect()row withcompany/website/jobPositionextras and the tenant's links. 401/406 → stepfailedmanyreach_key_rejected.
Click stitching
Templates link with the token variable or a pre-tokenized link field. On landing, the widget posts POST /user-session/kk-click (UserSessionController@kkClick), which resolves the token bot-filtered and stitches the click to the person/session — the same mechanism as Agent K's CRM sends. Attribution follows the token's minter (kkTokenSource() in app/lib/trafficSource.js): campaign-token mints (no CRM contact) read as manyreach; tokens minted by the workflow step read as agent_k. See Agent K › kk_token & click stitching.
Related
- Agent K — rules, bulk runs, campaign tokens
- GoHighLevel — Agent K's primary push target
- Integrations Overview · CRM & External Integration