Skip to main content

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:

ActionRoute
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 listPOST /knox/agent-k/manyreach/links
Push prospects into a campaignPOST /knox/agent-k/manyreach/push
Mint tokens for an external/CSV sendPOST /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)​

FieldNotes
api_keyRemoved from the schema (856f5b145) — the key lives only in the credential vault (provider manyreach, see Routes).
token_fieldProspect custom field the kk token is written to — custom1..custom20 (MANYREACH_FIELD_RE), default custom20
token_field_nameThe 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/lastName split from name, extra fields, the token in token_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): one prospect() 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 plus skipped for 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:

  1. Skipped no_email without an email, manyreach_not_connected when the vault has no key. Saving a rule with this step is refused ("Connect ManyReach in Integrations first") unless vault.status(…, 'manyreach').connected.
  2. No approval queue exists for a campaign add, so a lead the auto-send grid / rule cold_limit wouldn't let be emailed unasked is skipped cold_limit (reaching cold leads needs cold consent on the rule, like any send); the email gate (DND, suppression) applies.
  3. Mints/reuses a kk token with source: 'agent_k' keyed on the lead's CRM contact (ghl_contact_id or hubspot_contact_id) + email.
  4. Pushes one prospect() row with company / website / jobPosition extras and the tenant's links. 401/406 → step failed manyreach_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.