Skip to content

Email Delivery (Lettermint)

Rondo Club routes outgoing wp_mail() traffic through Lettermint using the theme-level transport Rondo\Notifications\LettermintMailer.

  • 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

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 with EmailTemplate::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

Class: includes/class-lettermint-mailer.php

Hook: pre_wp_mail

Behavior:

  • If Lettermint is not configured, the filter returns null and WordPress default mail flow continues
  • Headerless wp_mail() calls default to text/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.

Class: includes/class-lettermint-webhook.php

Endpoint: POST /wp-json/rondo/v1/lettermint/webhook

Supported actionable events:

  • message.hard_bounced
  • message.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-Signature and X-Lettermint-Delivery. Header normalization preserves duplicate values so the SDK can reject ambiguous signatures. A verification failure returns HTTP 401 invalid_signature before suppression or follow-up tasks are written.
  • Stores/updates per-recipient state in option rondo_lettermint_suppressed_emails
  • Creates idempotent follow-up rondo_todo tasks for Secretaris users
  • Task deduplication is applied first on Lettermint event_id, then on mail-level message_id + recipient to 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_label suffix (inactief) + _rondo_inactive_emails post meta)

Configuration helper: includes/class-lettermint-config.php

Priority order for values:

  1. WordPress constants
  2. Environment variables
  3. WordPress options

Supported keys:

  • API token:
    • RONDO_LETTERMINT_API_TOKEN
    • LETTERMINT_API_TOKEN
    • rondo_lettermint_api_token (option)
  • Team API token (for Team API management calls such as webhook creation):
    • RONDO_LETTERMINT_TEAM_API_TOKEN
    • LETTERMINT_TEAM_API_TOKEN
    • rondo_lettermint_team_api_token (option)
    • Falls back to the regular API token when not explicitly configured
  • Route ID (optional):
    • RONDO_LETTERMINT_ROUTE_ID
    • LETTERMINT_ROUTE_ID
    • rondo_lettermint_route_id (option)
  • Default From email (optional):
    • RONDO_LETTERMINT_FROM_EMAIL
    • LETTERMINT_FROM_EMAIL
    • rondo_lettermint_from_email (option)
  • Default From name (optional):
    • RONDO_LETTERMINT_FROM_NAME
    • LETTERMINT_FROM_NAME
    • rondo_lettermint_from_name (option)
  • Project ID (selected in settings for webhook auto-provisioning):
    • rondo_lettermint_project_id (option)
  • Webhook secret:
    • RONDO_LETTERMINT_WEBHOOK_SECRET
    • LETTERMINT_WEBHOOK_SECRET
    • rondo_lettermint_webhook_secret (option)
  • Webhook tolerance (seconds, minimum 30):
    • RONDO_LETTERMINT_WEBHOOK_TOLERANCE
    • LETTERMINT_WEBHOOK_TOLERANCE
    • rondo_lettermint_webhook_tolerance (option)

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-mailadres
    • Standaard afzender naam
  • Bounce verification uses a separate Verificatiemail block with:
    • Verificatiemail From e-mailadres
    • Verificatiemail From naam
    • Verificatiemail onderwerp
    • Verificatiemail bericht
    • Placeholders: {name}, {email}, {club_name}, {sender_name}, {sender_email}, {date}

Sender behavior:

  • If a mail call provides an explicit From header, that value is used.
  • If not, Lettermint transport falls back to configured default sender values.

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 the is_default route
  • Creates a webhook pointing to POST /wp-json/rondo/v1/lettermint/webhook
  • Registers only actionable events:
    • message.hard_bounced
    • message.spam_complaint
  • Persists returned webhook_id and webhook secret (secret/signing_secret) to WordPress options for runtime verification

UI note:

  • Instellingen > Koppelingen > Lettermint uses 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.

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() with X-Rondo-Email-Tag: lettermint-test
  • Validates Lettermint API token presence before sending
  • Sends to the provided recipient (or current admin user email when omitted)

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-verification
    • X-Rondo-Metadata JSON containing flow/sender/todo/person IDs
  • Sender resolution order for verification mails:
    • Verificatiemail From e-mailadres and Verificatiemail From naam
    • Default Lettermint sender (Standaard afzender ...)
    • Current user fallback
  • Recipient resolution order:
    • Explicit recipient request field
    • Bounce recipient meta on the todo (_rondo_lettermint_recipient)
    • First email in the first related person
  • When that verification email bounces, webhook processing assigns the follow-up todo to the sender and marks the person email inactive

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.

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.

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.