{"id":"6a64c51d88ea8efa12fc7b35","title":"2026 07 25 Issue 328","path":"how-to/committee/release-notes/2026-07-25-issue-328","contentMarkdown":"# 25-Jul-2026 — adopt Ramblers Team Emails API ([ref #328](https://github.com/nbarrett/ngx-ramblers/issues/328), [#329](https://github.com/nbarrett/ngx-ramblers/issues/329), [#330](https://github.com/nbarrett/ngx-ramblers/issues/330), [#331](https://github.com/nbarrett/ngx-ramblers/issues/331), [#332](https://github.com/nbarrett/ngx-ramblers/issues/332), [#333](https://github.com/nbarrett/ngx-ramblers/issues/333))\n\n## [build 792](https://github.com/nbarrett/ngx-ramblers/actions/runs/30160946191) — [commit 1e1610a](https://github.com/nbarrett/ngx-ramblers/commit/1e1610a8f36c15f438cd6b469df9b840d3fc73b8)\n\n_____\n\n## What's new\n\nNGX 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](https://github.com/nbarrett/ngx-ramblers/issues/209) interface with the published supporter snapshot, unsubscribe and bounced-email operations, including their team-scoped `api_key` and `team_code` credentials.\n\nSupporter 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.\n\nThe 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.\n\nHard 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.\n\nAdmin 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.\n\nUpload 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.\n\n## Supporter fields (Team Emails 1.0.0)\n\nWhat NGX does with each published supporter field in this release, and known follow-ups. Local member data that Ramblers does not return is preserved.\n\n| Supporter field | NGX use in this release | Future / not yet |\n| --- | --- | --- |\n| `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 |\n| `contactId` | Mapped to `salesforceId`; used for match; written onto the member record on apply | — |\n| `membershipNo` | Mapped to `membershipNumber`; match key; applied when changed | Nullable members without a number are supported |\n| `email` | Mapped and applied (when blank locally, or when policy requires); bounce/unsubscribe identity with `memberRef` | — |\n| `title` | Mapped; applied when blank locally | — |\n| `firstName` | Mapped (falls back to `friendlyName`); applied when blank locally | — |\n| `lastName` | Mapped; applied when blank locally | — |\n| `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 |\n| `mobile` | Mapped to `mobileNumber`; applied when blank locally | — |\n| `landline` | Mapped to `landlineTelephone`; applied when blank locally | — |\n| `membershipStatus` | Mapped to `memberStatus`; applied when changed | Confirm status vocabulary with Head Office if labels change |\n| `memberType` | Mapped to `type` on the load snapshot | Persist/apply path if admin UI needs it beyond snapshot review |\n| `membershipExpiry` | Mapped to `membershipExpiryDate`; applied when changed (including clear rules for lapsed/resigned) | — |\n| `membershipJoinDate` | Received and validated; not mapped into NGX | Map if needed for AGM/join reporting without Insight Hub |\n| `membershipEndDate` | Received and validated; not mapped into NGX | Map if end-of-membership reporting is required |\n| `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 |\n| `teamRelationshipFrom` | Mapped to `salesforceTeamRelationshipFrom` on the snapshot | Persist/apply if history of team relationship is needed in admin |\n| `wellbeingWalker` | Mapped on the snapshot | Persist/apply for filters and reporting |\n| `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 |\n| `volunteerRoles[]` | Received and validated; not mapped into NGX | Phase Two: roles, start dates, walk-leader status and Wellbeing Walks role |\n| `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 |\n| `emailConsentLastUpdated` | Mapped to `emailPermissionLastUpdated`; applied when changed | — |\n| `postConsent` | Mapped on the snapshot | Persist/apply; `postConsentLastUpdated` not mapped yet |\n| `postConsentLastUpdated` | Received and validated; not mapped | Map with post consent if post marketing is used |\n| `phoneConsent` | Mapped on the snapshot | Persist/apply; `phoneConsentLastUpdated` not mapped yet |\n| `phoneConsentLastUpdated` | Received and validated; not mapped | Map with phone consent if used |\n| `emailConsentWellbeingWalks` | Mapped on the snapshot | Persist/apply for Wellbeing Walks audiences |\n| `noWalkProgram` | Mapped on the snapshot | Persist/apply for programme suppression rules |\n| `noCampaigning` | Mapped on the snapshot | Persist/apply for campaign suppression |\n| `noSurveys` | Mapped on the snapshot | Persist/apply for survey suppression |\n| `canViewMemberData` | Mapped; enforced when sending protected member data / addresses (sender must have it) | Ensure every sync writes the flag onto the matched member record |\n| `canEmailMembers` | Mapped; enforced for Member / Affiliated audiences | Same persist/apply as above |\n| `canEmailVolunteers` | Mapped; enforced for Volunteer audiences | Same persist/apply as above |\n| `canEmailWellbeingWalkers` | Mapped; enforced for Wellbeing Walker audiences | Same persist/apply as above |\n| `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 |\n| Bounce payload (`memberRef`, email, hard/soft) | Hard/soft Brevo bounces written back with audit and retries | — |\n| 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 |\n| Disappeared supporters | Counted only; not deleted, expired or prepared for apply | Removal semantics only if Head Office defines them |\n| 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 |\n\n## At a glance\n\n- [#328](https://github.com/nbarrett/ngx-ramblers/issues/328) replaces the legacy client with `GET /get_supporters`, `/unsubscribe` and `/bounced_email` and validates every request and response against `@ramblers/sf-contract`.\n- [#329](https://github.com/nbarrett/ngx-ramblers/issues/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.\n- [#330](https://github.com/nbarrett/ngx-ramblers/issues/330) makes `canViewMemberData`, `canEmailMembers`, `canEmailVolunteers` and `canEmailWellbeingWalkers` effective safeguards for protected member data and audiences.\n- [#331](https://github.com/nbarrett/ngx-ramblers/issues/331) sends hard and soft bounce reports to Ramblers with idempotent audit records and bounded retries for temporary failures.\n- [#332](https://github.com/nbarrett/ngx-ramblers/issues/332) prepares Ramblers unsubscribe writeback using `memberRef` and email but keeps it behind an explicit disabled-by-default switch pending scope confirmation.\n- [#333](https://github.com/nbarrett/ngx-ramblers/issues/333) adds contract, mapping, snapshot, permission and writeback tests together with a rehearsal, production cutover and rollback runbook.\n- Insight Hub import remains available throughout transition and remains necessary for Phase Two fields that are absent from Team Emails 1.0.0.\n- 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.\n- Bulk load and bulk delete show striped progress bars; bulk wording uses **Processed** / **Finished processing** rather than per-member success noise.\n- Bulk-load matching requires an existing member id, so incomplete rows without ids are not treated as updates.\n- Save failures and unique-index races show a clear **Save failed** review message instead of a misleading **Updated** success.\n- 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.\n- Upload History filters live inside the tab panel; Members uploaded and Member actions headings and member rows load on first open.\n- Bulk-load tables scroll within the viewport so the panel stays on screen.\n- Member bulk-load audit sessions can also be listed and cleared under System Settings → Diagnostics.\n- Mail Settings → List Settings shows alert and progress feedback while syncing contacts with Brevo.\n- 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.","contentHtml":"

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

\n

build 792 — commit 1e1610a

\n
\n

What's new

\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

Supporter fields (Team Emails 1.0.0)

\n

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.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Supporter fieldNGX use in this releaseFuture / not yet
memberRefPrimary stable identity for match, bounce writeback and unsubscribe preparation; mapped to salesforceMemberRef on the load snapshotKeep as the stable identity for non-members; confirm any Head Office identifier semantics still open
contactIdMapped to salesforceId; used for match; written onto the member record on apply—
membershipNoMapped to membershipNumber; match key; applied when changedNullable members without a number are supported
emailMapped and applied (when blank locally, or when policy requires); bounce/unsubscribe identity with memberRef—
titleMapped; applied when blank locally—
firstNameMapped (falls back to friendlyName); applied when blank locally—
lastNameMapped; applied when blank locally—
friendlyNameUsed 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
mobileMapped to mobileNumber; applied when blank locally—
landlineMapped to landlineTelephone; applied when blank locally—
membershipStatusMapped to memberStatus; applied when changedConfirm status vocabulary with Head Office if labels change
memberTypeMapped to type on the load snapshotPersist/apply path if admin UI needs it beyond snapshot review
membershipExpiryMapped to membershipExpiryDate; applied when changed (including clear rules for lapsed/resigned)—
membershipJoinDateReceived and validated; not mapped into NGXMap if needed for AGM/join reporting without Insight Hub
membershipEndDateReceived and validated; not mapped into NGXMap if end-of-membership reporting is required
teamStatusMapped to salesforceTeamStatus on the snapshot; drives audience checks (Member / Affiliated / Volunteer / Wellbeing Walker) when present on the memberEnsure apply always writes team status so audience checks stay accurate after every sync
teamRelationshipFromMapped to salesforceTeamRelationshipFrom on the snapshotPersist/apply if history of team relationship is needed in admin
wellbeingWalkerMapped on the snapshotPersist/apply for filters and reporting
walkLeaderMapped 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 namesPersist 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 NGXPhase Two: roles, start dates, walk-leader status and Wellbeing Walks role
emailConsent + doNotEmailCombined into emailMarketingConsent (true only if consent and not do-not-email); doNotEmail kept on the snapshotGranular marketing consent remains Insight Hub / Phase Two
emailConsentLastUpdatedMapped to emailPermissionLastUpdated; applied when changed—
postConsentMapped on the snapshotPersist/apply; postConsentLastUpdated not mapped yet
postConsentLastUpdatedReceived and validated; not mappedMap with post consent if post marketing is used
phoneConsentMapped on the snapshotPersist/apply; phoneConsentLastUpdated not mapped yet
phoneConsentLastUpdatedReceived and validated; not mappedMap with phone consent if used
emailConsentWellbeingWalksMapped on the snapshotPersist/apply for Wellbeing Walks audiences
noWalkProgramMapped on the snapshotPersist/apply for programme suppression rules
noCampaigningMapped on the snapshotPersist/apply for campaign suppression
noSurveysMapped on the snapshotPersist/apply for survey suppression
canViewMemberDataMapped; enforced when sending protected member data / addresses (sender must have it)Ensure every sync writes the flag onto the matched member record
canEmailMembersMapped; enforced for Member / Affiliated audiencesSame persist/apply as above
canEmailVolunteersMapped; enforced for Volunteer audiencesSame persist/apply as above
canEmailWellbeingWalkersMapped; enforced for Wellbeing Walker audiencesSame persist/apply as above
canViewMemberDateReceived and validated (contract field); not used by NGXConfirm 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 scopeEnable when preference and team vs organisation-wide behaviour are confirmed
Disappeared supportersCounted only; not deleted, expired or prepared for applyRemoval 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 usedPhase Two fields needed to retire Insight Hub exports
\n

At a glance

\n\n"}