Email Delivery (Lettermint)
Rondo Club routes outgoing wp_mail() traffic through Lettermint using the theme-level transport Rondo\Notifications\LettermintMailer.
Overview
Section titled “Overview”- Existing mail call sites remain unchanged (
wp_mail()is still used throughout the codebase) - Delivery is handled via Lettermint API instead of SMTP/plugin transport
- Delivery failures and complaints are fed back through a signed webhook endpoint
- Most user-facing emails are wrapped by
Rondo\Notifications\EmailTemplate, which provides a shared branded HTML shell around each sender’s own content
Shared HTML Layout
Section titled “Shared HTML Layout”Class: includes/class-email-template.php
Purpose:
- Provides a consistent HTML shell for outbound emails with branded header, card layout, footer, and optional CTA button
- Supports both prebuilt HTML fragments (
body_html) and plain-text templates converted withEmailTemplate::format_plain_text() - Keeps existing sender-specific placeholder replacement logic inside each mailer, then wraps the final content
Emails rendered through Rondo\Notifications\EmailTemplate use the configured club logo from FinanceConfig::get_club_logo_id() in their header. The logo links to the existing brand_url and replaces the header’s text label. The email heading appears beside the logo in a vertically aligned, two-column table; the message body starts in the card underneath. It uses the WordPress medium image size with explicit proportional dimensions, capped at 64 pixels high and 160 pixels wide. The club display name is included as alternative text for mail clients that block images.
If no usable logo is configured, the existing brand_name text remains visible. The decorative accent stripe above the email heading is removed; message content and delivery behavior are unchanged.
The shell uses an inline Arial/Helvetica/sans-serif stack, matching the reviewed mail preview.
The configured club accent (FinanceConfig::get_accent_color()) controls template links and buttons, including standalone payment and activation buttons. It takes precedence over sender-specific accent arguments. If no valid club accent is set, a valid sender accent is used, then #0f766e. The configured accent background (get_accent_background_color()) provides a solid email background, falling back to #f3f7f6. All body and footer links receive the club accent inline, replacing earlier link colors without changing destinations or other formatting. Buttons generated by the helper retain their contrasting white text. Payment and VOG links, feedback callouts, mention highlights and digest section accents use the shared color helpers. Neutral text/table colors and the red overdue-task warning remain functional colors. Tournament assignment emails also use this shared shell.
Current adopters:
- Finance invoice mails (
InvoiceEmailSender) - Installment mails (
InstallmentEmailSender) - Invoice reminders (
InvoiceReminderSender) - VOG request/reminder mails (
VOGEmail) - Welcome mails for provisioned users (
UserProvisioning) - Todo assignment mails
- Immediate mention notifications
- Digest mails (
EmailChannel) - Lettermint test and verification mails
Outbound Transport
Section titled “Outbound Transport”Class: includes/class-lettermint-mailer.php
Hook: pre_wp_mail
Behavior:
- If Lettermint is not configured, the filter returns
nulland WordPress default mail flow continues - Headerless
wp_mail()calls default totext/plain; the normalized value is also sent as string metadata to Lettermint - If configured, mail is sent through Lettermint with support for:
- HTML/text content
From,Cc,Bcc,Reply-To- Custom headers
- Regular attachments and inline images with a Content-ID
- Optional route ID
- Tags and metadata
The Lettermint PHP SDK 3.1 creates a fresh immutable builder for each message
with emails->compose(). Keep the builder returned by each call when adding
headers, body content, metadata or attachments. The transport passes file bytes
through Attachment::fromBytes(), with a Content-ID for inline images.
LettermintMailer passes WordPress embeds to the Lettermint API as inline
attachments with matching Content-IDs. The default WordPress mailer handles the
same embeds when Lettermint is unconfigured. Invoice and reminder emails use
cid:rondo-invoice-qr for private payment QR images. The finance settings test
email uses a dummy QR image under rondo-test/ in public uploads.
Webhook Inbound Events
Section titled “Webhook Inbound Events”Class: includes/class-lettermint-webhook.php
Endpoint: POST /wp-json/rondo/v1/lettermint/webhook
Supported actionable events:
message.hard_bouncedmessage.spam_complaint
Soft bounces (message.soft_bounced) are ignored and do not create tasks or update suppression state.
Behavior:
- Verifies the raw request body with the Lettermint PHP SDK 3.1 using
X-Lettermint-SignatureandX-Lettermint-Delivery. Header normalization preserves duplicate values so the SDK can reject ambiguous signatures. A verification failure returns HTTP 401invalid_signaturebefore suppression or follow-up tasks are written. - Stores/updates per-recipient state in option
rondo_lettermint_suppressed_emails - Creates idempotent follow-up
rondo_todotasks for Secretaris users - Task deduplication is applied first on Lettermint
event_id, then on mail-levelmessage_id + recipientto avoid duplicate todos for one email when retries/follow-up events arrive - Falls back to administrators when no active Secretaris is found
- For verification-email flows (
metadata.flow = email_verification):- Assigns bounce follow-up task to the original sender (
metadata.sender_user_id) - Marks the matched person email contact as inactive (
contact_labelsuffix(inactief)+_rondo_inactive_emailspost meta)
- Assigns bounce follow-up task to the original sender (
Configuration
Section titled “Configuration”Configuration helper: includes/class-lettermint-config.php
Priority order for values:
- WordPress constants
- Environment variables
- WordPress options
Supported keys:
- API token:
RONDO_LETTERMINT_API_TOKENLETTERMINT_API_TOKENrondo_lettermint_api_token(option)
- Team API token (for Team API management calls such as webhook creation):
RONDO_LETTERMINT_TEAM_API_TOKENLETTERMINT_TEAM_API_TOKENrondo_lettermint_team_api_token(option)- Falls back to the regular API token when not explicitly configured
- Route ID (optional):
RONDO_LETTERMINT_ROUTE_IDLETTERMINT_ROUTE_IDrondo_lettermint_route_id(option)
- Default From email (optional):
RONDO_LETTERMINT_FROM_EMAILLETTERMINT_FROM_EMAILrondo_lettermint_from_email(option)
- Default From name (optional):
RONDO_LETTERMINT_FROM_NAMELETTERMINT_FROM_NAMErondo_lettermint_from_name(option)
- Project ID (selected in settings for webhook auto-provisioning):
rondo_lettermint_project_id(option)
- Webhook secret:
RONDO_LETTERMINT_WEBHOOK_SECRETLETTERMINT_WEBHOOK_SECRETrondo_lettermint_webhook_secret(option)
- Webhook tolerance (seconds, minimum 30):
RONDO_LETTERMINT_WEBHOOK_TOLERANCELETTERMINT_WEBHOOK_TOLERANCErondo_lettermint_webhook_tolerance(option)
Settings UI
Section titled “Settings UI”Rondo exposes Lettermint connection management in:
Instellingen > Koppelingen > Lettermint
The screen stores credentials via the existing club config endpoint (POST /wp-json/rondo/v1/config). Tokens and webhook secrets are encrypted at rest with sodium and are never returned by the API; responses contain only has_* flags.
UI guidance:
- Project API token help link points to
https://dash.lettermint.co/projects - Team API token help link points to
https://dash.lettermint.co/team/api-tokens - Default sender can be configured with:
Standaard afzender e-mailadresStandaard afzender naam
- Bounce verification uses a separate
Verificatiemailblock with:Verificatiemail From e-mailadresVerificatiemail From naamVerificatiemail onderwerpVerificatiemail bericht- Placeholders:
{name},{email},{club_name},{sender_name},{sender_email},{date}
Sender behavior:
- If a mail call provides an explicit
Fromheader, that value is used. - If not, Lettermint transport falls back to configured default sender values.
Webhook Provisioning
Section titled “Webhook Provisioning”Admin users can trigger automatic webhook creation from the same Lettermint settings screen.
Backend endpoint:
POST /wp-json/rondo/v1/lettermint/webhook/create
Behavior:
- Uses the configured Team API token (or API token fallback)
- Auto-resolves project/route using this priority:
- Explicit route override from advanced settings
- Explicit project override in request payload
- Stored selected project (
rondo_lettermint_project_id) - Single available project fallback
- Resolves the route by loading project routes (
GET /v1/projects/{projectId}/routes) and picking theis_defaultroute - Creates a webhook pointing to
POST /wp-json/rondo/v1/lettermint/webhook - Registers only actionable events:
message.hard_bouncedmessage.spam_complaint
- Persists returned
webhook_idand webhook secret (secret/signing_secret) to WordPress options for runtime verification
UI note:
Instellingen > Koppelingen > Lettermintuses the automatic flow by default.- If multiple Lettermint projects are available, the UI shows a dropdown with project names and requires selecting one.
- The selected project is stored and reused for future webhook provisioning calls.
- Webhook status is shown as a simple success/error indicator.
- Detailed webhook metadata (project/route/webhook ID/secret state) is available only under advanced settings.
- Route ID and webhook secret are available only as advanced fallback overrides.
Delivery Test
Section titled “Delivery Test”The same settings screen supports a quick send test to verify outbound transport:
POST /wp-json/rondo/v1/lettermint/test-email
Behavior:
- Admin-only endpoint
- Uses
wp_mail()withX-Rondo-Email-Tag: lettermint-test - Validates Lettermint API token presence before sending
- Sends to the provided recipient (or current admin user email when omitted)
Bounce Verification Flow
Section titled “Bounce Verification Flow”Task action endpoint:
POST /wp-json/rondo/v1/lettermint/verify-email
Behavior:
- Accessible to approved users with access to the todo (author, assignee, or admin)
- Sends a verification email via
wp_mail()with:X-Rondo-Email-Tag: email-verificationX-Rondo-MetadataJSON containing flow/sender/todo/person IDs
- Sender resolution order for verification mails:
Verificatiemail From e-mailadresandVerificatiemail From naam- Default Lettermint sender (
Standaard afzender ...) - Current user fallback
- Recipient resolution order:
- Explicit
recipientrequest field - Bounce recipient meta on the todo (
_rondo_lettermint_recipient) - First email in the first related person
- Explicit
- When that verification email bounces, webhook processing assigns the follow-up todo to the sender and marks the person email inactive
Weekly volunteer recruitment email
Section titled “Weekly volunteer recruitment email”WeekendVolunteerMail registers rondo_weekend_volunteer_mail on admin, REST and cron requests. A single WordPress cron event starts every Sunday at 19:00 Europe/Amsterdam, anchored to 20 September 2026; subsequent events process at most 25 addresses per minute. Calendar-based scheduling preserves local time across summer/winter time changes. Actual execution depends on the site’s WP-Cron runner. Delivery is limited to the scheduled Sunday evening; delayed jobs on Monday do not catch up with old mail.
Every Sunday from 20 September 2026 is a delivery round, including consecutive Sundays across DST and year boundaries. Empty or missed rounds do not shift that schedule. The mail footer describes the weekly frequency.
The selection covers all days of the next five full Monday–Sunday weeks. Its interval starts on the next Monday at 00:00 and ends exclusively 36 days after the sending Sunday. For example, the 25 October 2026 round covers 26 October through 29 November, including weekdays. Only published, open shifts with remaining capacity and an open signup window appear. The email groups equal task types and start/end times, summing their available places; unlimited capacity is labelled without a numeric limit.
Recipients come from PeopleShiftProgress: responsible players and parents with status not_started or insufficient. This includes planned as well as completed work, family attribution, scaled family duties and exemptions. Children do not receive their parents’ obligation mail. The primary contactable email per responsible person is used, normalized and deduplicated across all units. Shared addresses receive one digest containing shifts that at least one of those responsible people may claim. IVA (including waivers), VOG and pool restrictions reuse ShiftSignupEligibility, also used by member signup and coordinator assignment. Overlap warnings remain overridable in the signup flow.
At each batch, duty counts and recipients are refreshed. Relevant cache-generation changes during a batch trigger another recipient refresh; the destination, publication/contact policy, capacity and signup requirements are checked before each message. Fulfilled/exempt duties, changed addresses and empty personal shift selections are skipped. The initial queue is fixed for that Sunday; newly eligible addresses wait until the next weekly round.
Messages use the shared club-branded EmailTemplate, an actual first-name greeting and the /vrijwillig signup link. Below the signup button, the footer encourages members to choose a suitable shift themselves and links to the AWC volunteer policy. It explains that members who do not meet the policy may be assigned a shift, receive an assignment email, and may swap or arrange a replacement. This wording does not promise a particular assignment date or tie assignments to the weekly mailing schedule. They go through wp_mail() and the configured Lettermint transport with tag volunteer-weekend.
Coordinator overview and dashboard status
Section titled “Coordinator overview and dashboard status”The volunteer dashboard reads GET /rondo/v1/volunteer-mailing every minute.
This private, non-cacheable response requires manage_options or vrijwilligers.
It exposes next_at, scheduled, overview_email, planner_email and nullable
last_round. Round details contain date, accepted/pending/failed/uncertain/skipped
member-mail counts and overview_status, without recipient names or addresses.
Reserved member deliveries count as uncertain. Acceptance does not confirm inbox delivery.
PUT /rondo/v1/volunteer-mailing requires overview_email and optionally accepts
planner_email. Both accept a valid email or an empty string; invalid values
return 400. An empty overview address disables the general overview. The planner
address controls proposal notices and reminders
independently; omitting it preserves its setting. Saving settings sends no mail.
Each round reserves one general overview before calling wp_mail(). It includes
all currently open, signup-window-eligible shifts, including IVA shifts without an
eligible member recipient. It sends an empty-period notice when needed. The
overview counts toward the 25-attempt batch limit and uses tag
volunteer-weekend-overview. Failed, uncertain or already reserved overviews are
not resent automatically. Its status is accepted, failed, uncertain,
reserved, disabled or not_recorded. The recipient option is
rondo_weekend_volunteer_mail_overview_email; the persisted per-round overview
prevents changing the address from causing a second send in that round.
VolunteerMailingSettingsTest.php and WeekendVolunteerMailTest.php cover
permissions, independent settings, five-week selection, weekly scheduling, batch
limits and failure handling.
Delivery state and failure recovery
Section titled “Delivery state and failure recovery”The non-autoloaded option rondo_weekend_volunteer_mail_state holds the current Sunday’s date, pending addresses, next-batch timestamp and per-address outcomes (skipped, reserved, accepted, failed, uncertain). It is replaced on the next sending Sunday, one week later, bounding retained personal data. accepted means accepted by the transport, not confirmed inbox delivery.
A unique, invariant-value option rondo_weekend_mail_lock_YYYY-MM-DD serializes callbacks. A recipient is durably removed from the queue and marked reserved before the provider is called. Failed or ambiguous sends are never automatically retried, because a transport timeout can occur after provider acceptance. Normal completion releases the lock. A fatal process termination can leave it behind: inspect the current state and Lettermint events, ensure no worker remains active, then remove only that date’s lock to allow remaining pending addresses to continue. Do not put reserved/accepted addresses back into the queue without establishing the provider outcome. Old locks are removed when a new Sunday’s state replaces the previous one.
Theme deactivation clears the scheduled hook. No separate tables or external scheduler are used.