Browse documentation

🧭 Start Here

Blackcap Overview ✨ Blackcap Feature Catalog 🤖 AI Features 🧱 Technology, Administration, and Reliability Installation First Run

📘 User Guides

Administration and Operations Platform Configuration Organization Configuration Email and Consent Management

🚀 Deploy Blackcap

Platform Stacks and Raspberry Pi Hardware Raspberry Pi Deployment Raspberry Pi Client Services GCP Deployment Packaged Blackcap deployment Application Updates After Your First Blackcap Login: Self-Hosted Setup Guide Blackcap Release Notes Environment Variables and Secrets Reverse Proxy and TLS Background Jobs and Schedules

🛠️ Administer Blackcap

Organizations Users, Permissions, and Authentication Configuration Workspace Backups and Restore Database Administration Regression Testing Performance and Job Status Audit, Access Activity, and Logging GeoIP and Access Location Data Retention and Purge Support Chat Administration Support Requests API Tester and Postman Instance Reporting Third-Party Packages and Attribution AI Provider Usage and Billing Portals Microwave Pie licensing for Blackcap Microwave Pie licensing for Blackcap

🍽️ Use Recipes

Recipes and the Recipe Library Recipe Import and Discovery Recipe Editing and Cache Artifacts Recipe Sharing Social Recipe Import AI Recipe Image Generation 🪄 Adapt Recipe and 🎲 Variations

📅 Plan Meals

Meal Planner

🛒 Use Shopping Lists

Shopping Lists and Shop a List External and Household Shopping 🔗 Chrome Extension Shop With

🧺 Manage Kitchen Inventory

🧺 Kitchen Inventory

🖥️ Use Displays

Displays and Connections Assigning and Scheduling Display Content Remote Pi Client E-Ink Rendering Menu Refresh and Rendering Noun Project Footer Images

🧑‍🍳 Cook with Let’s Cook

🧑‍🍳 Let’s Cook 🧑‍🍳 Let’s Cook Controls and Timers

🤖 Use and Administer AI

🤖 AI in Blackcap 🤖 AI Providers and Connections 🤖 AI Seeds and Usage Support Chat

🔗 Use the Chrome Extension

🔗 Blackcap Chrome Extension 🔗 Chrome Extension Recipe Capture 🔗 Chrome Extension Shop With 🔗 Chrome Extension Release and Privacy

🎮 Play Games

Games and trivia Bramble Harvest — Player Guide Flavor Lab — Player Guide

🔌 Integrations

Email Integration Cloud Storage Integrations Voice Assistants Shop With Integrations Authentication Providers

⚙️ Develop Blackcap

Application Architecture Database Service and Data Access SQLite and PostgreSQL Database Migrations Background Job Architecture Testing Games platform — current developer reference Bramble Harvest developer tools API Architecture Security and Organization Scoping UI, Icons, and Documentation Assets Blackcap-Safe Emoji Support Chat Architecture Extending Support Chat Support Chat Model Benchmark Documentation Standards Terminology

⚠️ Troubleshoot Blackcap

⚠️ Troubleshooting Licensing Troubleshooting Deployment Troubleshooting Display Troubleshooting Recipe Import Troubleshooting 🤖 AI Troubleshooting Backup Troubleshooting Database Troubleshooting Diagnostic Organization Clones Support Chat

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_name
  • email.blackcap_logo_url
  • email.microwave_pie_logo_url
  • email.branding_website_url
  • email.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.

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.com is 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.com is 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.

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.

On this page