Campaigns

Send list data in, then design a canvas that checks attributes, waits, and sends a published template.

Open Campaigns at /app/marketing/campaigns, name the campaign, and choose a verified from address. The list is one of the Lists on Audience. A published template is required before a send block can use it.

Data integrations

A new person enters an active campaign when your app posts them to the list. POST /api/events uses the project's default list, or the audience_id in the body. POST /api/audiences/:id/events pins the list in the path. Send a Bearer API key. email is required. occurred_at is an ISO-8601 time. Omit it and Pigeon uses the time of the request. An older occurred_at is ignored.

shell
curl -X POST https://pigeonfs.com/api/events \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.net","audience_id":"3c91aa00-1b44-4e0c-9d77-11a0b3c8d301","occurred_at":"2026-11-06T12:00:00Z","consented":true,"attributes":{"last_access":"2026-11-06T12:00:00Z","plan":"trial"}}'

attributes.last_access is an ISO-8601 time. Other attribute names start with a letter and then use letters, digits, and underscores, up to 40 characters. You can store 40 of those keys. A string value can be 500 characters. Numbers and true or false are stored as themselves. consented false, or unsubscribed true, keeps the person on the list and leaves marketing_subscribed false, so they are not enrolled or emailed.

  • A new email on that event call is added to the list and walked through every active campaign for that list immediately.
  • The same email posted again updates attributes. It does not start the campaign a second time.
  • Repeat X-Pigeon-Idempotency-Key to replay the same result. Optional HMAC-SHA256 uses X-Pigeon-Timestamp and X-Pigeon-Signature.
  • POST /api/audiences/:id/contacts creates or merges one person by email or external_id. POST /api/audiences/:id/imports accepts up to 1,000 people. Copying checked people from Audience does the same merge. Those paths fill the list. The people join a campaign when you activate one that enrolls everyone already on the list.
shell
curl -X POST https://pigeonfs.com/api/audiences/3c91aa00-1b44-4e0c-9d77-11a0b3c8d301/contacts \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.net","external_id":"usr_1","attributes":{"last_access":"2026-11-06T12:00:00Z","plan":"trial"}}'

Design a campaign

  1. Add an Entry. Choose the list. Enroll when is either everyone already on the audience, plus new webhook signups, or New contact added (webhook signup).
  2. Add a Condition when the next mail depends on an attribute. Set the attribute, the check, and the value. Connect both the yes output and the no output. Each path still ends in a send.
  3. Add a Wait when the next mail should happen later. The duration is a number of hours. Wait blocks resume on the next scheduler tick.
  4. Add a Send and choose a published template. Save the draft. Activate when the canvas says Ready to activate.
  5. Pause stops new signups from entering and holds waits. Resume makes the campaign active again. Save the canvas while the campaign is still a draft.

A condition check is one of these:

  • Older than N days. A missing or unreadable time matches this check.
  • Newer than N days. A missing or unreadable time does not match this check.
  • Equals, or Does not equal. Letter case is ignored.
  • Exists, or Does not exist. These look only at whether the attribute is present.
  • Greater than, or Less than. These compare numbers.

Every block is connected, connections do not form a cycle, and every path ends in a send. The from address is a verified address. Campaign sends use a separate monthly and daily cap on the project. Put {{unsubscribe}} on the template so a reader can leave the list.

Canvas

Drag the empty canvas to move the view. Drag a block and the wire follows it. Drag from an output onto another block, or click an output and then the block, to connect. A condition has a yes branch and a no branch. The plus and minus buttons on the canvas zoom in and out. Hold Control or Command and use the wheel while the pointer is over the canvas to zoom as well. A plain wheel moves the view.

Use cases

Welcome a new signup. Set the entry to New contact added. Connect it to a Send that uses your published welcome template. When your app creates the account, POST /api/events with the email and consented true. The walk runs as soon as that new email is stored.

Write to a quiet account. Set the entry to everyone already on the list, plus new signups. Add a condition on last_access, Older than N days, value 14. The yes branch sends a published win-back template. The no branch sends a short published note, because each path ends in a send. Post attributes.last_access when the person opens the product, using the event call or the contact call.

Split by plan. Add a condition on plan, Equals, value trial. The yes branch sends the trial template. The no branch sends the template for everyone else. Put plan on the event or the contact call. A trial account sends the value trial.

Publish a template Lists and signup events Audience and event routes