Email Integration
Audience: Org Admin, System Admin, Deployment Administrator, Developer Related: Email and Consent Management User Guide · Configuration · Environment And Secrets · Index
Blackcap sends branded HTML email with plain-text alternatives through configured SMTP. The shared email layout supports Blackcap and Microwave Pie branding, hosted image behavior, environment-aware links, recipient rules, and feature-specific templates.
SMTP credentials are secrets. The Email and Consent Management User Guide is the canonical user-facing inventory of which messages are sent, their workflow timing, and their consent category. This document remains the canonical technical home for configuration, branding, rendering, delivery, privacy, and troubleshooting.
All centralized transactional email senders use inky_admin/services/email_branding_service.py. The service preserves the complete plain-text body and adds an email-client-safe HTML alternative with:
- a Blackcap by Microwave Pie text identity,
- Blackcap and Microwave Pie logo positions,
- an accessible heading and content area,
- an optional context panel and call-to-action,
- a copyable fallback action URL,
- and a consistent Blackcap footer with a recipient-specific Manage Email Preferences link when Consent Management can provide one.
The layout uses restrained table-based HTML, inline styles, system fonts, fixed image dimensions, meaningful alt text, and no JavaScript. Essential content never depends on remote images.
Configuration
Platform settings under the Email section:
email.branding_nameemail.blackcap_logo_urlemail.microwave_pie_logo_urlemail.branding_website_urlemail.branding_support_url
Logo URLs must be public HTTPS resources with no username, password, query string, or fragment. This prevents recipient IDs, organization IDs, tokens, or tracking parameters from entering shared branding URLs. Application action URLs are validated separately so legitimate reset, invitation, sharing, and review tokens remain intact.
Hosted assets
Blackcap defaults to the existing public assets in the Microwave Pie website repository:
assets/blackcap-logo.png→https://microwavepie.com/assets/blackcap-logo.png(128×128 transparent PNG)assets/microwavepie-logo-192.png→https://microwavepie.com/assets/microwavepie-logo-192.png(192×192 PNG)
This avoids maintaining duplicate email-only logo files. The Microwave Pie Netlify configuration applies Cache-Control: public, max-age=604800, must-revalidate to /assets/*. Serve these paths with HTTPS and the correct image/png MIME type, and do not append recipient-specific query parameters. Use the Email configuration settings only when the public asset location changes or an alternate approved logo is required.
Adding a new email type
Create the normal EmailMessage, set From/To/Subject exactly as before, then call apply_branded_email(...) with the complete plain-text body. Add attachments after or before the alternative as required by the current sender; Python's EmailMessage preserves the multipart structure. Never insert raw internal errors, credentials, reset secrets, API Tokens, MFA secrets, or provider credentials into the layout.
Preview
Open docs/previews/blackcap-branded-email-preview.html in a browser. Also test the plain-text part and an email client with remote images disabled.
Consent Management policy
Online Blackcap installations use Microwave Pie Consent Management as the authority for outbound-email consent. Blackcap does not maintain a second preference database and does not mint Consent Management URLs locally.
The integration reuses the same permanent registered-instance bearer token used by Microwave Pie Health Monitoring and Deployment Management. Blackcap calls POST /api/v1/instances/consent/email-policy before sending and the management service accepts the request only for an active, already-registered Blackcap instance. No additional Consent credential is configured in Blackcap.
Consent Management returns, per normalized recipient:
- whether the category may be sent;
- the durable recipient-specific Manage Email Preferences URL when applicable;
- an RFC 8058 one-click unsubscribe URL for Product Updates or General Marketing; and
- the configured Microwave Pie postal address for those marketing categories.
Blackcap sends one message per recipient when a recipient-specific preference URL is required. This prevents one recipient's Consent Management link from being exposed to another recipient in a To/Cc/Bcc group.
Email classification
| Category | Current Blackcap examples | Consent behavior |
|---|---|---|
| Required Service | invitations, password resets, support/request confirmations, voice-assistant link notices, regression notices, backup/admin lifecycle email | Always allowed. Blackcap asks Consent Management for the preference footer, but a management-service outage does not block necessary service mail. |
| Shared Content | recipe/PDF/export email, Blackcap-to-Blackcap recipe-share invitations, Meal Plan Review email | Allowed unless that recipient explicitly opted out of Shared Content. Blackcap fails closed if Consent Management cannot make the decision. The sharing user is told when a recipient was suppressed. |
| Product Updates | No current Blackcap-originated campaign | Requires explicit opt-in. Blackcap fails closed and includes Consent Management-provided RFC 8058 unsubscribe metadata and postal address when this category is introduced. |
| General Marketing | No current Blackcap-originated campaign | Requires explicit opt-in. Blackcap fails closed and includes Consent Management-provided RFC 8058 unsubscribe metadata and postal address when this category is introduced. |
Fully offline/unregistered installations do not have an authoritative Consent Management service. Optional categories therefore do not send from that state. Required service messages remain fail-open so recovery/authentication workflows are not made unavailable by a temporary management-service outage; in that case the message simply cannot include a Consent Management-issued preference link.
Account-page Email Preferences
The signed-in Account → Email Preferences panel is hosted by Microwave Pie Consent Management but embedded inside the normal Blackcap account layout. Blackcap does not pass its permanent instance token to the browser. Instead, the local /account/consent route uses the same registered-instance bearer credential as heartbeat to request a short-lived Consent Management embed for the signed-in user's email, then redirects only the iframe to that opaque Consent Management URL. The Consent Management frame authorization is bound to the browser-visible Account origin. Blackcap prefers the same-origin Account referrer, then trusted external/forwarded URL information, and recognizes the common Pi HTTPS ports 8443/9443. This matters when stunnel or another local TLS wrapper makes Gunicorn see internal HTTP even though the browser is using HTTPS; Consent Management receives the actual browser origin for its frame-ancestors policy. The iframe can change that user's Product Updates, General Marketing, and Shared Content choices; Required Service remains checked and read-only. If the management service is unavailable, the account page stays usable and the panel shows an unavailable state. Consent API calls make one short retry for transient connection/408/425/429/5xx failures before applying the normal required-service fail-open or optional-email fail-closed policy. The Account template eagerly loads this iframe and preconnects the browser to consent.microwavepie.com, so DNS/TLS setup can overlap the server-to-server embed-session request instead of waiting until the browser reaches the iframe. The frame remains content-height driven and does not reserve a large fixed-height area while it loads. Successful and failed embed authorization logs include elapsed_ms, which makes it possible to distinguish management-service API latency from the browser's separate consent-host navigation when tuning Cloud Run minimum instances or network behavior.
For multi-recipient Shared Content, the share UI renders recipient-specific delivery results directly beneath the recipient field. Explicit Shared Content opt-outs are shown as red blocked-recipient chips (for example 🚫 friend@example.com), successful recipients are shown separately, and SMTP failures remain distinguishable from consent suppression. This avoids making the user infer which address was blocked from a count-only message.
Service boundary and diagnostics
Blackcap uses two Microwave Pie hostnames intentionally:
tracking.microwavepie.comis the server-to-server Microwave Pie management-service hostname. Consent policy checks, Account embed-session creation, and integration diagnostics use the existing registered-instance/heartbeat bearer credential here.consent.microwavepie.comis the recipient/browser-facing Consent Management service. Manage Email Preferences links, magic links, Account iframe content, RFC 8058 one-click URLs, and the public health contract stay on this hostname.
The API Tester exposes System → Consent Management Integration Status (GET /api/system/consent-integration/status). It sends no recipient email and changes no preference. The diagnostic verifies that this Blackcap installation can authenticate to GET /api/v1/instances/consent/status on the Microwave Pie management service with its existing registered-instance identity, validates the advertised category/API contract, and independently performs an HTTPS request to https://consent.microwavepie.com/consent/health. Tokens and installation secrets are never returned.
The built-in Regression Tests run the same checks as the Consent Management Integration group. A registered online instance treats authentication, API-contract, TLS/DNS/routing, or public-host failures as regression failures. An installation without a registered Microwave Pie management-service identity skips the management-service-dependent group because offline/unregistered Blackcap does not send optional email. The regression group deliberately does not create fake contacts such as pass@.../fail@... and does not mutate any real consent preference.
Consent Management adds no Blackcap database tables or columns. Contacts, preference state/history, long-lived preference links, and short-lived iframe sessions live in Microwave Pie Consent Management. Consequently there is no Consent-specific Blackcap Database Admin resource or schema migration to display on the Blackcap Database page.
Adding a consent-aware email sender
Prefer the existing centralized send helpers. When a new sender must use SMTP directly, classify the message first and call resolve_email_consent(...) before opening SMTP. Use the returned manage_preferences_url in apply_branded_email(...), call apply_consent_headers(...) for any returned RFC 8058 metadata, and never construct consent/unsubscribe tokens in Blackcap.
For a multi-recipient optional message, honor every returned recipient decision independently. Do not expose a suppressed recipient's address to other recipients, and surface an understandable result to the initiating Blackcap user when Shared Content could not be delivered because the intended recipient opted out.