Email templating system

.github/workflows/test.yaml

@@ -26,7 +26,6 @@ jobs:
           pnpm --filter @courselit/common-models build
           pnpm --filter @courselit/utils build
           pnpm --filter @courselit/text-editor build
-          pnpm --filter @courselit/state-management build
           pnpm --filter @courselit/components-library build
           pnpm --filter @courselit/page-primitives build
           pnpm --filter @courselit/page-blocks build

.gitignore

@@ -44,4 +44,5 @@ report*.json
 globalConfig.json
 
 # CourseLit files
-domains_to_delete.txt
+domains_to_delete.txt
+.codex

AGENTS.md

@@ -6,6 +6,7 @@
 - Command for running tests: `pnpm test`.
 - The project uses shadcn for building UI so stick to its conventions and design.
 - In `apps/web` workspace, create a string first in `apps/web/config/strings.ts` and then import it in the `.tsx` files, instead of using inline strings.
+- For admin/dashboard empty states in `apps/web`, prefer reusing `apps/web/components/admin/empty-state.tsx` instead of creating one-off placeholder UIs.
 - When working with forms, always use refs to keep the current state of the form's data and use it to enable/disable the form submit button.
 - Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
 - While working with forms, always use zod and react-hook-form to validate the form. Take reference implementation from `apps/web/components/admin/settings/sso/new.tsx`.

apps/docs/package.json

@@ -18,7 +18,7 @@
         "@docsearch/css": "^3.1.0",
         "@docsearch/react": "^3.1.0",
         "@types/node": "^18.0.0",
-        "@types/react": "^17.0.45",
+        "@types/react": "^18.0.0",
         "@types/react-dom": "^18.0.0",
         "astro": "^1.4.2",
         "preact": "^10.7.3",

apps/docs/src/config.ts

@@ -96,6 +96,10 @@ export const SIDEBAR: Sidebar = {
                 text: "Sequences (Campaigns)",
                 link: "en/email-marketing/sequences",
             },
+            {
+                text: "Templates",
+                link: "en/email-marketing/templates",
+            },
             {
                 text: "Analytics",
                 link: "en/email-marketing/analytics",

apps/docs/src/pages/en/email-marketing/broadcasts.md

@@ -20,7 +20,9 @@ From the `Dashboard`, go to `Mails` to land on the `Broadcasts` hub. Here, you w
 
 1. Click the `New broadcast` button on the right, in the `Broadcasts` hub.
 
-2. Let's get acquainted with the interface. In the following image, we have marked all the sections. To see the description of a section, note its number in the screenshot and find its description below.
+2. You will see a template selection screen. Click the template you'd like to use as a starting point. After selecting it, You will be redirected to the broadcast management screen. The active tab will be `Compose`.
+
+3. Let's get acquainted with the interface. In the following image, we have marked all the sections. To see the description of a section, note its number in the screenshot and find its description below.
 
     -   1. **User Filters**: To select the users.
     -   2. **Total Selected Users**: The total number of selected users as per the applied filters.
@@ -33,7 +35,7 @@ From the `Dashboard`, go to `Mails` to land on the `Broadcasts` hub. Here, you w
 
     ![Broadcast Compose](/assets/emails/compose-broadcast.png)
 
-3. Upon clicking the **Mail Edit** button, a full-page email editor will open where you can edit the email.
+4. Upon clicking the **Mail Edit** button, a full-page email editor will open where you can edit the email.
 
     > When done, simply press the exit button. All changes are auto-saved.
 
@@ -46,7 +48,7 @@ From the `Dashboard`, go to `Mails` to land on the `Broadcasts` hub. Here, you w
     -   3. **Settings Pane**: The settings pane for the email and the selected block.
     -   4. **Exit Button**: The email editor exit button.
 
-4. If you are not yet ready to send the email or schedule it, you can simply go back to the Broadcasts hub by clicking on the `Broadcasts` breadcrumb (located at the top of the page).
+5. If you are not yet ready to send the email or schedule it, you can simply go back to the Broadcasts hub by clicking on the `Broadcasts` breadcrumb (located at the top of the page).
 
 ## Send Immediately
 
@@ -71,6 +73,7 @@ Once an email is scheduled, you will see the time it will be sent at the bottom,
 Now that you understand how to send broadcasts, you can also see:
 
 - [Set up automated email sequences](/en/email-marketing/sequences)
+- [Create re-usable templates](/en/email-marketing/templates)
 - [Track your email performance with analytics](/en/email-marketing/analytics)
 
 ## Stuck Somewhere?

apps/docs/src/pages/en/email-marketing/sequences.md

@@ -1,5 +1,5 @@
 ---
-title: Email sequences
+title: Sequences
 description: Send email sequences to your audience
 layout: ../../../layouts/MainLayout.astro
 ---
@@ -26,34 +26,36 @@ Here, you will see all the sequences you have configured.
 
 You will be redirected to the sequence compose screen. The active tab will be `Compose`.
 
-2. Let's get acquainted with the interface.
+2. You will see a template selection screen. Click the template you'd like to use as a starting point. After selecting it, You will be redirected to the sequence management screen. The active tab will be `Compose`.
+
+3. Let's get acquainted with the interface.
 
 In the following image, we have marked all the sections. To see the description of a section, note its number in the screenshot and find its description below.
 
-    -   1. **Sequence Name**: The internal name of the sequence.
-    -   2. **From**: The sender's name that is displayed in the emails sent.
-    -   3. **Entrance Condition**: The condition that triggers this sequence for a user. You can pick from the following conditions:
-        - `Tag added`
-        - `Tag removed`
-        - `Product purchased`
-        - `Subscriber added`
-        - `Community joined`
-        - `Community left`
-    -   4. **Entrance Condition Data**: The exact tag or product that triggers the sequence. This field is only relevant in the context of the `Entrance Condition` field.
-    -   5. **Save**: A button to save your changes to the sequence.
-    -   6. **Start/Pause**: A button to start or pause the sequence. Once paused, the sequence won't be triggered for subsequent events in the system.
-    -   7. **Email Row**: Shows an overview of one of the emails in the sequence.
-    -   8. **New Email Button**: A button to add a new email to the sequence.
+![Sequence Compose](/assets/emails/compose-sequence.png)
 
-    ![Sequence Compose](/assets/emails/compose-sequence.png)
+-   1. **Sequence Name**: The internal name of the sequence.
+-   2. **From**: The sender's name that is displayed in the emails sent.
+-   3. **Entrance Condition**: The condition that triggers this sequence for a user. You can pick from the following conditions:
+    - `Tag added`
+    - `Tag removed`
+    - `Product purchased`
+    - `Subscriber added`
+    - `Community joined`
+    - `Community left`
+-   4. **Entrance Condition Data**: The exact tag or product that triggers the sequence. This field is only relevant in the context of the `Entrance Condition` field.
+-   5. **Save**: A button to save your changes to the sequence.
+-   6. **Start/Pause**: A button to start or pause the sequence. Once paused, the sequence won't be triggered for subsequent events in the system.
+-   7. **Email Row**: Shows an overview of one of the emails in the sequence.
+-   8. **New Email Button**: A button to add a new email to the sequence.
 
-3. Fill in the details for `Sequence Name`, `From`, `Entrance Condition`, and `Entrance Condition Data` (if applicable), then hit `Save`.
+4. Fill in the details for `Sequence Name`, `From`, `Entrance Condition`, and `Entrance Condition Data` (if applicable), then hit `Save`.
 
-4. Start adding emails to this sequence. When you create a new sequence, an empty email is added to it by default.
+5. Start adding emails to this sequence. When you create a new sequence, an empty email is added to it by default.
 
     ![Sequence add email](/assets/emails/compose-sequence-add-email.jpeg)
 
-5. Let's understand what information an email row shows:
+6. Let's understand what information an email row shows:
 
     ![Sequence email row](/assets/emails/compose-sequence-email-row.jpeg)
 
@@ -64,9 +66,9 @@ In the following image, we have marked all the sections. To see the description
 
     > The default email has `0 days` as the delay, which means the email will be sent immediately after the user enters the sequence, as it is the first email in the sequence.
 
-6. To edit an email, click on the subject. This will open the email compose screen as shown below.
+7. To edit an email, click on the subject. This will open the email compose screen as shown below.
 
-7. Let's get acquainted with the email compose interface:
+8. Let's get acquainted with the email compose interface:
 
     -   1. **Delay**: The delay (in days) between this email and the previous one.
     -   2. **Subject**: The email's subject.
@@ -78,8 +80,8 @@ In the following image, we have marked all the sections. To see the description
 
     ![Sequence's Email Compose](/assets/emails/compose-sequence-email.png)
 
-8. Edit the email's subject and status, then hit `Save`.
-9. Edit the email's content by clicking on the mail edit button. Upon clicking the **Mail Edit** button, a full-page email editor will open where you can edit the email.
+9. Edit the email's subject and status, then hit `Save`.
+10. Edit the email's content by clicking on the mail edit button. Upon clicking the **Mail Edit** button, a full-page email editor will open where you can edit the email.
 
     > When done, simply press the exit button. All changes are auto-saved.
 
@@ -92,18 +94,19 @@ In the following image, we have marked all the sections. To see the description
     -   3. **Settings Pane**: The settings pane for the email and the selected block.
     -   4. **Exit Button**: The email editor exit button.
 
-10. To go back to the sequence settings, click on the `Compose sequence` breadcrumb as shown below.
+11. To go back to the sequence settings, click on the `Compose sequence` breadcrumb as shown below.
 
     ![Go Back to Sequence Settings](/assets/emails/back-to-sequence-breadcrumb.png)
 
-11. Add more emails to the sequence by clicking on the `New email` button.
-12. Keep editing your sequence until you think it's perfect. Once you are satisfied with your sequence, hit the `Start` button to begin sending this sequence to users.
+12. Add more emails to the sequence by clicking on the `New email` button.
+13. Keep editing your sequence until you think it's perfect. Once you are satisfied with your sequence, hit the `Start` button to begin sending this sequence to users.
 
 ## Next Steps
 
 Now that you understand how to create email sequences, you can also see:
 
 - [Send one-off broadcasts](/en/email-marketing/broadcasts)
+- [Create re-usable templates](/en/email-marketing/templates)
 - [Track your email performance with analytics](/en/email-marketing/analytics)
 
 ## Stuck Somewhere?

apps/docs/src/pages/en/email-marketing/templates.md

@@ -0,0 +1,99 @@
+---
+title: Templates
+description: Create reusable email templates for broadcasts and sequences
+layout: ../../../layouts/MainLayout.astro
+---
+
+Email templates help you build a reusable library of branded email layouts. Once saved, you can use them while creating broadcasts or sequence emails.
+
+> This feature is currently in beta, which means you may encounter bugs. Please report them in our <a href="https://discord.com/invite/GR4bQsN" target="_blank">Discord</a> group if you run into any issues.
+
+> **Before you start**: If your school is hosted on [courselit.app](https://courselit.app), you need to get approved to send marketing emails. [Request access here](/en/email-marketing/mail-access-request).
+
+## Templates Hub
+
+From the `Dashboard`, go to `Mails` and open the `Templates` tab.
+
+Here, you will see all templates you have saved.
+
+- If this is your first template, click `Create from template`.
+- If you already have templates, click `New template`.
+
+![Templates Hub](/assets/emails/email-templates-hub.png)
+
+## Create a Template
+
+1. Open the `Templates` tab and click `Create from template` (or `New template`).
+2. You will be taken to the `Choose a template` screen.
+
+    ![Templates selection screen](/assets/emails/email-template-selection-screen.png)
+
+3. Review the available sections:
+
+    - **System**: Built-in starter templates.
+    - **My templates**: Your saved templates.
+
+4. Click any template card in the `System` section to start from it.
+
+CourseLit will create a new custom template and open its `Manage` screen.
+
+## Edit a Template
+
+On the `Manage` screen, you can control the template settings and content.
+
+![Template management](/assets/emails/email-template-manage-screen.png)
+
+### Edit title
+
+1. Update the `Template name`.
+2. Click `Save` to persist the new name.
+
+### Edit content
+
+1. Click the edit button on the preview (pencil icon) to open the full email editor.
+
+    ![Template edit button](/assets/emails/email-template-manage-edit-button.png)
+
+2. Edit blocks, styles, and variables in the editor.
+
+    ![Email editor invoked via template manage screen](/assets/emails/email-editor-via-template.png)
+
+> Template content is auto-saved while editing.
+
+3. Click `Exit` to return to the template `Manage` screen.
+
+## Use Templates in Broadcasts and Sequences
+
+You can use templates while creating emails:
+
+1. Go to `Mails`.
+2. Click `New broadcast` or `New sequence`.
+3. On the `Choose a template` page, select one from:
+
+    - `System` (starter templates)
+    - `My templates` (your saved templates)
+
+4. Continue editing subject, audience/trigger details, and send settings as needed.
+
+You can also add a template to an existing sequence by creating a new email in that sequence and selecting a template.
+
+## Delete a Template
+
+1. Open `Mails` → `Templates`.
+2. Open the template you want to remove.
+3. In `Danger zone`, click `Delete template`.
+4. Confirm deletion in the dialog.
+
+> Template deletion is permanent and cannot be undone.
+
+## Next Steps
+
+Now that you know how templates work, you can:
+
+- [Send one-off broadcasts](/en/email-marketing/broadcasts)
+- [Set up automated email sequences](/en/email-marketing/sequences)
+- [Track your email performance with analytics](/en/email-marketing/analytics)
+
+## Stuck Somewhere?
+
+We are always here for you. Come chat with us in our <a href="https://discord.com/invite/GR4bQsN" target="_blank">Discord</a> channel or send a tweet to <a href="https://twitter.com/courselit" target="_blank">@CourseLit</a>.