Send a welcome email after signup with Loops

Install the Loops SDK, emit one signup event, and let a Workflow deliver the welcome email with consent, unsubscribe, testing, and failure handling built into the path.

Developer guides

Who this is for

You want a coding agent to add one welcome email to an existing Node.js or TypeScript signup flow. The app will emit a signup event; a Loops Workflow will own the message, consent checks, unsubscribe handling, and delivery.

Give this to your agent

This prompt is intentionally provider-neutral. It tests whether an agent discovers the right lifecycle path instead of forcing a welcome email through a transactional API.

Install the SDK

npm

The official package is loops. Version 7 supports TypeScript, ESM, and CommonJS and requires Node 18 or later. Create one server-only client; the API key grants account access and must never reach browser code.

// lib/loops.ts — server only
import { LoopsClient } from "loops";

if (!process.env.LOOPS_API_KEY) {
  throw new Error("LOOPS_API_KEY is not set");
}

export const loops = new LoopsClient(process.env.LOOPS_API_KEY);

Set the server-only API key

Generate a key under Settings → API in Loops. Store it in your deployment secrets and local .env file. Never commit it, log it, or expose it through NEXT_PUBLIC_, VITE_, browser code, or a mobile client.

# .env — server only
LOOPS_API_KEY

Send one signup event

Call this only after the user record is committed. sendEvent creates or updates the contact, saves contact properties, and triggers the matching Workflow. Keep one stable idempotency key for the signup across every retry.

import { loops } from "./lib/loops";

type NewUser = {
  id: string;
  email: string;
  firstName?: string | null;
  marketingConsent: boolean;
};

export async function onUserCreated(user: NewUser) {
  return loops.sendEvent({
    email: user.email,
    userId: user.id,
    eventName: "user_signed_up",
    contactProperties: {
      firstName: user.firstName ?? null,
      subscribed: user.marketingConsent,
    },
    eventProperties: { source: "product_signup" },
    headers: { "Idempotency-Key": "signup:" + user.id },
  });
}

Do not hardcode subscribed: true. Map it from your product’s consent decision. The event name is case-sensitive, contactProperties persist on the contact, and eventProperties exist only for this event and the email it triggers.

Configure the Workflow in Loops

The Event received trigger must match user_signed_up exactly. Choose One time so the first signup enters once, add the email immediately after the trigger, send a preview, then Start the Workflow. Dashboard configuration remains a human-reviewed step.

Test the whole path

First trigger [email protected] or [email protected] and confirm the event appears and enters the Workflow without delivering email. Then use a real opted-in inbox, confirm the Workflow send and metrics, retry with the same idempotency key to check duplicate protection, test marketingConsent: false, and run npx tsc --noEmit.

Common failure modes

Wrong package: install loops. Browser calls: keep LOOPS_API_KEY server-side. Event mismatch: user_signed_up is case-sensitive. Inactive Workflow: previews work, but real events wait until you click Start. No consent: an unsubscribed contact will not receive Workflow email. Suppression or unverified domain: Loops blocks the send. Duplicate events: reuse the same Idempotency-Key on retries.

Consent and email category

A welcome or onboarding email is marketing in Loops, even when signup triggers it. Send it through a Workflow so unsubscribe and suppression state are honored. Reserve transactional email for action-completing messages such as account verification, password resets, receipts, and security alerts.