Outreach Source
Run the source stage for one outreach run: turn the run's ICP filters into a sourced list and ingest it idempotently into Twenty. This is a bulk stage. Reconcile every lead through twenty-engine-sync; do not write Twenty directly and do not enrich or send.
References
Read these first:
references/CONTEXT.mdreferences/docs/outreach-operator/run-contract.mdreferences/docs/outreach-operator/tool-map.mdreferences/docs/outreach-operator/control-plane.md
Open when checkpointing to Paperclip or choosing a surface:
references/docs/outreach-operator/workflow.mdreferences/docs/paperclip-operator/cli-contract.mdreferences/docs/paperclip-operator/integration-matrix.md
Process
Follow the bulk-stage pattern in run-contract.md.
- Resume. Read the Run Record. Confirm
source is in the run's stage scope and read its checkpoint.
- If
source is done, stop and report; do not re-source.
- If
running, read its counts and the Twenty segment, and continue from there.
- Done when you can state whether this is a fresh source run or a resume, and the current counts.
- Read source config from the Run Record: ICP slice and filters, source tool, volume and credit caps, and suppression rules.
- Configure and dry-run the source query. Project the result-set size, a small sample, and the credit or cost estimate against caps. Mutate nothing.
- Done when the projected list and its cost are shown and compared to the caps.
- Ask for approval before pulling. The pull is an external-tool action and leads to CRM writes.
- Pull within caps, then reconcile every sourced person into Twenty through
twenty-engine-sync (idempotent match-or-create, additive). Consult eligibility-gate where the per-person verdict decides whether to ingest, reuse, or suppress. Record sourcing provenance on each record.
- Stop and checkpoint as
stopped if a cap or stop condition trips; never exceed a cap to finish the batch.
- Reconcile and checkpoint. Write source counts to the Run Record: sourced, ingested, matched, suppressed or deduped, and errored. Move
source to qa.
- Done when every person from the pull is accounted for in Twenty with provenance, and the counts sum to the pulled total.
- QA gate. Present the ingested batch summary against the run's QA gate. On pass, set
source to done. On fail, set it to revise or stopped with a comment.
Tools
Apollo is the primary source, reached through composio: composio__COMPOSIO_SEARCH_TOOLS with toolkits:["APOLLO"], then composio__COMPOSIO_MULTI_EXECUTE_TOOL over APOLLO_PEOPLE_SEARCH / APOLLO_ORGANIZATION_SEARCH. Confirm the connection with APOLLO_GET_AUTH_STATUS before pulling. A provided CSV imports via grinfi__import_leads_from_file. Ingest to Twenty through twenty-engine-sync. See tool-map.md.
Boundaries
- Bulk stage, not a per-lead loop. Source fills the list and provenance; channel-key enrichment is the enrich stage.
- All Twenty writes go through
twenty-engine-sync. Never write Twenty directly, and never send or spend send credits.
- Honor caps and suppression. Stop at the cap and checkpoint what was reached.
- Approval-gated. Get approval before the external pull and before CRM writes; the dry-run comes first.
- Stay in this run. Source only the run's segment under its filters; do not widen the ICP or start another stage.
1---2name: outreach-source3description: Run the source stage of an outbound-engine run - filtered sourcing (Apollo) into idempotent Twenty ingest, within the Run Record's caps. Use when the operator wants to source or resume sourcing a run's lead list, pull leads matching the ICP filters, or fill a Twenty segment before resolve and enrich. Bulk stage; reconciles every lead through twenty-engine-sync and stops at a QA gate.4---56# Outreach Source78Run the source stage for one outreach run: turn the run's ICP filters into a sourced list and ingest it idempotently into Twenty. This is a bulk stage. Reconcile every lead through `twenty-engine-sync`; do not write Twenty directly and do not enrich or send.910## References1112Read these first:1314- `references/CONTEXT.md`15- `references/docs/outreach-operator/run-contract.md`16- `references/docs/outreach-operator/tool-map.md`17- `references/docs/outreach-operator/control-plane.md`1819Open when checkpointing to Paperclip or choosing a surface:2021- `references/docs/outreach-operator/workflow.md`22- `references/docs/paperclip-operator/cli-contract.md`23- `references/docs/paperclip-operator/integration-matrix.md`2425## Process2627Follow the bulk-stage pattern in `run-contract.md`.28291. Resume. Read the Run Record. Confirm `source` is in the run's stage scope and read its checkpoint.30 - If `source` is `done`, stop and report; do not re-source.31 - If `running`, read its counts and the Twenty segment, and continue from there.32 - Done when you can state whether this is a fresh source run or a resume, and the current counts.332. Read source config from the Run Record: ICP slice and filters, source tool, volume and credit caps, and suppression rules.343. Configure and dry-run the source query. Project the result-set size, a small sample, and the credit or cost estimate against caps. Mutate nothing.35 - Done when the projected list and its cost are shown and compared to the caps.364. Ask for approval before pulling. The pull is an external-tool action and leads to CRM writes.375. Pull within caps, then reconcile every sourced person into Twenty through `twenty-engine-sync` (idempotent match-or-create, additive). Consult `eligibility-gate` where the per-person verdict decides whether to ingest, reuse, or suppress. Record sourcing provenance on each record.38 - Stop and checkpoint as `stopped` if a cap or stop condition trips; never exceed a cap to finish the batch.396. Reconcile and checkpoint. Write source counts to the Run Record: sourced, ingested, matched, suppressed or deduped, and errored. Move `source` to `qa`.40 - Done when every person from the pull is accounted for in Twenty with provenance, and the counts sum to the pulled total.417. QA gate. Present the ingested batch summary against the run's QA gate. On pass, set `source` to `done`. On fail, set it to `revise` or `stopped` with a comment.4243## Tools4445Apollo is the primary source, reached through composio: `composio__COMPOSIO_SEARCH_TOOLS` with `toolkits:["APOLLO"]`, then `composio__COMPOSIO_MULTI_EXECUTE_TOOL` over `APOLLO_PEOPLE_SEARCH` / `APOLLO_ORGANIZATION_SEARCH`. Confirm the connection with `APOLLO_GET_AUTH_STATUS` before pulling. A provided CSV imports via `grinfi__import_leads_from_file`. Ingest to Twenty through `twenty-engine-sync`. See `tool-map.md`.4647## Boundaries4849- Bulk stage, not a per-lead loop. Source fills the list and provenance; channel-key enrichment is the enrich stage.50- All Twenty writes go through `twenty-engine-sync`. Never write Twenty directly, and never send or spend send credits.51- Honor caps and suppression. Stop at the cap and checkpoint what was reached.52- Approval-gated. Get approval before the external pull and before CRM writes; the dry-run comes first.53- Stay in this run. Source only the run's segment under its filters; do not widen the ICP or start another stage.
bbengamin