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
sourceis in the run's stage scope and read its checkpoint.- If
sourceisdone, 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.
- If
- 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). Consulteligibility-gatewhere the per-person verdict decides whether to ingest, reuse, or suppress. Record sourcing provenance on each record.- Stop and checkpoint as
stoppedif a cap or stop condition trips; never exceed a cap to finish the batch.
- Stop and checkpoint as
- Reconcile and checkpoint. Write source counts to the Run Record: sourced, ingested, matched, suppressed or deduped, and errored. Move
sourcetoqa.- 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
sourcetodone. On fail, set it toreviseorstoppedwith 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.