@funnelsgrove/emails

Server-side client for the FunnelsGrove Integration API. Email delivery, template authoring, and lifecycle sequences all live under /integration/v1/email; none of these endpoints are part of the funnel SDK contract.

import { createEmailsClient } from '@funnelsgrove/emails';

const emails = createEmailsClient({
  privateToken: process.env.FUNNELSGROVE_PRIVATE_TOKEN!,
});

const receipt = await emails.send({
  template: 'login-code',
  to: '[email protected]',
  variables: { code: '481953', expiresInMinutes: 10 },
  from: { email: '[email protected]', name: 'Example Security' },
  replyTo: '[email protected]',
});

console.log(receipt.id);

Transactional sends may copy up to ten recipients and attach one PDF up to 5 MiB:

import { readFile } from 'node:fs/promises';

await emails.send({
  template: 'manual-invoice',
  to: '[email protected]',
  cc: ['[email protected]'],
  variables: { invoiceNumber: 'MV0002' },
  attachments: [{
    filename: 'MV0002.pdf',
    contentType: 'application/pdf',
    content: await readFile('MV0002.pdf'),
  }],
});

The project secret token is sent as Authorization: Bearer <token> and is never intended for browser code. The template must be published in the project first. Project email content can also be managed through the existing fgrove email CLI. The optional from.email must use a verified sending domain in the same project. replyTo accepts one email address. Arbitrary transport headers are not exposed.

Create and publish a template from Node.js or the CLI:

await emails.createTemplate({
  slug: 'order-confirmation',
  name: 'Order confirmation',
  draft: {
    subject: 'Order {{ORDER_ID}}',
    previewText: null,
    html: '<p>Order {{ORDER_ID}}</p>',
    text: 'Order {{ORDER_ID}}',
    variables: { ORDER_ID: 'string' },
  },
});

fgrove email pull --workspace "$WORKSPACE" --project "$PROJECT"
fgrove email validate --dir .
fgrove email push --workspace "$WORKSPACE" --project "$PROJECT"
fgrove email template publish order-confirmation --workspace "$WORKSPACE" --project "$PROJECT"

Production sequence steps currently use published templates. Delays stay simple: hours or days. An empty funnelIds list applies to all funnels. Direct-copy authoring exists in the client contract, but lifecycle delivery cannot persist it yet, so do not publish direct-copy steps.

const sequence = await emails.createSequence({
  slug: 'lead-follow-up',
  name: 'Lead follow-up',
  draft: {
    triggerEventType: 'email_captured',
    funnelIds: [],
    steps: [{
      key: 'welcome',
      mode: 'template',
      template: 'welcome',
      variables: { firstName: 'first_name' },
      personalizationEnabled: true,
      delay: { value: 1, unit: 'hours' },
    }],
  },
});

await emails.addSequenceStep(sequence.id, {
  key: 'reminder',
  mode: 'template',
  template: 'reminder',
  variables: { firstName: 'first_name' },
  delay: { value: 2, unit: 'days' },
});

await emails.publishSequence(sequence.id);
await emails.enableSequence(sequence.id);

// Stops new enrollments and blocks queued steps at their pre-send check.
await emails.disableSequence(sequence.id);

With personalization enabled, FunnelsGrove emits an email.personalization_requested project webhook 20 minutes before delivery. Patch only the variables that need fresh data; the pinned template is validated and rendered again before it sends:

await emails.updateVariables(event.data.deliveryId, {
  firstName: customer.firstName,
  recommendation: customer.recommendation,
});

fgrove email update-variables "$DELIVERY_ID" \
  --variables '{"firstName":"Ada"}'

Sequence editing uses the same project CLI with fgrove email sequence add-step and local JSON files:

fgrove email sequence add-step lead-follow-up \
  --workspace "$WORKSPACE" \
  --project "$PROJECT" \
  --key reminder \
  --subject "A quick reminder" \
  --body "Come back when you are ready." \
  --delay-days 2

Cancel a user's active enrollment idempotently. A retry returns cancelled: 0 after the enrollment is already terminal:

await emails.cancelSequenceEnrollment(sequence.id, {
  funnelEndUserId: '00000000-0000-4000-8000-000000000000',
  reason: 'customer_request',
});

fgrove email sequence cancel lead-follow-up \
  --user-id 00000000-0000-4000-8000-000000000000