mailkit-workflow

MailKit Workflow

Purpose

Design macOS MailKit app extensions around Apple Mail’s documented handler model. MailKit supplies an MEExtension entry point and four distinct capabilities: content blocking, message actions, compose-session handling, and message security. This skill owns that Mail-specific behavior and its privacy boundary.

It does not own a mail server, IMAP/SMTP transport, account provisioning, general authentication, generic extension mechanics, or Messages/iMessage collaboration.

When To Use

• Use this skill when a macOS app needs a MailKit extension that blocks remote content, acts on downloaded messages, participates in composition, or secures messages.
• Use this skill when selecting MEContentBlocker, MEMessageActionHandler, MEComposeSessionHandler, or MEMessageSecurityHandler and their MEExtensionCapabilities declaration.
• Use app-extension-architecture-workflow when the extension point or app/extension target architecture is not yet settled.
• Use file-provider-and-finder-sync-workflow for remote files and Finder behavior, not message attachments or mail synchronization.
• Use Messaging Collaboration Skills for Messages/iMessage, communication notifications, VoIP, or Push to Talk behavior.
• Recommend xcode-build-run-workflow, xcode-testing-workflow, and macos-distribution-workflow for their respective execution boundaries.

Single-Path Workflow

1. Classify the MailKit capability:
   • use a content blocker for declarative remote-content rules shown in Mail
   • use message actions for a decision as Mail downloads a message
   • use compose sessions for recipient validation, compose-window UI, delivery suitability, or custom headers
   • use message security for encryption and digital signatures
   • split capabilities only when each one has a concrete Mail behavior and privacy case
2. State the documented MailKit behavior relied on:
   • MEExtension supplies handlers for the capabilities declared in MEExtensionCapabilities
   • enabled content-blocking extensions continue to apply their rules even when a person asks Mail to load remote content
   • message action decisions run as Mail downloads messages, not as a retroactive bulk-mail automation contract
   • compose-session approval is a delivery gate, not an excuse to silently alter recipient intent
3. Set up the target boundary:
   • keep the containing macOS app responsible for onboarding, settings, account-independent configuration, and user explanation
   • keep the Mail extension responsible for its selected MailKit handlers and short, deterministic decisions
   • declare only the chosen capabilities in the extension’s Info.plist; do not advertise handlers that are not implemented
4. Design each handler conservatively:
   • content blocker: generate narrow JSON rules, explain their effect, and provide a test corpus for allowed and blocked content
   • message action: use explicit, explainable rules and avoid irreversible actions unless the user has made the policy clear
   • compose session: validate only what the feature needs, provide focused UI when justified, fail delivery with a concrete user-readable reason, and make custom headers intentional
   • message security: identify key material, trust policy, signing/encryption state, user consent, failure recovery, and interoperable message expectations before implementation
5. Protect mail data:
   • minimize access to message bodies, recipients, headers, attachments, and remote-content identifiers
   • do not log raw message content, addresses, tokens, cryptographic material, or full headers
   • keep any shared configuration separate from message-derived data; use an App Group only when the app and extension have a documented shared-data need
6. Validate in layers:
   • verify the macOS target, extension point, MEExtensionCapabilities, signing, embedding, install, and Mail enablement state
   • test representative messages and account states in a non-production mailbox
   • test content-blocker rules, action decisions, compose allow/deny outcomes and UI, or security encryption/signature success and failure paths as applicable
   • prove that disabled, interrupted, malformed, missing-key, and offline conditions produce clear behavior without leaking mail data
7. Return the chosen handler set, documented behavior, Mail/app data boundary, privacy policy, validation matrix, and next handoff.