Environment Variables

Owlat uses environment variables to configure payments, email sending, authentication, and feature flags. Backend variables are set via the Convex dashboard; frontend variables live in .env files.

Where to Set Variables

Convex backend (all process.env references in apps/api/):

npx convex env set VAR_NAME value

Or set them in the Convex dashboard under your deployment's Settings > Environment Variables.

Nuxt frontend (apps/web/.env):

NUXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NUXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
NUXT_PUBLIC_SITE_URL=http://localhost:3000

Payments (Stripe)

Prerequisites

• A Stripe account
• Four subscription products with monthly prices (one per plan tier)
• Optionally, a metered price and billing meter for per-email charges

Required Variables

Set these in the Convex dashboard:

Optional (Metered Email Billing)

Setup Steps

1. Create a Stripe account at stripe.com and note your secret key from the API Keys page.
2. Create a single product in Stripe with graduated tiered pricing for contacts. Copy the Price ID (starts with price_).
3. (Optional) Create a metered price for per-email billing:
   • Create a product for email usage
   • Add a metered price (e.g., €0.25 per 1,000 emails)
   • Create a Billing Meter in Stripe and copy the Meter ID
4. Set the environment variables in the Convex dashboard:

   npx convex env set BILLING_ENABLED true
   npx convex env set STRIPE_SECRET_KEY sk_live_...
   npx convex env set STRIPE_WEBHOOK_SECRET whsec_...
   npx convex env set STRIPE_PRICE_CONTACT_TIERED price_...
   

Contact Tiers (Graduated Pricing)

Email sending is billed at €0.25 per 1,000 emails when metered billing is configured.

Email Sending

Provider Selection

Owlat supports two email providers: AWS SES (default) and Resend. Set the EMAIL_PROVIDER variable in the Convex dashboard:

npx convex env set EMAIL_PROVIDER ses    # default
npx convex env set EMAIL_PROVIDER resend

AWS SES

Setup Steps

1. Create an IAM user in AWS with programmatic access and the AmazonSESFullAccess policy (or a scoped policy allowing ses:SendEmail and ses:SendRawEmail).
2. Verify your sending domain in the SES console. SES requires domain verification before you can send emails.
3. Request production access if your SES account is in sandbox mode. Sandbox mode limits sending to verified addresses only.
4. Set the environment variables:

   npx convex env set EMAIL_PROVIDER ses
   npx convex env set AWS_SES_REGION eu-west-1
   npx convex env set AWS_SES_ACCESS_KEY_ID AKIA...
   npx convex env set AWS_SES_SECRET_ACCESS_KEY ...
   

Resend

Setup Steps

1. Create a Resend account at resend.com and add your sending domain.
2. Generate an API key from the Resend dashboard.
3. (Optional) Set up webhooks for delivery tracking:
   • In Resend, create a webhook pointing to your Convex site URL's webhook endpoint
   • Copy the webhook signing secret
4. Set the environment variables:

   npx convex env set EMAIL_PROVIDER resend
   npx convex env set RESEND_API_KEY re_...
   npx convex env set RESEND_WEBHOOK_SECRET whsec_...
   

Common Email Configuration

These variables apply regardless of which provider you use:

Waitlist

The waitlist gates new signups behind admin approval. When enabled, new users land on a waiting screen until an admin approves them.

Variables

Convex dashboard:

Nuxt frontend (apps/web/.env):

Setup Steps

1. Enable the waitlist on both sides:

   # Convex
   npx convex env set WAITLIST_ENABLED true
   
   # apps/web/.env
   NUXT_PUBLIC_WAITLIST_ENABLED=true
   

2. Optionally, auto-approve specific emails (e.g., your team):

   npx convex env set WAITLIST_AUTO_APPROVE_EMAILS "admin@example.com,dev@example.com"
   

Analytics (PostHog)

Owlat integrates with PostHog for product analytics and error tracking. The integration is optional — everything works without it.

Variables

Convex dashboard:

Nuxt frontend (apps/web/.env):

Setup Steps

1. Create a PostHog project at posthog.com and copy the project API key.
2. Add the organization group type in PostHog: go to Settings → Groups → add a group type called organization. This enables organization-level analytics.
3. Set the environment variables:

   # Convex (server-side events)
   npx convex env set POSTHOG_API_KEY phc_...
   npx convex env set POSTHOG_HOST https://eu.i.posthog.com
   
   # apps/web/.env (client-side events)
   NUXT_PUBLIC_POSTHOG_API_KEY=phc_...
   NUXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
   

Tracked Events

Client-side (automatic):

• $pageview — SPA page navigations
• $pageleave — page leave events
• $exception — Vue errors and unhandled promise rejections
• User identification and organization group association

Server-side (fire-and-forget from mutations):

• campaign_created, campaign_sent
• contact_created
• automation_created, automation_activated, automation_paused
• mailing_list_created

All server events include organizationId as a property and PostHog group.

Translations (AI)

Owlat supports AI-powered email template translations. OpenRouter is the primary provider; OpenAI is used as a fallback if OpenRouter is not configured.

Set in the Convex dashboard:

npx convex env set OPENROUTER_API_KEY sk-or-...
# or, as fallback:
npx convex env set OPENAI_API_KEY sk-...

Authentication

Set BETTER_AUTH_SECRET in the Convex dashboard. Use a long, random string:

npx convex env set BETTER_AUTH_SECRET $(openssl rand -base64 32)

Nuxt Frontend

These go in apps/web/.env:

Complete Reference

All environment variables in one table: