@carlonicora/nextjs-jsonapi 6.14.1 → 6.16.0

package/src/features/email-automation/components/forms/EmailAutomationEditor.tsx

@@ -12,6 +12,7 @@ import { useI18nRouter } from "../../../../i18n";
 import { EmailAutomationInput, EmailAutomationInterface } from "../../data/EmailAutomationInterface";
 import { EmailAutomationService } from "../../data/EmailAutomationService";
 import { EmailAutomationTriggerInterface } from "../../data/EmailAutomationTriggerInterface";
+import { EmailPurpose } from "../../data/EmailPurpose";
 
 export type EmailAutomationEditorProps = {
   automation?: EmailAutomationInterface;
@@ -65,6 +66,7 @@ function EmailAutomationEditorInternal({
           message: t("emailAutomations.fields.replyTo.error"),
         }),
         isActive: z.boolean(),
+        purpose: z.enum(["service", "marketing"], { message: t("emailPurpose.error") }),
       }),
     [t],
   );
@@ -77,6 +79,8 @@ function EmailAutomationEditorInternal({
       exitTrigger: automation?.exitTrigger ?? "",
       replyTo: automation?.replyTo ?? "",
       isActive: automation?.isActive ?? false,
+      // No preselected value on create: the form refuses to save without a choice.
+      purpose: (automation?.purpose ?? "") as EmailPurpose,
     }),
     [automation],
   );
@@ -86,6 +90,15 @@ function EmailAutomationEditorInternal({
     defaultValues: getDefaultValues(),
   });
 
+  const purpose = form.watch("purpose");
+  const purposeValues = useMemo(
+    () => [
+      { id: "service", text: t("emailPurpose.service") },
+      { id: "marketing", text: t("emailPurpose.marketing") },
+    ],
+    [t],
+  );
+
   return (
     <EditorSheet
       form={form}
@@ -106,6 +119,7 @@ function EmailAutomationEditorInternal({
           exitTrigger: values.exitTrigger || undefined,
           replyTo: values.replyTo || undefined,
           isActive: values.isActive,
+          purpose: values.purpose,
         };
         return isEdit ? await EmailAutomationService.update(payload) : await EmailAutomationService.create(payload);
       }}
@@ -118,6 +132,15 @@ function EmailAutomationEditorInternal({
     >
       <div className="flex w-full flex-col gap-y-4">
         <FormInput form={form} id="name" name={t("emailAutomations.fields.name.label")} isRequired />
+        <FormSelect
+          form={form}
+          id="purpose"
+          name={t("emailPurpose.label")}
+          placeholder={t("emailPurpose.placeholder")}
+          values={purposeValues}
+          description={purpose === "service" ? t("emailPurpose.serviceWarning") : undefined}
+          isRequired
+        />
         <FormSelect
           form={form}
           id="trigger"

package/src/features/email-automation/components/forms/EmailStepEditor.tsx

@@ -13,7 +13,9 @@ import { EmailAutomationStepInput, EmailAutomationStepInterface } from "../../da
 import { EmailAutomationStepService } from "../../data/EmailAutomationStepService";
 
 /** The fixed variable set the renderer fills (spec § "Rendering"). */
-const TEMPLATE_VARIABLES = ["{{name}}", "{{email}}", "{{url}}", "{{unsubscribeUrl}}", "{{unsubscribeAllUrl}}"];
+const TEMPLATE_VARIABLES = ["{{name}}", "{{email}}", "{{url}}", "{{unsubscribeUrl}}"];
+/** Only a Marketing automation fills it: a Service email has no "stop all marketing emails" link. */
+const MARKETING_ONLY_VARIABLES = ["{{unsubscribeAllUrl}}"];
 
 export type EmailStepEditorProps = {
   step?: EmailAutomationStepInterface;
@@ -43,8 +45,10 @@ function EmailStepEditorInternal({
   onSuccess,
 }: EmailStepEditorProps) {
   const t = useTranslations();
-  const { reload } = useEmailAutomation();
+  const { automation, reload } = useEmailAutomation();
   const isEdit = !!step;
+  const templateVariables =
+    automation?.purpose === "service" ? TEMPLATE_VARIABLES : [...TEMPLATE_VARIABLES, ...MARKETING_ONLY_VARIABLES];
 
   const formSchema = useMemo(
     () =>
@@ -129,7 +133,7 @@ function EmailStepEditorInternal({
             <>
               <span className="block">
                 {t("emailAutomations.step.variablesHint")}{" "}
-                {TEMPLATE_VARIABLES.map((variable) => (
+                {templateVariables.map((variable) => (
                   <span key={variable} className="me-2 text-foreground">
                     {variable}
                   </span>

package/src/features/email-automation/components/index.ts

@@ -4,6 +4,7 @@ export * from "./lists/EmailAutomationsList";
 export * from "./lists/EmailAutomationRecipientsList";
 export * from "./forms/EmailAutomationEditor";
 export * from "./forms/EmailStepEditor";
+export * from "./forms/EmailAutomationAddPersonDialog";
 export * from "./canvas/EmailAutomationActiveSwitch";
 export * from "./canvas/EmailAutomationCanvasTab";
 export * from "./canvas/EmailAutomationCanvas";

package/src/features/email-automation/components/lists/EmailAutomationRecipientsList.tsx

@@ -8,18 +8,20 @@ import { Modules } from "../../../../core";
 import { DataListRetriever, useDataListRetriever } from "../../../../hooks";
 import { Button, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../../../../shadcnui";
 import { useEmailAutomation } from "../../contexts/EmailAutomationContext";
+import { EmailAutomationAddPersonDialog } from "../forms/EmailAutomationAddPersonDialog";
 import { EmailAutomationEnrollmentFields } from "../../data/email-automation-enrollment.fields";
 import { EmailAutomationEnrollmentInterface } from "../../data/EmailAutomationEnrollmentInterface";
 import { EmailAutomationService } from "../../data/EmailAutomationService";
 
 /**
- * Read-only list of the people in this automation (owner decision 6: no row
- * actions). Rendered inside a tab, so it keeps its own bordered card (no
- * `fullWidth`), as PricesList does inside ProductContainer.
+ * List of the people in this automation (owner decision 6: no row actions; a
+ * person is added by hand through "Add person" in the filters). Rendered inside
+ * a tab, so it keeps its own bordered card (no `fullWidth`), as PricesList does
+ * inside ProductContainer.
  */
 export function EmailAutomationRecipientsList() {
   const t = useTranslations();
-  const { automation } = useEmailAutomation();
+  const { automation, reload } = useEmailAutomation();
   const [statusFilter, setStatusFilter] = useState<string>("all");
 
   const data: DataListRetriever<EmailAutomationEnrollmentInterface> = useDataListRetriever({
@@ -48,6 +50,17 @@ export function EmailAutomationRecipientsList() {
 
   const filters = (
     <div className="flex items-center gap-4">
+      {automation && (
+        <EmailAutomationAddPersonDialog
+          automationId={automation.id}
+          disabled={automation.stepCount === 0}
+          onAdded={() => {
+            void data.refresh();
+            void reload();
+          }}
+        />
+      )}
+
       <Select items={statusItems} value={statusFilter} onValueChange={handleStatusChange}>
         <SelectTrigger className="w-40">
           <SelectValue />
@@ -69,22 +82,27 @@ export function EmailAutomationRecipientsList() {
   );
 
   return (
-    <ContentListTable
-      data={data}
-      fields={[
-        EmailAutomationEnrollmentFields.email,
-        EmailAutomationEnrollmentFields.name,
-        EmailAutomationEnrollmentFields.status,
-        EmailAutomationEnrollmentFields.currentStep,
-        EmailAutomationEnrollmentFields.nextSendAt,
-        EmailAutomationEnrollmentFields.sentCount,
-      ]}
-      tableGeneratorType={Modules.EmailAutomationEnrollment}
-      filters={filters}
-      /* The enrolments endpoint takes no search term, so rendering the box would
+    <div data-testid="email-automation-recipients">
+      <ContentListTable
+        data={data}
+        fields={[
+          EmailAutomationEnrollmentFields.email,
+          EmailAutomationEnrollmentFields.name,
+          EmailAutomationEnrollmentFields.status,
+          EmailAutomationEnrollmentFields.currentStep,
+          EmailAutomationEnrollmentFields.nextSendAt,
+          EmailAutomationEnrollmentFields.sentCount,
+        ]}
+        tableGeneratorType={Modules.EmailAutomationEnrollment}
+        /* ContentListTable renders its filters only inside the title bar, so the
+         list needs a title for "Add person" and the status filter to show. */
+        title={t("emailAutomations.tabs.recipients")}
+        filters={filters}
+        /* The enrolments endpoint takes no search term, so rendering the box would
          give the page a control that silently does nothing. */
-      allowSearch={false}
-      emptyState={t("emailAutomations.recipients.empty")}
-    />
+        allowSearch={false}
+        emptyState={t("emailAutomations.recipients.empty")}
+      />
+    </div>
   );
 }

package/src/features/email-automation/components/lists/EmailAutomationsList.tsx

@@ -58,6 +58,7 @@ export function EmailAutomationsList({ fullWidth }: EmailAutomationsListProps =
       data={data}
       fields={[
         EmailAutomationFields.name,
+        EmailAutomationFields.purpose,
         EmailAutomationFields.trigger,
         EmailAutomationFields.status,
         EmailAutomationFields.steps,

package/src/features/email-automation/components/unsubscribe/EmailUnsubscribe.tsx

@@ -27,6 +27,8 @@ export function EmailUnsubscribe({ token, scope, source = "automation" }: Props)
   const [state, setState] = useState<UnsubscribeState>("loading");
   const [stoppedScope, setStoppedScope] = useState<UnsubscribeScope>(scope);
   const [automationName, setAutomationName] = useState<string>("");
+  // A Service automation is not a marketing email: its page offers only "Stop these emails".
+  const [isServiceAutomation, setIsServiceAutomation] = useState<boolean>(false);
   const [isStoppingAll, setIsStoppingAll] = useState<boolean>(false);
 
   useEffect(() => {
@@ -40,6 +42,7 @@ export function EmailUnsubscribe({ token, scope, source = "automation" }: Props)
         }
         const enrollment = await EmailAutomationEnrollmentService.unsubscribe({ token, scope });
         setAutomationName(enrollment?.automation?.name ?? "");
+        setIsServiceAutomation(enrollment?.automation?.purpose === "service");
         setStoppedScope(scope);
         setState("success");
       } catch {
@@ -100,10 +103,12 @@ export function EmailUnsubscribe({ token, scope, source = "automation" }: Props)
           <p className="text-muted-foreground max-w-md text-sm leading-relaxed">
             {t("emailAutomations.unsubscribe.stoppedAutomation", { name: automationName })}
           </p>
-          <Button variant="secondary" onClick={stopAll} disabled={isStoppingAll}>
-            {isStoppingAll && <Loader2 className="h-4 w-4 animate-spin" />}
-            {t("emailAutomations.unsubscribe.alsoStopAll")}
-          </Button>
+          {!isServiceAutomation && (
+            <Button variant="secondary" onClick={stopAll} disabled={isStoppingAll}>
+              {isStoppingAll && <Loader2 className="h-4 w-4 animate-spin" />}
+              {t("emailAutomations.unsubscribe.alsoStopAll")}
+            </Button>
+          )}
         </>
       )}
     </div>

package/src/features/email-automation/data/EmailAutomation.ts

@@ -1,5 +1,6 @@
 import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
 import { EmailAutomationInput, EmailAutomationInterface } from "./EmailAutomationInterface";
+import { EmailPurpose } from "./EmailPurpose";
 
 export class EmailAutomation extends AbstractApiData implements EmailAutomationInterface {
   private _name?: string;
@@ -7,6 +8,7 @@ export class EmailAutomation extends AbstractApiData implements EmailAutomationI
   private _exitTrigger?: string;
   private _replyTo?: string;
   private _isActive: boolean = false;
+  private _purpose: EmailPurpose = "marketing";
   private _stepCount?: number;
   private _activeCount?: number;
   private _completedCount?: number;
@@ -32,6 +34,10 @@ export class EmailAutomation extends AbstractApiData implements EmailAutomationI
     return this._isActive;
   }
 
+  get purpose(): EmailPurpose {
+    return this._purpose;
+  }
+
   get stepCount(): number {
     return this._stepCount ?? 0;
   }
@@ -56,6 +62,8 @@ export class EmailAutomation extends AbstractApiData implements EmailAutomationI
     this._exitTrigger = data.jsonApi.attributes.exitTrigger ?? undefined;
     this._replyTo = data.jsonApi.attributes.replyTo ?? undefined;
     this._isActive = data.jsonApi.attributes.isActive === true;
+    // A record saved before purpose existed counts as Marketing.
+    this._purpose = data.jsonApi.attributes.purpose === "service" ? "service" : "marketing";
     this._stepCount = data.jsonApi.attributes.stepCount;
     this._activeCount = data.jsonApi.attributes.activeCount;
     this._completedCount = data.jsonApi.attributes.completedCount;
@@ -81,6 +89,7 @@ export class EmailAutomation extends AbstractApiData implements EmailAutomationI
     if (data.exitTrigger !== undefined) response.data.attributes.exitTrigger = data.exitTrigger;
     if (data.replyTo !== undefined) response.data.attributes.replyTo = data.replyTo;
     if (data.isActive !== undefined) response.data.attributes.isActive = data.isActive;
+    if (data.purpose !== undefined) response.data.attributes.purpose = data.purpose;
 
     return response;
   }

package/src/features/email-automation/data/EmailAutomationCandidate.ts

@@ -0,0 +1,66 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import {
+  EmailAutomationCandidateInterface,
+  EmailAutomationCandidateReason,
+  EmailAutomationRecipientType,
+} from "./EmailAutomationCandidateInterface";
+
+export class EmailAutomationCandidate extends AbstractApiData implements EmailAutomationCandidateInterface {
+  private _recipientType: EmailAutomationRecipientType = "user";
+  private _recipientId?: string;
+  private _email?: string;
+  private _name?: string;
+  private _addable?: boolean;
+  private _reason?: EmailAutomationCandidateReason;
+
+  get recipientType(): EmailAutomationRecipientType {
+    return this._recipientType;
+  }
+
+  get recipientId(): string {
+    return this._recipientId ?? "";
+  }
+
+  get email(): string {
+    return this._email ?? "";
+  }
+
+  get name(): string | undefined {
+    return this._name;
+  }
+
+  get addable(): boolean {
+    return this._addable ?? false;
+  }
+
+  get reason(): EmailAutomationCandidateReason | undefined {
+    return this._reason;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes;
+    this._recipientType = attributes.recipientType === "waitlist" ? "waitlist" : "user";
+    this._recipientId = attributes.recipientId;
+    this._email = attributes.email;
+    this._name = attributes.name ?? undefined;
+    this._addable = attributes.addable === true;
+    this._reason = attributes.reason ?? undefined;
+
+    return this;
+  }
+
+  /**
+   * The API computes candidates and never accepts one as a request body; this
+   * only identifies the resource.
+   */
+  createJsonApi(data: { id: string }) {
+    return {
+      data: {
+        type: Modules.EmailAutomationCandidate.name,
+        id: data.id,
+      },
+    };
+  }
+}

package/src/features/email-automation/data/EmailAutomationCandidateInterface.ts

@@ -0,0 +1,19 @@
+import { ApiDataInterface } from "../../../core";
+
+export type EmailAutomationRecipientType = "user" | "waitlist";
+
+export type EmailAutomationCandidateReason = "already_enrolled" | "opted_out" | "no_consent";
+
+/**
+ * A person the administrator may add to an automation by hand. The API decides
+ * whether they can be added (`addable`) and why not (`reason`); the browser only
+ * displays it.
+ */
+export interface EmailAutomationCandidateInterface extends ApiDataInterface {
+  get recipientType(): EmailAutomationRecipientType;
+  get recipientId(): string;
+  get email(): string;
+  get name(): string | undefined;
+  get addable(): boolean;
+  get reason(): EmailAutomationCandidateReason | undefined;
+}

package/src/features/email-automation/data/EmailAutomationEnrollment.ts

@@ -1,5 +1,6 @@
 import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
 import {
+  EmailAutomationEnrollmentInput,
   EmailAutomationEnrollmentInterface,
   EmailAutomationEnrollmentStatus,
 } from "./EmailAutomationEnrollmentInterface";
@@ -85,8 +86,21 @@ export class EmailAutomationEnrollment extends AbstractApiData implements EmailA
     return this;
   }
 
-  createJsonApi(_data?: any): any {
-    throw new Error("EmailAutomationEnrollment is created by the API and cannot be created from the client");
+  /**
+   * Body of POST email-automations/:id/email-automation-enrollments: an
+   * administrator adds a person by hand. The API enrols them at the first step.
+   */
+  createJsonApi(data: EmailAutomationEnrollmentInput) {
+    return {
+      data: {
+        type: Modules.EmailAutomationEnrollment.name,
+        id: data.id,
+        attributes: {
+          recipientType: data.recipientType,
+          recipientId: data.recipientId,
+        },
+      },
+    };
   }
 
   /**

package/src/features/email-automation/data/EmailAutomationEnrollmentInterface.ts

@@ -3,6 +3,13 @@ import { EmailAutomationInterface } from "./EmailAutomationInterface";
 
 export type EmailAutomationEnrollmentStatus = "active" | "completed" | "unsubscribed" | "exited" | "failed";
 
+/** Body of POST email-automations/:id/email-automation-enrollments (manual add). */
+export type EmailAutomationEnrollmentInput = {
+  id: string;
+  recipientType: "user" | "waitlist";
+  recipientId: string;
+};
+
 export interface EmailAutomationEnrollmentInterface extends ApiDataInterface {
   get email(): string;
   get name(): string | undefined;

package/src/features/email-automation/data/EmailAutomationInterface.ts

@@ -1,4 +1,5 @@
 import { ApiDataInterface } from "../../../core";
+import { EmailPurpose } from "./EmailPurpose";
 
 export type EmailAutomationInput = {
   id: string;
@@ -7,6 +8,7 @@ export type EmailAutomationInput = {
   exitTrigger?: string;
   replyTo?: string;
   isActive?: boolean;
+  purpose?: EmailPurpose;
 };
 
 export interface EmailAutomationInterface extends ApiDataInterface {
@@ -15,6 +17,7 @@ export interface EmailAutomationInterface extends ApiDataInterface {
   get exitTrigger(): string | undefined;
   get replyTo(): string | undefined;
   get isActive(): boolean;
+  get purpose(): EmailPurpose;
   get stepCount(): number;
   get activeCount(): number;
   get completedCount(): number;

package/src/features/email-automation/data/EmailAutomationService.ts

@@ -1,5 +1,9 @@
 import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../core";
-import { EmailAutomationEnrollmentInterface } from "./EmailAutomationEnrollmentInterface";
+import { EmailAutomationCandidateInterface } from "./EmailAutomationCandidateInterface";
+import {
+  EmailAutomationEnrollmentInput,
+  EmailAutomationEnrollmentInterface,
+} from "./EmailAutomationEnrollmentInterface";
 import { EmailAutomationInput, EmailAutomationInterface } from "./EmailAutomationInterface";
 import { EmailAutomationTriggerInterface } from "./EmailAutomationTriggerInterface";
 
@@ -103,4 +107,52 @@ export class EmailAutomationService extends AbstractService {
       previous: params.previous,
     });
   }
+
+  /**
+   * GET email-automations/:id/email-automation-candidates: users and waitlist
+   * entries matching the search, each flagged addable or not by the API. Paged:
+   * read through useDataListRetriever, which passes the next/previous refs.
+   */
+  static async findCandidates(params: {
+    automationId: string;
+    search?: string;
+    next?: NextRef;
+    previous?: PreviousRef;
+  }): Promise<EmailAutomationCandidateInterface[]> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.EmailAutomation,
+      id: params.automationId,
+      childEndpoint: Modules.EmailAutomationCandidate,
+    });
+
+    if (params.search) endpoint.addAdditionalParam("search", params.search);
+
+    return this.callApi<EmailAutomationCandidateInterface[]>({
+      type: Modules.EmailAutomationCandidate,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+      previous: params.previous,
+    });
+  }
+
+  /**
+   * POST email-automations/:id/email-automation-enrollments: adds one person by
+   * hand. The API re-checks every rule and answers 400 with the reason.
+   */
+  static async addEnrollment(params: {
+    automationId: string;
+    input: EmailAutomationEnrollmentInput;
+  }): Promise<EmailAutomationEnrollmentInterface> {
+    return this.callApi<EmailAutomationEnrollmentInterface>({
+      type: Modules.EmailAutomationEnrollment,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.EmailAutomation,
+        id: params.automationId,
+        childEndpoint: Modules.EmailAutomationEnrollment,
+      }).generate(),
+      input: params.input,
+    });
+  }
 }

package/src/features/email-automation/data/EmailPurpose.ts

@@ -0,0 +1 @@
+export type EmailPurpose = "service" | "marketing";

package/src/features/email-automation/data/__tests__/email-automation-models.spec.ts

@@ -1,11 +1,13 @@
 import { beforeAll, describe, expect, it } from "vitest";
 import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
 import { ModuleFactory, ModuleWithPermissions } from "../../../../permissions/types";
+import { EmailAutomationCandidateModule } from "../../EmailAutomationCandidateModule";
 import { EmailAutomationEnrollmentModule } from "../../EmailAutomationEnrollmentModule";
 import { EmailAutomationModule } from "../../EmailAutomationModule";
 import { EmailAutomationStepModule } from "../../EmailAutomationStepModule";
 import { EmailAutomationTriggerModule } from "../../EmailAutomationTriggerModule";
 import { EmailAutomation } from "../EmailAutomation";
+import { EmailAutomationCandidate } from "../EmailAutomationCandidate";
 import { EMAIL_AUTOMATION_UNSUBSCRIBE_TYPE, EmailAutomationEnrollment } from "../EmailAutomationEnrollment";
 import { EmailAutomationStep } from "../EmailAutomationStep";
 
@@ -24,6 +26,7 @@ beforeAll(() => {
   ModuleRegistry.register("EmailAutomationStep", EmailAutomationStepModule(moduleFactory));
   ModuleRegistry.register("EmailAutomationEnrollment", EmailAutomationEnrollmentModule(moduleFactory));
   ModuleRegistry.register("EmailAutomationTrigger", EmailAutomationTriggerModule(moduleFactory));
+  ModuleRegistry.register("EmailAutomationCandidate", EmailAutomationCandidateModule(moduleFactory));
 });
 
 const hydrate = (attributes: Record<string, unknown>) =>
@@ -100,4 +103,71 @@ describe("email automation models", () => {
       data: { type: EMAIL_AUTOMATION_UNSUBSCRIBE_TYPE, attributes: { scope: "all" } },
     });
   });
+
+  it("EmailAutomationCandidate rehydrates kind, id, email, addable and reason", () => {
+    const blocked = new EmailAutomationCandidate().rehydrate(
+      hydrate({
+        recipientType: "waitlist",
+        recipientId: "w1",
+        email: "ada@example.com",
+        addable: false,
+        reason: "no_consent",
+      }),
+    );
+    expect(blocked.recipientType).toBe("waitlist");
+    expect(blocked.recipientId).toBe("w1");
+    expect(blocked.email).toBe("ada@example.com");
+    expect(blocked.name).toBeUndefined();
+    expect(blocked.addable).toBe(false);
+    expect(blocked.reason).toBe("no_consent");
+
+    const open = new EmailAutomationCandidate().rehydrate(
+      hydrate({
+        recipientType: "user",
+        recipientId: "u1",
+        email: "grace@example.com",
+        name: "Grace",
+        addable: true,
+        reason: null,
+      }),
+    );
+    expect(open.recipientType).toBe("user");
+    expect(open.name).toBe("Grace");
+    expect(open.addable).toBe(true);
+    expect(open.reason).toBeUndefined();
+  });
+
+  it("EmailAutomationCandidate createJsonApi returns type and id only", () => {
+    expect(new EmailAutomationCandidate().createJsonApi({ id: "u1" })).toEqual({
+      data: { type: "email-automation-candidates", id: "u1" },
+    });
+  });
+
+  it("EmailAutomationEnrollment.createJsonApi builds type, id, recipientType and recipientId", () => {
+    expect(
+      new EmailAutomationEnrollment().createJsonApi({ id: "e1", recipientType: "user", recipientId: "u1" }),
+    ).toEqual({
+      data: {
+        type: "email-automation-enrollments",
+        id: "e1",
+        attributes: { recipientType: "user", recipientId: "u1" },
+      },
+    });
+  });
+  it('EmailAutomation rehydrates purpose "service"', () => {
+    const m = new EmailAutomation().rehydrate(hydrate({ name: "Welcome", purpose: "service" }));
+    expect(m.purpose).toBe("service");
+  });
+
+  it("missing purpose rehydrates as marketing", () => {
+    expect(new EmailAutomation().rehydrate(hydrate({ name: "Welcome" })).purpose).toBe("marketing");
+    expect(new EmailAutomation().rehydrate(hydrate({ name: "Welcome", purpose: "other" })).purpose).toBe("marketing");
+  });
+
+  it("createJsonApi sends purpose when set", () => {
+    const body = new EmailAutomation().createJsonApi({ id: "a1", name: "Welcome", purpose: "service" });
+    expect(body.data.attributes.purpose).toBe("service");
+    const without = new EmailAutomation().createJsonApi({ id: "a1", name: "Welcome" });
+    expect("purpose" in without.data.attributes).toBe(false);
+  });
 });

package/src/features/email-automation/data/email-automation.fields.ts

@@ -1,5 +1,6 @@
 export enum EmailAutomationFields {
   name = "name",
+  purpose = "purpose",
   trigger = "trigger",
   status = "status",
   steps = "steps",

package/src/features/email-automation/data/index.ts

@@ -9,5 +9,7 @@ export * from "./EmailAutomationEnrollment";
 export * from "./EmailAutomationEnrollmentService";
 export * from "./EmailAutomationTriggerInterface";
 export * from "./EmailAutomationTrigger";
+export * from "./EmailAutomationCandidateInterface";
+export * from "./EmailAutomationCandidate";
 export * from "./email-automation.fields";
 export * from "./email-automation-enrollment.fields";

package/src/features/email-automation/hooks/useEmailAutomationTableStructure.tsx

@@ -62,6 +62,25 @@ export const useEmailAutomationTableStructure: UseTableStructureHook<
       enableSorting: false,
       enableHiding: false,
     }),
+    [EmailAutomationFields.purpose]: () => ({
+      id: "purpose",
+      accessorKey: "purpose",
+      header: t("emailAutomations.list.columns.purpose"),
+      cell: ({ row }: { row: TableContent<EmailAutomationInterface> }) => {
+        const automation: EmailAutomationInterface = row.original.jsonApiData;
+        return automation.purpose === "service" ? (
+          <Badge variant="softBlue" data-testid="email-automation-purpose-badge">
+            {t("emailPurpose.service")}
+          </Badge>
+        ) : (
+          <Badge variant="softGray" data-testid="email-automation-purpose-badge">
+            {t("emailPurpose.marketing")}
+          </Badge>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
     [EmailAutomationFields.trigger]: () => ({
       id: "trigger",
       accessorKey: "trigger",

package/src/features/email-automation/index.ts

@@ -2,4 +2,6 @@ export * from "./EmailAutomationModule";
 export * from "./EmailAutomationStepModule";
 export * from "./EmailAutomationEnrollmentModule";
 export * from "./EmailAutomationTriggerModule";
+export * from "./EmailAutomationCandidateModule";
 export * from "./data";
+export * from "./data/EmailPurpose";

package/src/features/email-blast/EmailBlastModule.ts

@@ -15,6 +15,7 @@ export const EmailBlastModule = (factory: ModuleFactory) =>
         fields: [
           createJsonApiInclusion("email-blasts", [
             "subject",
+            "purpose",
             "status",
             "sentAt",
             "recipientCount",