# Outbound Campaigns

<!-- BEGIN GENERATED: guide-map -->
## Guide map

Read only the section needed for the next decision. Line ranges are exact
for this generated runtime target.

| Section | What it covers | Lines |
| --- | --- | --- |
| [Purpose](#purpose) | Scope, ownership, and the central operating question. | 30-39 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 40-44 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 45-54 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 55-70 |
| [Choose A Path](#choose-a-path) | Decision hierarchy for selecting the right capability or provider. | 71-78 |
| [Primary SDK Paths](#primary-sdk-paths) | Operating guidance and contracts for this section. | 79-90 |
| [Supporting References](#supporting-references) | Capability, provider, policy, and runtime guides for this outcome. | 91-102 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 103-120 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 121-133 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 134-146 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 147-163 |
| [Verification](#verification) | Evidence required before reporting success. | 164-172 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 173-183 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 184-193 |
<!-- END GENERATED: guide-map -->

Design, stage, publish, and operate multistep outbound sequences with truthful
audience data and sender capacity.

## Purpose

Outbound Campaigns owns the coordination boundary where audience truth, copy,
sender readiness, sequence structure, schedule, and lifecycle state become one
operable campaign. It ensures the exact reviewed audience and revision are what
the platform stages and activates.

This guide routes the campaign. Child references own detailed authoring,
sender, lifecycle, and approval mechanics.

## Use This When

Use this guide when copy, audience, senders, and sequence lifecycle must work
together. Use `copywriting.md` for copy-only work.

## Do Not Use This For

| Task | Owning Reference |
| --- | --- |
| Finding or enriching an audience without creating a campaign | The matching company or contact outcome guide |
| Drafting or reviewing copy without lifecycle work | `copywriting.md` |
| Connecting or purchasing mailbox capacity | `mailboxes.md` |
| Reading or replying to existing conversations | `inbox-and-replies.md` |
| Running one isolated external send | The owning email or LinkedIn effect guide |

## Mental Model

A campaign is a versioned activation contract, not a collection of editable
screens. Its truth is the intersection of:

- an audience snapshot with stable identity, inclusion rationale, and
  suppression state;
- a reviewed copy revision with complete variable mappings;
- eligible senders with sufficient channel capacity;
- sequence timing, stop rules, and success conditions;
- an explicit lifecycle state from draft through staged, published, active,
  paused, or terminal.

Changes to any one of those inputs can invalidate activation readiness. Preview
proves what would happen; publish and send are separate effects.

## Choose A Path

1. Define the audience contract, sender context, steps, variables, stop rules,
   and success condition.
2. Author and preview before publishing.
3. Prove sender readiness and audience field coverage before activation.
4. Preserve sequence, revision, audience, and run receipts.

## Primary SDK Paths

<!-- BEGIN GENERATED: primary-sdk-paths -->
| Primary function | Choose it when | Required inputs | Returns | Exact contract |
| --- | --- | --- | --- | --- |
| `vf.sequences.create_draft` | Use to create the editable sequence shell before adding audience data or changing workflow behavior. | None | `sequence_detail` | [`sequence_authoring.md`](sequence_authoring.md) · installed SDK: `verbiflow/sequences.py:133-329` |
| `vf.sequences.upload_csv_to_source` | Use when a verified local CSV is the sequence audience and must be mapped, staged, and promoted. | `csv_path`, `sequence_id`, `source_node_id` | `sequence_staging_result` | [`sequences.md`](sequences.md) · installed SDK: `verbiflow/sequences.py:3807-3916` |
| `vf.sequences.update_draft` | Use to revise sequence settings, sender selection, workflow topology, filters, or variants with revision safety. | `sequence_id` | `sequence_detail` | [`sequence_authoring.md`](sequence_authoring.md) · installed SDK: `verbiflow/sequences.py:331-419` |
| `vf.sequences.verify_copy` | Use before saving or publishing copy to verify channel rules and template variables. | `steps` | `copy_verification` | [`sequence_authoring.md`](sequence_authoring.md) · installed SDK: `verbiflow/sequences.py:3682-3728` |
| `vf.sequences.publish` | Use only after audience, copy, sender, and draft checks pass and explicit publication is intended. | `sequence_id` | `sequence_detail` | [`sequences.md`](sequences.md) · installed SDK: `verbiflow/sequences.py:959-1010` |
<!-- END GENERATED: primary-sdk-paths -->

## Supporting References

Open only the child that resolves the next material decision.

| Reference | Use it for | Kind |
| --- | --- | --- |
| [`copy.md`](copy.md) | Grounded outbound drafting, personalization, review, and data contracts. | capability |
| [`senders.md`](senders.md) | Sender identity, mailbox connections, movement, capacity, and delivery readiness. | capability |
| [`sequence_authoring.md`](sequence_authoring.md) | Sequence structure, copy, variables, staging, and audience data contracts. | capability |
| [`sequences.md`](sequences.md) | Sequence staging, publishing, lifecycle, sending, and operational receipts. | capability |
| [`safety.md`](safety.md) | Approval, confirmation, side-effect, purchase, and external-communication boundaries. | policy |

## Preflight

Before authoring or changing a campaign, establish:

- the intended organization, campaign objective, channel mix, and success
  condition;
- the audience source, stable identity key, qualification predicate, and
  suppression requirements;
- the sender identity, channel connection, available capacity, and ownership;
- the required copy variables and their coverage in the intended audience;
- step order, delays, schedules, stop conditions, and reply handling;
- current sequence, draft, revision, audience, and lifecycle identifiers;
- whether the request is draft-only, publish, activation, pause, or another
  customer-visible effect.

Inspect current state before creating a replacement. Resume or amend the same
campaign when it is the user's intended durable object.

## Risk And Side Effects

| Stage | Risk And Boundary |
| --- | --- |
| Design, draft, and preview | Reversible work. Preserve IDs and surface validation failures. |
| Audience staging | Platform write. Verify exact membership and mappings before promotion. |
| Publishing | Customer-visible lifecycle mutation. Require clear intent and preserve the published revision. |
| Activation or sending | External communication. Confirm audience, senders, schedule, and stop rules immediately before the effect. |
| Paid enrichment or capacity changes | Credit or purchase boundary owned by the relevant child guide. |

Retries at the activation boundary can duplicate external effects. Reconcile
the existing operation receipt before issuing another mutation.

## Canonical Operating Pattern

1. Inspect existing campaign, sender, audience, and lifecycle state.
2. Define the audience and variable contracts before writing steps.
3. Author the sequence structure and copy as one coherent draft.
4. Preview source rows, mappings, rendered variants, stop rules, and schedule.
5. Resolve coverage, sender-capacity, suppression, and validation failures.
6. Stage the exact reviewed audience and preserve the resulting identities.
7. Publish or activate only when clearly requested, then verify the resulting
   revision and lifecycle state.
8. Monitor replies, failures, and capacity through their owning operational
   surfaces rather than silently mutating the campaign.

## Data Contracts

Preserve these identities and relationships:

| Record | Required Meaning |
| --- | --- |
| Campaign or sequence | Stable sequence identity, objective, owner, and lifecycle state. |
| Draft and revision | Immutable reviewed content/config version and its validation state. |
| Audience snapshot | Stable row identities, source lineage, qualification, suppression, and mappings. |
| Sender assignment | Sender identity, channel, readiness, capacity, and assignment scope. |
| Schedule and stop contract | Timing, timezone, allowed windows, stop conditions, and reply behavior. |
| Operation receipt | Stage, publish, activate, pause, or send identity with resulting status and counts. |

Never report a campaign as published from a draft identifier, or as activated
from a preview count. Preserve the exact revision and audience generation used
by the effect.

## Verification

Verify rendered messages, variable coverage, audience membership, sender
capacity, lifecycle state, and the exact published revision.

Confirm that suppression and stop rules are active, schedule semantics match
the intended timezone and windows, and the final operation receipt belongs to
the same sequence, revision, audience, and sender set that were reviewed.

## Troubleshooting

| Symptom | Likely Cause | What To Do |
| --- | --- | --- |
| Preview is healthy but publish is rejected | Draft validation, authority, or lifecycle state changed | Re-inspect the same sequence and resolve the reported gate. |
| Rendered messages contain missing values | Audience mapping and copy variables diverged | Measure variable coverage on the staged audience and repair mappings before publish. |
| Audience count changes unexpectedly | Source generation, suppression, or dedupe changed | Compare stable keys and source lineage across preview and stage. |
| Campaign is published but nothing sends | Sender readiness, capacity, schedule, or lifecycle eligibility is false | Inspect each readiness dimension rather than republishing. |
| Duplicate action appears possible after a timeout | The effect may have succeeded before the response failed | Reconcile the operation receipt and current state before retrying. |
| Replies continue after the intended stop condition | Reply classification or stop rule is not bound to the active revision | Inspect the campaign's active stop contract and reply state. |

## Related References

| If You Are Doing This | Read Next |
| --- | --- |
| Grounded copy and personalization | `copy.md` and `copywriting.md` |
| Sequence structure, variables, and staging contracts | `sequence_authoring.md` |
| Publish, activation, and lifecycle operations | `sequences.md` |
| Sender identity and capacity | `senders.md` and `mailboxes.md` |
| Approval and external-effect boundaries | `safety.md` |
| Reply triage after launch | `inbox-and-replies.md` |
