Skip to main content

Communications: lists explain themselves, audience breakdown, exclusion lists, template lint and starters

Motorical

Everything here is additive: existing requests and responses keep working.

  • Lists explain themselves. A list has a description, a kind, a source_label and a recorded provenance. GET /lists/{id} returns the whole card with counts computed on every read (member_count, eligible_count, unsubscribed_count, bounced_count, suppressed_count), the campaigns that use it and whether it is a one-time snapshot. PATCH /lists/{id} is now a partial update.
  • Know who will get it, and why not the others. compile and schedule return an audience breakdown whose included figure is the recipient count, with the people left out grouped by reason. A campaign with nobody left is refused with EMPTY_AUDIENCE. The report carries sync, so a zero that only means "not delivered to the report yet" is not read as a failure.
  • Add contacts as JSON. POST /lists/{id}/contacts/bulk takes up to 500 contacts, answers for every row, never adds back people who unsubscribed or bounced, and supports dry_run.
  • Build lists from lists. POST /lists/derive (union, intersection, difference) records how a list was made; GET /lists/compare shows the overlap of two lists; GET /lists/{id}/relations and GET /map show how lists, campaigns and templates connect.
  • Exclusion lists. A campaign can take exclude_list_ids: people on those lists are never sent to. A list that a campaign excludes can no longer be deleted (409 LIST_IN_USE, which also now protects lists used by unfinished campaigns).
  • Templates. POST /templates/preview shows what a recipient will see, with and without a name. GET /templates/rules, POST /templates/lint, /fix and /check-links give a rulebook, findings with ready fixes (nothing is saved until you PATCH) and a link check. Templates have a description, a kind and derived_from, and POST /templates/{id}/duplicate makes a copy that remembers its parent. Campaigns have a description.
  • Brand kit and starters. GET/PATCH /settings/brand-kit stores your sender name, postal address, colours and font once. GET /templates/starters lists seven starters, POST /templates/starters/{key}/render shows one without saving, and POST /templates/from-starter saves it as a normal template.
  • Readiness. GET /readiness names the first thing missing before a campaign can be sent.

Documentation changed