25-Jul-2026 — adopt Ramblers Team Emails API (ref #328, #329, #330, #331, #332, #333)

build 792 — commit 1e1610a

What's new

NGX now implements the consumer side of Ramblers Team Emails 1.0.0 using the same shared contract as the live Salesforce mock. This replaces the superseded #209 interface with the published supporter snapshot, unsubscribe and bounced-email operations, including their team-scoped api_key and team_code credentials.

Supporter synchronisation treats the API response as a complete snapshot. It matches members using stable Ramblers identities, supports members and non-members without assuming that a membership number exists, preserves locally held data that Ramblers does not return, and records new, changed, unchanged and disappeared counts for review. A supporter who disappears from a later snapshot is counted only: Phase One does not define disappearance as deletion, expiry or transfer, so those members are not prepared for apply.

The published permissions now protect member data and email audiences. When Ramblers Team Emails is enabled, NGX requires the signed-in supporter to have permission to view member data before exposing protected addresses, and separately enforces permission to email members, volunteers and Wellbeing Walkers. Local-only recipients continue to use the existing NGX permissions.

Hard and soft Brevo bounces can now be reported to Ramblers using the supporter reference and email address. NGX records whether the writeback was delivered, skipped or failed, retries transient network, rate-limit and server errors, and avoids repeating a writeback that has already succeeded. Unsubscribe requests are contract-valid and use the published supporter identity, but remain deliberately disabled until Head Office confirms which preference they change and whether that change is team-specific or organisation-wide.

Admin UI now uses the published product name Ramblers Team Emails end to end (settings, bulk load, upload history, match labels). Internal host paths, config keys and Mongo field names stay as they are. Member bulk load and bulk delete show visual progress bars with percentage complete, clearer success and error wording, and safer matching that only updates members that already have an id. Bulk delete and Brevo contact create or update are faster under rate limits.

Upload history can be managed from Member Bulk Load → Manage History: filter by date range, select sessions with checkboxes, and delete the selection (with member action rows). Diagnostics still supports list and clear-all for admins. Upload History filters sit inside the panel, sub-tabs and members populate on first open, and large tables scroll within the browser window. Mail Settings → List Settings shows live progress when syncing with Brevo.

Supporter fields (Team Emails 1.0.0)

What NGX does with each published supporter field in this release, and known follow-ups. Local member data that Ramblers does not return is preserved.

Supporter field	NGX use in this release	Future / not yet
`memberRef`	Primary stable identity for match, bounce writeback and unsubscribe preparation; mapped to `salesforceMemberRef` on the load snapshot	Keep as the stable identity for non-members; confirm any Head Office identifier semantics still open
`contactId`	Mapped to `salesforceId`; used for match; written onto the member record on apply	—
`membershipNo`	Mapped to `membershipNumber`; match key; applied when changed	Nullable members without a number are supported
`email`	Mapped and applied (when blank locally, or when policy requires); bounce/unsubscribe identity with `memberRef`	—
`title`	Mapped; applied when blank locally	—
`firstName`	Mapped (falls back to `friendlyName`); applied when blank locally	—
`lastName`	Mapped; applied when blank locally	—
`friendlyName`	Used only as `firstName` fallback when first name is empty (not the same as local `displayName`)	Store as its own member field later; do not overwrite `displayName`; optional seed of display name only when creating or when blank
`mobile`	Mapped to `mobileNumber`; applied when blank locally	—
`landline`	Mapped to `landlineTelephone`; applied when blank locally	—
`membershipStatus`	Mapped to `memberStatus`; applied when changed	Confirm status vocabulary with Head Office if labels change
`memberType`	Mapped to `type` on the load snapshot	Persist/apply path if admin UI needs it beyond snapshot review
`membershipExpiry`	Mapped to `membershipExpiryDate`; applied when changed (including clear rules for lapsed/resigned)	—
`membershipJoinDate`	Received and validated; not mapped into NGX	Map if needed for AGM/join reporting without Insight Hub
`membershipEndDate`	Received and validated; not mapped into NGX	Map if end-of-membership reporting is required
`teamStatus`	Mapped to `salesforceTeamStatus` on the snapshot; drives audience checks (Member / Affiliated / Volunteer / Wellbeing Walker) when present on the member	Ensure apply always writes team status so audience checks stay accurate after every sync
`teamRelationshipFrom`	Mapped to `salesforceTeamRelationshipFrom` on the snapshot	Persist/apply if history of team relationship is needed in admin
`wellbeingWalker`	Mapped on the snapshot	Persist/apply for filters and reporting
`walkLeader`	Mapped on the snapshot only (not yet applied to the member record). NGX “walk leader” filters and pickers still use who has led walks, event assignment and Walks Manager contact names	Persist the flag and use it as an extra label or soft signal (e.g. member admin badge). Do not replace activity-based leader lists, rematch or walk edit permissions with this boolean alone
`volunteerRoles[]`	Received and validated; not mapped into NGX	Phase Two: roles, start dates, walk-leader status and Wellbeing Walks role
`emailConsent` + `doNotEmail`	Combined into `emailMarketingConsent` (`true` only if consent and not do-not-email); `doNotEmail` kept on the snapshot	Granular marketing consent remains Insight Hub / Phase Two
`emailConsentLastUpdated`	Mapped to `emailPermissionLastUpdated`; applied when changed	—
`postConsent`	Mapped on the snapshot	Persist/apply; `postConsentLastUpdated` not mapped yet
`postConsentLastUpdated`	Received and validated; not mapped	Map with post consent if post marketing is used
`phoneConsent`	Mapped on the snapshot	Persist/apply; `phoneConsentLastUpdated` not mapped yet
`phoneConsentLastUpdated`	Received and validated; not mapped	Map with phone consent if used
`emailConsentWellbeingWalks`	Mapped on the snapshot	Persist/apply for Wellbeing Walks audiences
`noWalkProgram`	Mapped on the snapshot	Persist/apply for programme suppression rules
`noCampaigning`	Mapped on the snapshot	Persist/apply for campaign suppression
`noSurveys`	Mapped on the snapshot	Persist/apply for survey suppression
`canViewMemberData`	Mapped; enforced when sending protected member data / addresses (sender must have it)	Ensure every sync writes the flag onto the matched member record
`canEmailMembers`	Mapped; enforced for Member / Affiliated audiences	Same persist/apply as above
`canEmailVolunteers`	Mapped; enforced for Volunteer audiences	Same persist/apply as above
`canEmailWellbeingWalkers`	Mapped; enforced for Wellbeing Walker audiences	Same persist/apply as above
`canViewMemberDate`	Received and validated (contract field); not used by NGX	Confirm with Head Office whether this is intentional vs `canViewMemberData`; ignore or map once clarified
Bounce payload (`memberRef`, email, hard/soft)	Hard/soft Brevo bounces written back with audit and retries	—
Unsubscribe payload (`memberRef`, email)	Prepared against the contract; disabled by default until Head Office confirms scope	Enable when preference and team vs organisation-wide behaviour are confirmed
Disappeared supporters	Counted only; not deleted, expired or prepared for apply	Removal semantics only if Head Office defines them
Not on Team Emails 1.0.0 (e.g. postcode, joint membership, group/area/other marketing consent)	Not returned by the API; local values kept; Insight Hub import still used	Phase Two fields needed to retire Insight Hub exports

At a glance

#328 replaces the legacy client with GET /get_supporters, /unsubscribe and /bounced_email and validates every request and response against @ramblers/sf-contract.
#329 reconciles complete supporter snapshots while preserving local fields, counting unexplained disappearances without preparing them for apply, and supporting affiliated members, volunteers and Wellbeing Walkers without membership numbers.
#330 makes canViewMemberData, canEmailMembers, canEmailVolunteers and canEmailWellbeingWalkers effective safeguards for protected member data and audiences.
#331 sends hard and soft bounce reports to Ramblers with idempotent audit records and bounded retries for temporary failures.
#332 prepares Ramblers unsubscribe writeback using memberRef and email but keeps it behind an explicit disabled-by-default switch pending scope confirmation.
#333 adds contract, mapping, snapshot, permission and writeback tests together with a rehearsal, production cutover and rollback runbook.
Insight Hub import remains available throughout transition and remains necessary for Phase Two fields that are absent from Team Emails 1.0.0.
System Settings and Member Bulk Load label the integration Ramblers Team Emails, with URL slug ramblers-team-emails and automatic rewrite from legacy salesforce / head-office-supporter-import query values.
Bulk load and bulk delete show striped progress bars; bulk wording uses Processed / Finished processing rather than per-member success noise.
Bulk-load matching requires an existing member id, so incomplete rows without ids are not treated as updates.
Save failures and unique-index races show a clear Save failed review message instead of a misleading Updated success.
Manage History lets file or member admins filter sessions by date, tick individual sessions and delete the selection; member action rows for those sessions are removed too.
Upload History filters live inside the tab panel; Members uploaded and Member actions headings and member rows load on first open.
Bulk-load tables scroll within the viewport so the panel stays on screen.
Member bulk-load audit sessions can also be listed and cleared under System Settings → Diagnostics.
Mail Settings → List Settings shows alert and progress feedback while syncing contacts with Brevo.
Brevo contact delete, create and batch update run with documented 10 RPS, 429 cooldown, and concurrent delete without remote event-history snapshots for large bulk selections.