segment-builder

---
name: segment-builder
description: Splits your customer list into a small number of segments built from what people actually did, with the lawful basis, the transparency wording and the size of each one written down beside it. Use when you are sending the same email to everybody and it is working less every time.
---

# Stop sending everyone everything, and be able to say why each group got what it got

You give this whatever records what your customers did: a till export, a booking-system CSV, an online ordering report, a loyalty spreadsheet, or the three of them that do not agree with each other. You get back a small set of segments defined by behaviour you can point at, the count in each one, the lawful basis each segment can be emailed under, the sentence you have to put on your sign-up form before you use it, and a named list of the segments the skill refused to build and the reason it refused.

## What it does

1. **Reconcile the sources before you segment anything, and keep the join key visible.** A pub with a booking system, a card terminal and a loyalty app has three customer lists and one customer. Pick the join key deliberately: lowercase email is usually the only stable one, because names are typed differently every visit and mobile numbers are shared across a household. Record how many rows each source contributed, how many matched, and how many did not. Rows that could not be matched are not discarded, they are counted and reported, because a segment built from the two systems that happened to join is a segment that quietly excludes everyone who only ever paid by card.

2. **Build the behaviour columns first, and only from things that actually happened.** Three columns carry most of the value: how many days since this person last spent money with you, how many separate visits they have made in the period, and what they have spent in total across the period. That is recency, frequency and monetary value, the RFM method, and it has the property that matters here, which is that every value in it is a fact from your own till rather than a guess about a person. Add a fourth if you have it and it is factual: which day of the week they usually come. Do not add estimated lifetime value, propensity scores or anything else the data does not contain.

3. **Refuse to build the segments that quietly become special category data.** This is where a hospitality list goes wrong, and it does not look dangerous at the time. A "vegan menu" segment built from dietary notes on bookings can reveal religious or philosophical belief. A "gluten free" or "nut allergy" segment is data concerning health. The ICO's test is not about how the data was labelled but about what you intend to do with it: you are processing special category data where "your processing intends to make an inference linked to one of the special categories of data" or "you intend to treat someone differently on the basis of inferred information linked to one of the special categories of data", and this applies "regardless of how confident you are that the inference is correct". Its guidance adds that if you profile to infer "ethnicity, beliefs, politics, health status (condition or risks), sexual orientation or sex life", you need an Article 9 condition, and the ICO's direct marketing guidance says that for marketing "You should have 'explicit consent'" because it is unlikely another condition applies. So: an allergy note stays in the kitchen system where it belongs and does not become a marketing segment, unless the customer has separately and explicitly agreed to be emailed on that basis.

4. **Set a minimum segment size and enforce it.** Below roughly fifty people a segment is not a segment, it is a handful of named individuals who will recognise themselves in the email, and the effort of writing separate copy for it is never repaid. Merge anything smaller into its nearest neighbour and say in the output that you did. Four to six segments is the working number for a single-site venue. Somebody who builds fourteen writes fourteen emails once and then writes none.

5. **Write the lawful basis on the segment, not on the campaign.** Each segment gets one of two labels. Specific consent to marketing email. Or the soft opt-in, which under regulation 22(3) of PECR needs the details to have been obtained "in the course of the sale or negotiations for the sale of a product or service to that recipient", the marketing to be of "similar products and services only", and a simple means of refusing to have been given at collection and in every message since. A segment that mixes the two is fine. A segment containing anyone who fits neither is not, and those rows go to a separate list headed "no lawful basis, do not email". The ICO's guidance on the soft opt-in is explicit that it "does not apply to prospective customers or new contacts (eg from bought-in lists)".

6. **Separate the suppression list from the screening list and never confuse the two.** A suppression list holds people who told you to stop. A screening list holds people you have decided not to include this time. The ICO draws the line sharply: "Unlike a suppression list, you don't use a screening list to comply with someone's objection to direct marketing. Use of a screening list is processing for direct marketing purposes." Practically, that means the suppression list is checked against every segment before any send and its exclusions are absolute, while a screening decision is yours to change. Report both counts separately so that a dropping open rate can be traced to the right cause.

7. **Write the transparency sentence the segments require, and put it where people give you their details.** You cannot analyse purchase history to decide what somebody receives and say nothing about it. The ICO's own worked example of adequate wording is one sentence: "We will use your purchase history to tell you about our offers and products that we think you will be most interested in." Its guidance adds the test for whether your wording is honest enough, which is that "If you find it difficult to explain what you want to do, or you don't want to tell people because you think they might object, this is a sign that you should rethink your intended marketing activity." Output the exact sentence for this venue's segments so it can be pasted onto the booking form and the sign-up box.

8. **Attach the message to the segment, one line each, before anyone writes an email.** For each segment: what these people did, what you want them to do next, and the single offer or piece of news most likely to cause it. A group who came four times in ninety days does not need a discount, they need to know about the new menu first. A group who came once eleven months ago needs a reason to remember you exist. If two segments end up with the same line, they are the same segment, and the output should merge them rather than pretending otherwise.

9. **Print the segment table with counts, and keep the refusals underneath it.** Columns: segment name, rule in plain words (for example "spent money in the last 60 days, three or more visits"), count, percentage of the emailable list, lawful basis, message line, and the date the underlying export was taken. Below it, a table headed "not built, and why", listing every segment that was requested or suggested and refused: too small, no lawful basis, or would have inferred special category data. That second table is the one to keep, because it is the record of the decisions that would otherwise be re-made and made differently in six months.

## Then it checks

1. Every segment row shows a count, the percentage of the emailable list it represents, and the date the source export was taken, and the counts of all segments plus the excluded rows add up to the total rows read.
2. No segment is defined by, or derived from, a dietary requirement, an allergy, an accessibility note, a health note, a religious observance or a name-based assumption about origin, and any such request appears in the "not built, and why" table.
3. Every segment carries a lawful basis of `consent` or `soft-opt-in-PECR-22(3)`, and every row that fits neither appears in the separate "no lawful basis, do not email" list with the reason.
4. No segment holds fewer than the stated minimum, and every merge performed to reach that minimum is named in the output.
5. The suppression count and the screening count are reported as two separate numbers, and every segment has been screened against the suppression list before its count is stated.
6. The output contains one transparency sentence, written for this venue, describing the analysis actually being done, and no segment relies on analysis that sentence does not cover.

Any check fails: name it, redo that step once. Failed twice: say what is wrong and stop.

## Rules
- Public information only.
- Never invent a fact, a number or a quote.
- Anything sent in someone's name says whose name it is.
- Never build a segment from an inference when the fact itself is available. "Ordered the set menu three times" is a fact from your till. "Probably price sensitive" is a story about a person, and the ICO warns that profiling "might perpetuate stereotypes if you make general assumptions based on the information you hold".
- Never quote a benchmark, an industry average or an expected open rate at the owner. The only figures in the output are counted from this venue's own export, and every one of them shows the date it was counted.
- Never let a segment survive the loss of its lawful basis. If someone unsubscribes they leave every segment at once, not just the one that sent the email, because the right to object under data protection law covers the profiling related to the marketing as well as the marketing itself.
- This output is a working document prepared for the owner's solicitor or data protection adviser to check before it is used. It applies published regulator guidance to a customer list; it is not legal advice on your obligations under PECR or the UK GDPR.

## Built from
- Information Commissioner's Office, "What is special category data?", https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/lawful-basis/special-category-data/what-is-special-category-data/, latest update shown as 9 April 2024, read 14 September 2026: the inference test and the profiling sentence quoted in step 3, which is the whole basis of the second check.
- Information Commissioner's Office, "Collect information and generate leads", https://ico.org.uk/for-organisations/direct-marketing-and-privacy-and-electronic-communications/direct-marketing-guidance/collect-information-and-generate-leads/, no publication date shown on the page, read 14 September 2026: the profiling requirements and the verbatim transparency example in step 7, and the stereotyping warning in the rules.
- Information Commissioner's Office, "Respect people's preferences", https://ico.org.uk/for-organisations/direct-marketing-and-privacy-and-electronic-communications/direct-marketing-guidance/respect-peoples-preferences/, no publication date shown on the page, read 14 September 2026: the suppression list versus screening list distinction quoted in step 6.
- Information Commissioner's Office, "Plan direct marketing", https://ico.org.uk/for-organisations/direct-marketing-and-privacy-and-electronic-communications/direct-marketing-guidance/plan-direct-marketing/, no publication date shown on the page, read 14 September 2026: the explicit consent position for special category marketing quoted in step 3.
- The Privacy and Electronic Communications (EC Directive) Regulations 2003, regulation 22, https://www.legislation.gov.uk/uksi/2003/2426/regulation/22, made 18 September 2003, read 14 September 2026: the verbatim soft opt-in conditions that the lawful-basis label in step 5 is checked against.
- rsquaredacademy, "rfm: Customer Segmentation using RFM Analysis", https://github.com/rsquaredacademy/rfm, no publication date shown on the page, read 14 September 2026: the recency, frequency and monetary definitions used in step 2.

# Customer segment builder

## You are given
One or more customer or transaction exports from a UK hospitality business: a till report, a booking-system CSV, an online ordering export, a loyalty spreadsheet. Column names vary and the files may not agree. You may also be given a suppression list of email addresses, a consent log showing who opted in to marketing email and when, and a stated minimum segment size (default 50).

## Produce
Write these files into `./segments-output/`:

1. `segments.csv` with exactly these columns: `segment_name`, `rule_in_words`, `count`, `pct_of_emailable`, `lawful_basis`, `message_line`, `export_date`. `lawful_basis` is `consent`, `soft-opt-in-PECR-22(3)` or `mixed`.
2. `customers_segmented.csv` with columns: `email_lower`, `segment_name`, `days_since_last_spend`, `visits_in_period`, `total_spend_gbp`, `usual_day`, `lawful_basis`, `source_files`. One row per customer.
3. `no-lawful-basis.csv`, same columns as `customers_segmented.csv` plus `reason`, holding every customer who matched neither consent nor soft opt-in.
4. `not-built.csv` with columns `requested_segment`, `refusal_reason`. Refusal reasons are exactly one of `below minimum size`, `no lawful basis`, `would infer special category data`.
5. `reconciliation.txt`: rows read per source file, rows joined, rows that joined from only one source, suppression matches removed, screening exclusions applied, and the final emailable total. Suppression and screening counts must be two separate numbers.
6. `transparency-sentence.txt`: one sentence describing the analysis actually performed, written for pasting onto a sign-up form.

## Rules
- Join on lowercase trimmed email address only. Never join on name or phone number.
- Build segments only from: days since last spend, number of visits, total spend, and usual day of week. Never from a dietary note, allergy note, accessibility note, health note, religious observance, nationality, title or a name-based assumption. Any such field encountered is dropped and logged as a `would infer special category data` row in `not-built.csv`.
- Produce between four and six segments. Merge any segment below the minimum size into its nearest neighbour and record the merge in `reconciliation.txt`.
- Remove every suppression-list match from every segment before counting.
- Never write a benchmark, an industry average or an expected open or click rate into any file. Every number must be counted from the supplied data.
- Do not send any email, call any marketing API, or contact any person. You produce files only.
- Money is in pounds with two decimals. Dates are DD/MM/YYYY.

## Return
Print the absolute path of each file written, the segment names with their counts, the emailable total, the suppression count and the screening count as separate figures, and every row of `not-built.csv`. If the totals in `reconciliation.txt` do not add up to the rows read, say so plainly rather than adjusting a number to make them balance.