Newsletter segments (add-on)

Every saved segment, with the count of people it is about, when that count was taken, and how many campaigns are pointed at it. The count is cached and refreshed by the worker every fifteen minutes or so, so read counted_at beside it before quoting the number — and call count_segment when the answer has to be true right now. A segment with a list_id is about the people subscribed to that list who also match its conditions; a segment with none is about everybody the store may mail. Start here when somebody asks who a campaign would reach.

One segment with its full condition document, its cached count and the list it is narrowed to. The document has three containers — all, any and none — and each holds conditions of the form {field, op, value}. Read get_segment_vocabulary to find out what the fields mean before writing one.

Every field a segment condition may name, with its type, the operators it accepts, the group it belongs to and — for the fields that are chosen from a list — the options themselves. This is the reference for writing a condition document: a field this does not name, or an operator a field does not declare, is refused both when the segment is saved and when it runs. Some fields come from other add-ons and are only here when those add-ons are installed, so read this rather than assuming a fixed list.

Answer a condition document straight away: how many people match it, ten of them, and how many matched but cannot be mailed — suppressed, gone from the list, or never confirmed. Nothing is stored. This is the right tool for "how many people would that reach?", and the right thing to run before creating a segment, because a document that matches nobody is much easier to fix before a campaign is pointed at it. Pass list_id to require that people are also subscribed to that list.

Save a condition document under a name. Run preview_segment first and say what the count came to — a segment saved without anybody looking at what it matches is a campaign audience nobody has checked. The definition is validated against the vocabulary as it is saved and again every time it runs, so a field that goes away with an add-on is a refusal rather than a quietly smaller audience. The count is left empty until the worker takes it, which is within about fifteen minutes.

Edit a segment's name, description, list or conditions. Changing the conditions or the list clears the cached count, because the old number is the answer to a different question — the screens say "not counted yet" until the worker takes a new one. Every draft and scheduled campaign pointed at this segment will use the new definition when it starts, so check what is using it first.

Remove a segment. Refused, with the campaigns named, while any draft or scheduled campaign is still pointed at it — those campaigns have to be given a different audience first. A campaign that has already sent keeps its record of who received it in the sends table, so deleting the segment it used takes nothing away from the history.