extension-email-marketing

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: extension-email-marketing
description: Send personalised marketing emails to subscribers with an unsubscribe link.
version: 0.3.0
compatibility:
  mops:
    caffeineai-email-marketing: "~0.2.2"
    caffeineai-email-verification: "~0.3.1"
    caffeineai-email: "~0.5.0"
    caffeineai-authorization: "~1.0.1"
  npm:
    "@caffeineai/email-marketing": "~0.2.0"
caffeineai-subscription: [plus, pro]
---

# Email — Marketing
Marketing email extension for [Caffeine AI](https://caffeine.ai?utm_source=caffeine-skill&utm_medium=referral).

## Overview

This skill adds direct marketing email support with subscriber management, topic-based subscriptions, and unsubscribe links that land on the app's own frontend. The backend mints one unsubscribe token per subscriber and topic (`unsubscribeTokens`) and handles it through `MixinEmailUnsubscribe`; the frontend renders the `/unsubscribe` page, where the recipient clicks a button to unsubscribe. Requires email verification before users can receive marketing emails.

## Required Setup Checklist

All six steps are mandatory.

1. **mops dependencies** — `mops add caffeineai-email-marketing`, `mops add caffeineai-email-verification` and `mops add caffeineai-authorization`.
2. **Stable state fields** — `emailSubscribers : EmailSubscribers.State` and `unsubscribeTokens : UnsubscribeTokens.State` (plus the verification states `verifiedEmails` and `verificationTokens`), initialised in the migration chain head.
3. **Mixin invocations** — `include MixinEmailUnsubscribe(emailSubscribers, unsubscribeTokens)` and `include MixinEmailVerification(verifiedEmails, verificationTokens)` in `main.mo`.
4. **Sending** — `EmailMarketing.sendMarketingEmail(emailSubscribers, verifiedEmails, unsubscribeTokens, topicId, fromUsername, subject, htmlBody, personalise)` sends to every verified subscriber of the topic; the app never assembles the recipient list. `sendMarketingEmailTo` takes explicit addresses and sends to those of them that are verified subscribers of the topic.
5. **Unsubscribe link** — the body should contain `{{UNSUBSCRIBE_URL}}`; when it is missing an unsubscribe line is appended. Every copy also carries a `List-Unsubscribe` header pointing at the same page.
6. **Frontend npm package and route** — `@caffeineai/email-marketing` installed, and a public route `/unsubscribe` (reachable without signing in) that renders a button calling `confirm()`.

CRITICAL: the unsubscribe link is `https://<app domain>/unsubscribe?token=…`. Without the frontend route the recipient lands on a missing page and cannot unsubscribe, which is a compliance failure.

# Backend

## This component is for sending direct marketing emails and managing subscribers to marketing topics.

- Users MUST have verified their email address AND MUST be subscribed to a marketing topic before they can receive marketing emails on that topic
- Marketing emails MUST contain an unsubscribe link which will unsubscribe the user from the given topic
- This component depends on the [extension-email-verification](../extension-email-verification/SKILL.md) for verifying email addresses, be sure to check that too.

### To subscribe users to marketing topics and manage lists of subscribers

- Use the prefabricated module `mo:caffeineai-email-marketing/subscribers.mo` which cannot be modified.
- Marketing email subscribers MUST be handled solely through this subscribers module
- Do NOT also store a subscribed status against user profiles
- CRITICAL: a marketing mail goes only to verified subscribers of its topic, added through `EmailSubscribers.add`. `sendMarketingEmail` reads them itself and `sendMarketingEmailTo` drops every other address, because the unsubscribe link of an address outside the topic is rejected by `_caffeineEmailUnsubscribe`, which is a compliance failure.

```mo:caffeineai-email-marketing/subscribers.mo
module {
  public type State = {
    var topics : Map.Map<Nat, TopicRecord>;
    var topicsByName : Map.Map<Text, Nat>;
  };

  // Ad