promo-calendar

---
name: promo-calendar
description: Builds a twelve-month email calendar out of dates that genuinely exist - bank holidays read from GOV.UK, your own trading dates, and local events verified on the organiser's own website - with the lead time, the stock dependency and the closing date attached to each one. Use when you need reasons to email that are not invented.
---

# A year of real reasons to email, on dates you can prove exist

You give this your trading pattern, your quiet weeks, your own anniversaries, and whatever local events you think are coming. You get back a twelve-month calendar where every entry carries a date that has been checked against a primary source, the day you have to start preparing it, the stock or staffing it depends on, the closing date that goes in the email, and a one-line reason a customer would care. Anything that could not be verified is listed separately as unverified rather than quietly dropped or quietly kept.

## What it does

1. **Load the bank holidays from GOV.UK and nowhere else, and load the right division.** The machine-readable list at https://www.gov.uk/bank-holidays.json splits into `england-and-wales`, `scotland` and `northern-ireland`, and the three do not match. For 2026 the England and Wales list is New Year's Day 1 January, Good Friday 3 April, Easter Monday 6 April, Early May 4 May, Spring 25 May, Summer 31 August, Christmas Day 25 December and Boxing Day substitute day 28 December. Scotland's 2026 list has no Easter Monday at all, puts the Summer bank holiday on 3 August rather than 31 August, adds 2nd January, St Andrew's Day on 30 November, and a World Cup bank holiday on 15 June. A Glasgow bar planning around an English August bank holiday has planned around nothing. Read the division that matches where the venue is and write the source and the date read beside every entry.

2. **Check every movable feast rather than assuming last year's date.** Easter moves, and with it Good Friday, Easter Monday, Shrove Tuesday, Mothering Sunday and the whole of Lent. In England and Wales, Good Friday falls on 3 April in 2026 and on 26 March in 2027, so an Easter menu email that goes out in the same week two years running will be eight days out the second year. Subtract each date from today before it goes on the calendar. Anything in the past is not an opportunity, and the calendar says so in words rather than dropping the row.

3. **Put the venue's own dates on before anybody else's.** These are the entries nobody else can copy and the ones customers actually respond to: the date you opened, the date the new menu starts, the head chef's first anniversary, the week the garden opens, the day the refurbishment finishes, the last Sunday lunch before the kitchen closes for its deep clean. Each one needs a real date you can point at, not "sometime in spring". A calendar built only from national holidays is the same calendar as every competitor within four miles, and it arrives in the same inbox on the same morning.

4. **Verify every local event on the organiser's own website, not on a listings site.** Festivals, race meetings, school fetes, market days, football fixtures and university term dates all move, and the aggregators do not update. Fetch the organiser's own domain, read the date there, and record the URL and the date you read it. Where the organiser's page and a venue's page disagree, record both and mark the entry unverified rather than picking the convenient one. Where no primary source exists, the entry goes on the unverified list and the owner is told which phone call settles it.

5. **Set the frequency cap before filling the calendar, not after.** Decide how many marketing emails a customer may receive in a month and hold the line. The constraint is not taste, it is the law and the mailbox providers: every message must carry "a simple means of refusing", and each extra send is another chance to lose the address permanently. Build the calendar to that cap, then rank the entries. When two land in the same week, one gets promoted and the other gets moved or cut, and the calendar records which and why so the decision is not made again next year from scratch.

6. **Attach a lead time and a dependency to every entry.** The date in the calendar is the send date. Behind it sits the date the photography has to exist, the date the menu has to be signed off, the date the stock has to be ordered and the date the rota has to cover it. Write all four. An email offering a five-course tasting menu that the kitchen cannot staff is worse than no email, because CAP rule 8.10 requires a promoter to demonstrate "that they have made a reasonable estimate of the likely response and either that they were capable of meeting that response or that consumers had sufficient information, presented clearly and in a timely fashion, to make an informed decision on whether or not to participate", and rule 8.9 is blunt that "Phrases such as 'subject to availability' do not relieve promoters of their obligation to do everything reasonable to avoid disappointing participants".

7. **Give every promotional entry a real closing date, and never a manufactured one.** CAP rule 8.17.4.a requires "a prominent closing date, if applicable, for purchases and submissions of entries or claims", and rule 8.17.4.e allows a closing date to be changed only where "unavoidable circumstances beyond the control of the promoter make it necessary". The other half matters more. Rule 3.30 states that marketing communications "must not falsely state that a product, or the terms on which it is offered, will be available only for a limited time to deprive consumers of the time or opportunity to make an informed choice", and it is marked in the Code as reflecting a prohibited practice. "Last chance" on an offer you intend to run again in six weeks is the exact thing that rule names. If the offer is open-ended, say it is open-ended and do not put a countdown on it.

8. **Write the one-line reason a customer would care, and reject any entry that cannot have one.** Not "National Pie Week is coming" but "the pie and a pint is £12 on Thursdays through pie week, and we only do eighty". If the only thing you can say about an entry is that the date exists, the entry is a reason for you to email rather than a reason for them to read, and it comes off the calendar. This is the filter that removes most of the invented occasions, because almost none of them survive it.

9. **Output the calendar as a table sorted by send date, with the unverified list kept separate underneath.** Each row: send date, occasion, division or source, the one-line reason, the offer if any, the closing date, the lead-time date, the dependency, the owner and the status. Underneath it, a second table headed "unverified, do not plan around these" holding every date that could not be confirmed on a primary source, with the URL that was tried and what it said. Keeping the two apart is the whole value, because a calendar that mixes eight confirmed dates with four guesses is a calendar nobody can trust any part of.

## Then it checks

1. Every bank holiday entry names the division it was read for (`england-and-wales`, `scotland` or `northern-ireland`) and the date it was read from GOV.UK, and no entry mixes divisions.
2. Every date in the calendar is later than today's date, and any date that turned out to be in the past appears in the output as an explicit "this has already happened" line rather than being deleted.
3. Every local event entry carries the organiser's own URL and the date that page was read, or sits in the unverified table, and no entry is sourced only from a listings site or an aggregator.
4. The count of marketing emails in any calendar month does not exceed the frequency cap set in step 5, and the calendar shows the count per month so the cap can be checked by eye.
5. Every promotional entry has either a stated closing date in DD Month YYYY form or an explicit "no closing date, open-ended" marker, and no entry uses "last chance", "ends soon" or "limited time" without a date behind it.
6. Every entry has a one-line customer reason and a named dependency, and no row reads "TBC", "as usual" or "same as last year".

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 carry a date over from last year's calendar without re-checking it. Easter, Mothering Sunday, half terms, race meetings and bank holiday substitutes all move, and a date that was right once reads exactly like a date that is right now.
- Never put an occasion on the calendar because a marketing website says it exists. National days invented by a brand to sell something are a reason for that brand to email, not for you, and the step 8 filter exists to catch them.
- Never manufacture urgency. A deadline you intend to extend is the practice CAP rule 3.30 names, and a customer who notices the same "final week" twice stops believing every price you quote.
- This output is a working document prepared for the owner's accountant or solicitor to check before any promotion is published. It assembles dates and states what published advertising rules say; it is not legal advice on whether a particular promotion complies.

## Built from
- GOV.UK, "UK bank holidays", https://www.gov.uk/bank-holidays.json, no publication date shown on the page, read 14 September 2026: the machine-readable bank holiday list, the three separate divisions, and every 2026 and 2027 date quoted in steps 1 and 2, which is what step 1 is built on.
- Committee of Advertising Practice, "08 Promotional marketing", https://www.asa.org.uk/type/non_broadcast/code_section/08.html, no publication date shown on the page, read 14 September 2026: rules 8.9 and 8.10 on availability behind step 6, and rule 8.17.4 on closing dates behind step 7.
- Committee of Advertising Practice, "03 Misleading advertising", https://www.asa.org.uk/type/non_broadcast/code_section/03.html, no publication date shown on the page, read 14 September 2026: rule 3.30 on falsely limited availability, which is the whole of the second half of step 7 and the third bespoke rule above.
- Information Commissioner's Office, "Electronic mail marketing", https://ico.org.uk/for-organisations/direct-marketing-and-privacy-and-electronic-communications/guide-to-pecr/electronic-and-telephone-marketing/electronic-mail-marketing/, no publication date shown on the page, read 14 September 2026: the opt-out-in-every-message requirement that makes the frequency cap in step 5 a compliance question and not a stylistic one.
- 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 "simple means of refusing ... at the time of each subsequent communication" quoted in step 5.

# Twelve-month promotional email calendar builder

## You are given
A plain-text brief for one UK hospitality venue containing: the town and nation the venue sits in, the venue's own fixed dates (opening anniversary, menu changes, closures, garden opening), the quiet weeks it wants to fill, the maximum number of marketing emails a customer may receive per calendar month, and optionally a list of local events with the organiser's website address. You have network access.

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

1. `promo-calendar.csv` with exactly these columns: `send_date`, `occasion`, `category`, `customer_reason`, `offer`, `closing_date`, `lead_time_date`, `dependency`, `owner`, `source_url`, `source_read_date`, `status`. Dates are DD/MM/YYYY. `category` is one of `bank-holiday`, `venue-own`, `local-event`, `seasonal-trade`. `closing_date` is either a date or the literal text `open-ended`. `status` is `confirmed` or `unverified`.
2. `unverified.csv`, the same columns, holding every entry whose date could not be confirmed on a primary source, plus a final column `what_was_tried` naming the URL fetched and what it returned.
3. `monthly-counts.csv` with columns `month`, `emails_planned`, `cap`, `over_cap`. `over_cap` is `yes` or `no`.
4. `sources.txt`, one line per URL fetched, with the date fetched and the HTTP status.

## Rules
- Read bank holidays only from `https://www.gov.uk/bank-holidays.json`. Select the division matching the venue's nation: `england-and-wales`, `scotland` or `northern-ireland`. Never merge divisions. Put the division in `source_url` alongside the URL.
- Verify each local event by fetching the organiser's own domain. A listings site, aggregator or search snippet is not a source: such an entry goes to `unverified.csv`.
- Drop no date silently. Any date earlier than today goes into `unverified.csv` with `what_was_tried` reading `date has already passed`.
- Never exceed the stated monthly cap in `promo-calendar.csv`. Where a month would exceed it, move the lowest-ranked entry to a neighbouring month and record the move in `what_was_tried` on a matching row in `unverified.csv`.
- Every `confirmed` row must have a non-empty `customer_reason` and a non-empty `dependency`. Rows that cannot get both become `unverified`.
- Never write `TBC`, `last chance`, `ends soon` or `limited time` into any field.
- Do not send any email or contact any person. You produce files only.

## Return
Print the absolute path of each file written, the number of confirmed rows and unverified rows, any month where `over_cap` is `yes`, and the full list of URLs fetched with their status codes. If `https://www.gov.uk/bank-holidays.json` could not be reached, say so and write no `bank-holiday` rows at all.