Best Practices

Source tracking

Use the source field to distinguish where signups originate. This powers the Sources analytics breakdown and helps you measure channel performance.

await wk.subscribers.create({
  email: "user@example.com",
  source: "product-hunt-launch",
});

Common source values: landing-page, signup-form, referral, product-hunt, twitter, docs, partner-page.

Metadata

Use metadata to attach structured data to a subscriber without changing the schema.

await wk.subscribers.create({
  email: "user@example.com",
  metadata: {
    plan: "pro",
    referralCode: "FRIEND10",
    signedUpAt: "2025-06-11T12:00:00Z",
  },
});

Keep metadata JSON-serializable and under 10 KB per entry.

Duplicate handling

Each email can only be registered once per project. Attempting to sign up the same email again returns a 409 Conflict. This is intentional — the waitlist tracks unique interest.

To update an existing subscriber's name or metadata, use the management API's update entry endpoint from the dashboard.

Security

• Store API keys in environment variables, never in client-side code or version control
• Rotate keys periodically from the API Keys dashboard page
• Use separate API keys for development and production environments
• If a key is compromised, delete it immediately and generate a new one