---
name: pombo-campaigns
description: Draft a one-off email campaign in Pombo end to end. Pick the audience, attach a template, set the sender, and hand a review link back to the user. Use for a single send to a list or segment (an announcement, a newsletter, a promo), not for an automated multi-step flow.
---

# Drafting a campaign in Pombo

A campaign is one send to a list or a segment. This skill takes it from a brief
to a draft the user reviews. You never send it. Sending and scheduling stay a
click in Pombo. For an automated multi-step flow, use `pombo-events` and build a
sequence instead.

## 1. Get the audience right first

- A **segment** (dynamic, re-evaluated at send): `list_segments` to find one,
  or `create_segment` and `preview_segment` to build and size one. Prefer this.
- An **explicit list**: exact contact emails or ids. Use when the user names
  the recipients.
- `count_contacts` or `preview_segment` to tell the user how many people this
  reaches before drafting. A surprising number usually means the filter is
  wrong.

## 2. Have or make the template

- `list_templates` for an existing one, or `create_template`
  (`category: "full_template"`) in the user's brand voice.
- `validate_template`, then `preview_template` for a link the user can open on
  their phone. Nothing is sent and nothing counts against the cap.
- Iterate on the preview link, not by test-sending repeatedly.

## 3. Create the campaign in one call

`create_campaign` takes the name, the sender, the template, and the audience
together:

```
create_campaign(
  name: "March pricing update",
  from_name: "Acme",
  from_email: "hello@mail.acme.com",   # must be on a verified sending domain
  template_id: "<uuid>",               # also sets template_version and subject
  segment_id: "<uuid>"                 # OR contact_emails: [...] OR contact_ids: [...]
)
```

- Pass at most one of `segment_id`, `contact_emails`, `contact_ids`.
- If you pass `template_id` and no `subject`, the campaign takes the template's
  subject. Set `subject` explicitly to override.
- It is always created as a draft. The result includes a `review_url` and says
  plainly that nothing was sent.
- `contact_emails` are resolved to contacts. Unknown or suppressed addresses
  are skipped and reported in the result. Check the skipped count against what
  the user expected.

## 4. Adjust if needed

- `get_campaign` to read it back with its stats surface.
- `update_campaign` for a partial change: rename, change the sender, swap the
  template, or replace the audience. Works only while the campaign has not gone
  out.
- `list_campaigns` (optionally filtered by status) to find drafts.
- `delete_campaign` removes a draft that has never sent. A campaign that has
  sent anything is kept for its reporting. To clear it from the list, leave it.

## 5. Hand it back

Give the user the `review_url`. Tell them:

- how many people it reaches and which segment or list,
- the subject line and from address,
- that they send or schedule it from Pombo. You have not and cannot.

Optionally `send_test_email` to an address inside the organization so they see
the real rendering first. That one test counts against the weekly cap.

## Done when

A draft campaign exists with the right audience, template, subject, and sender,
and the user has the review link. The send itself is theirs.