Send email and notifications

email:
  driver: local                          # in development; production uses resend or ses
  from: "Pinecart <hello@pinecart.dev>"
  unsubscribe-url: https://app.pinecart.dev/unsubscribe
  templates:
    receipt:
      subject: "Receipt {{orderId}}"
      text: "Thanks for order {{orderId}}."
    newsletter:
      subject: "Pinecart news, issue {{issue}}"
      text: "Issue {{issue}} is out."
    shipped:
      subject: "Order {{orderId}} shipped"
      text: "Order {{orderId}} is on its way."
network:
  allow: [app.pinecart.dev]              # mainsdk check reads the URL above as a host

import { email } from "mainsdk";

export async function sendReceipt(to: string, orderId: string) {
  return email.send({
    to,
    template: "receipt",
    data: { orderId },
    idempotencyKey: `receipt:${orderId}`,
  });
}

import { email } from "mainsdk";

export async function sendIssue(to: string, issue: number) {
  return email.marketing({
    to,
    template: "newsletter",
    data: { issue },
    unsubscribe: await email.unsubscribe.create(to),
    idempotencyKey: `newsletter:${issue}:${to}`,
  });
}

import { email } from "mainsdk";

export const GET = (req: Request) => email.unsubscribe.handle(req);
export const POST = (req: Request) => email.unsubscribe.handle(req);

notify:
  channels: [whatsapp, sms, email]
  whatsapp: local
  sms: local
  quiet: { from: "22:00", to: "08:00", tz: Asia/Kolkata }
  templates:
    order.shipped:
      whatsapp: { name: order_shipped, language: en, params: [orderId] }
      sms: { text: "Pinecart: order {{orderId}} shipped", dlt-template-id: "1007000000000001" }
      email: shipped

import { notify } from "mainsdk";

type Customer = { id: string; email: string; phone: string };

export async function agreeToWhatsApp(customer: Customer) {
  await notify.contact.update(customer.id, { phone: customer.phone, email: customer.email });
  return notify.consent.create(customer.id, "whatsapp", { source: "checkout-form" });
}

export async function orderShipped(customer: Customer, orderId: string) {
  return notify(customer, {
    template: "order.shipped",
    data: { orderId },
    category: "orders",
    idempotencyKey: `order.shipped:${orderId}`,
  });
}

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { email, notify } from "mainsdk";
import { channels, createTestApp, mailbox } from "@mainsdk/testing";

// The functions from the steps above.
declare function sendReceipt(to: string, orderId: string): Promise<unknown>;
declare function sendIssue(to: string, issue: number): Promise<{ status: string }>;
declare function orderShipped(
  customer: { id: string; email: string; phone: string },
  orderId: string,
): Promise<{ channel: string; skipped: { code: string }[] }>;

const yaml = [
  "schema: 1",
  "project: pinecart",
  "email:",
  "  from: 'Pinecart <hello@pinecart.dev>'",
  "  unsubscribe-url: https://app.pinecart.dev/unsubscribe",
  "  templates:",
  "    receipt: { subject: 'Receipt {{orderId}}', text: 'Thanks.' }",
  "    newsletter: { subject: 'News {{issue}}', text: 'Issue {{issue}}.' }",
  "    shipped: { subject: 'Shipped {{orderId}}', text: 'On its way.' }",
  "notify:",
  "  channels: [whatsapp, email]",
  "  whatsapp: local",
  "  templates:",
  "    order.shipped:",
  "      whatsapp: { name: order_shipped, language: en, params: [orderId] }",
  "      email: shipped",
].join("\n");

const jane = { id: "u1", email: "jane@example.com", phone: "+919876543210" };

describe("messaging", () => {
  it("email-notify AC8 sends a receipt once", async () => {
    const app = createTestApp({ yaml });
    await sendReceipt(jane.email, "A1");
    await sendReceipt(jane.email, "A1");
    mailbox(app).toHaveSent({ template: "receipt", times: 1 });
  });

  it("email-notify AC1 sends a newsletter with the one-click headers", async () => {
    const app = createTestApp({ yaml });
    await sendIssue(jane.email, 7);
    const headers = mailbox(app).last(jane.email)?.headers;
    assert.equal(headers?.["List-Unsubscribe-Post"], "List-Unsubscribe=One-Click");
  });

  it("email-notify AC3 does not send marketing to an address that unsubscribed", async () => {
    const app = createTestApp({ yaml });
    await email.suppression.create(jane.email, { reason: "unsubscribe" });
    const result = await sendIssue(jane.email, 8);
    assert.equal(result.status, "suppressed");
    mailbox(app).toHaveSent({ template: "newsletter", times: 0 });
  });

  it("email-notify AC2 uses WhatsApp only after consent", async () => {
    const app = createTestApp({ yaml });
    const first = await orderShipped(jane, "A2");
    assert.equal(first.channel, "email");
    assert.equal(first.skipped[0]?.code, "MAIN-NOTIFY-0004");

    await notify.consent.create(jane, "whatsapp", { source: "test" });
    const second = await orderShipped(jane, "A3");
    assert.equal(second.channel, "whatsapp");
    assert.deepEqual(channels(app).whatsapp?.last()?.params, { orderId: "A3" });
  });
});

email:
  driver: resend
  key: secret:RESEND_API_KEY
  webhook: resend-events
notify:
  whatsapp: whatsapp-cloud
  sms: msg91
  whatsapp-cloud: { phone-number-id: "1234567890", token: secret:WHATSAPP_TOKEN }
  msg91: { key: secret:MSG91_AUTH_KEY }
webhooks:
  inbound:
    resend-events:
      preset: standard
      secret: secret:RESEND_WEBHOOK_SECRET
      path: /api/webhooks/resend

npx mainsdk check
npx mainsdk check --env prod
npx mainsdk info --json

Goal: send email and notifications from this app.
Read: docs/specs/email-notify.md, this page, main.yaml.
Touch only: main.yaml, main.env.prod.yaml, the files that send messages, their tests.
Do: use email.send and notify with templates declared in main.yaml; never build a mailer or call a provider directly.
Pass an idempotencyKey on every send. Pass unsubscribe: await email.unsubscribe.create(address) to email.marketing.
Record notify.consent.create before any SMS or WhatsApp. Leave tracking off. Use local drivers in development only.
Verify: npx mainsdk check --json --agent, then the tests.
Never hard-code a provider key, and never send marketing without an unsubscribe link.