Skip to content

Plan: email reminders for deadlines ​

Status: plan, awaiting the Product Owner's approval (QD-21, QD-22). It includes the Product Owner's single-mailbox condition. No code yet.

Why ​

SPEC-004's heads-up only reaches someone who opens a conversation. FEAW's confirmation statement went overdue on 7 Sep 2026 unnoticed. Reminders must arrive whether or not anyone talks to GetMy Books. Moves SM-1. This delivers SPEC-001 S6 and the email half of CAP-02.3, and is written up as a new scenario set in SPEC-004 (S7 onward) once approved.

What gets sent ​

  • Every obligation deadlines_upcoming already knows: Companies House accounts and confirmation statement, VAT returns, Corporation Tax payment and CT600, for each company.
  • Thresholds: 30, 14, 7 and 3 days before the due date, as SPEC-001 S6 says; then on the day; then weekly while overdue (Companies House overdue items, and HMRC items until 13 months after as "check it was done").
  • To: every person with access to that company (today Rob and Fraser for FEAW), from entity_access (QD-22 recommends this).
  • Content: company, what is due, period, due date, days left or overdue, and where to file (gov.uk link). No amounts, no bank or VAT figures, so an email that goes astray leaks nothing financial. Plain text and simple HTML.
  • One email per person per day, listing every item that crossed a threshold that day, rather than one email per item.

Never twice ​

  • A table reminder_sent under RLS: entity_id, principal_id, obligation_key (company number or VRN, obligation kind, period end), due_date, threshold (30d, 14d, 7d, 3d, due, overdue-week-N), sent_at. Unique on (entity_id, principal_id, obligation_key, due_date, threshold).
  • The row is written in the same transaction that claims the send, before the email goes out; a failed send is marked and retried the next run, so a crash can't send twice and a failure isn't lost.
  • If a due date moves (Companies House extends it), the key changes and the new date gets its own thresholds.

When it runs ​

  • Once a day at 08:00 Europe/London, inside the deployed app on the NAS: a small scheduler in src/web/ entry that calls a pure dueReminders(today, obligations, sent) function in src/rules/. Restarts are harmless because of the unique key.
  • A missed day (NAS down) catches up: the latest threshold already passed and not sent is sent once, marked as late; older missed ones are recorded as skipped, not sent.

How it sends (QD-21) ​

Microsoft Graph sendMail from a dedicated notifications@getmy.group mailbox in the getmy.group tenant. No new vendor; mail comes from our own domain with SPF, DKIM and DMARC already handled by Microsoft 365.

Condition (Product Owner, 2026-09-29): the app can send from that one mailbox only. An app granted the Graph Mail.Send application permission on its own can send as any mailbox in the tenant, so it must be limited:

  • Preferred: RBAC for Applications in Exchange Online. The app registration gets no tenant-wide Mail.Send in Entra. Instead, in Exchange, a service principal for the app is given the "Application Mail.Send" role with a management scope that matches only notifications@getmy.group.
  • Fallback: an Exchange application access policy (RestrictAccess) on a mail-enabled security group containing only that mailbox, if RBAC for Applications isn't available on the tenant's plan.
  • The code sends only from REMINDER_FROM and refuses to start if it is not set (audit K2).

Client ID and secret in Doppler prd only.

Alternatives considered: SMTP through Microsoft 365 (needs SMTP AUTH turned on, weaker), or a transactional provider such as Postmark (a new vendor and data processor, needs DNS records).

Failures ​

  • Graph 401, 429 (honour Retry-After), 5xx, timeout: logged without addresses or content, retried next run, and after 2 failed days an alert goes through the alerting item in the AUDIT.md queue.
  • Companies House unreachable: that company's Companies House items are skipped for the day and the email says so, never silently.

Acceptance tests ​

  1. Given FEAW's VAT return due 7 Oct 2026, when the job runs on 7 Sep, 23 Sep, 30 Sep, 4 Oct and 7 Oct, then Rob and Fraser each get one email on each of those days, and running the job twice on one day sends nothing the second time.
  2. Given the confirmation statement overdue since 7 Sep 2026, when the job runs each day, then an overdue email goes once a week, not daily.
  3. Given the job didn't run from 28 Sep to 1 Oct, when it runs on 2 Oct, then the missed 7-day reminder for 7 Oct goes once, marked late. Had several thresholds been missed, only the latest one is sent.
  4. Given BST ends on 25 Oct 2026, when the job runs at 08:00 London on 24, 25 and 26 Oct, then each day's reminders go on that London date (tested across the change).
  5. Given Graph answers 429 then 200, when the job runs, then the email is sent once after the wait; given a 5xx, nothing is marked sent and the next run retries.
  6. Given a person with access to WealthTechPros only, when the job runs, then they get no FEAW reminders.
  7. Given a reminder email, then it contains no amounts and no bank details, and the logs contain no email address or email body.
  8. One sender mailbox only. Given the app's Graph credentials, when it sends from notifications@getmy.group, the email is delivered; when the same credentials try to send as any other mailbox in the tenant (for example Rob's), Graph refuses with 403 ErrorAccessDenied. Run at setup and after any change to the app's permissions, and recorded in the ADR for reminders. In code, a unit test shows every send uses REMINDER_FROM and nothing else.

Scopes and settings ​

  • No new Xero scope. Companies House: the existing key.
  • Microsoft Graph: "Application Mail.Send" through RBAC for Applications, scoped to one mailbox (or Mail.Send with an application access policy as the fallback). Never tenant-wide.
  • Doppler prd: GRAPH_TENANT_ID, GRAPH_CLIENT_ID, GRAPH_CLIENT_SECRET, REMINDER_FROM. Validated at startup (audit K2).

Dependencies ​

  • The NAS deploy working (the dedicated deploy user, plan first), since reminders run in the deployed app.
  • Prd secrets separated from dev (plan first).
  • QD-21 (how to send) and QD-22 (who receives) approved.
  • An Exchange Online admin (Rob) for the RBAC for Applications setup.