MailerLite Integration

Knowledge > Integrations > MailerLite

What it is / why we use it

MailerLite is the email marketing platform for all ChurchWiseAI properties. As of April 2026, MailerLite handles lead nurture only — newsletter signups, guide downloaders, PewSearch claimants, and cross-property leads. Paying customers (premium_churches) are handled entirely by the code-based Lifecycle Email System (churchwiseai-web/src/lib/lifecycle-emails.ts + Resend + Vercel cron).

MailerLite's current role (leads only):

Newsletter subscriber management (signup forms, groups, segmentation)
Lead nurture sequences for non-customers (newsletter welcome, cross-property cross-promo)
Congregation Care broadcasts (via the CareTab in PewSearch admin dashboard)
Manual campaigns (one-off announcements sent from MailerLite UI)

NOT handled by MailerLite (moved to code system):

Customer onboarding sequences
Win-back sequences for cancelled churches
CWA → ShareWise cross-promo (sent via Resend cron at day 7)

All three codebases (churchwiseai-web, pewsearch, sermon-illustrations) share a single MailerLite account. Only churchwiseai-web holds the live API key; PewSearch and ITW proxy through a CWA endpoint so the key never spreads across repos. All calls are fire-and-forget — MailerLite is treated as downstream of Supabase, so API failures never break user-facing flows.

Account Info

Platform: MailerLite (connect.mailerlite.com)
Account owner: churchwiseai@gmail.com (same Google account as Stripe)
API key location: MAILERLITE_API_KEY env var in churchwiseai-web only
Agent access: Agents have full REST API access. Never send the founder to the MailerLite dashboard; call the API directly.

How Used Per Product

Product	Purpose
ChurchWiseAI	Subscriber sync on trial start, checkout completion, cancellation; newsletter signups; demo booking confirmation
SermonWise	Users synced to `sermonwise-users` group; Pro subscribers to `sermonwise-pro`
ShareWiseAI	Coming Soon signups synced to `sharewise-users`; paid subscribers to `sharewise-paid`
PewSearch	Premium page subscribers synced via proxy; claims/leads captured to `pewsearch-claims`
IllustrateTheWord	Newsletter subscribers synced via proxy to `itw-subscribers`; paid to `itw-premium`
Cross-property	`ministry-digest` group covers subscribers who opted into the shared pastoral newsletter

Subscriber Lifecycle — When Subscribers Are Synced

Subscribers are added or updated at these trigger points:

Onboard form submission (/api/onboard) — user added to cwa-trial group with subscription_status: active and source_property: churchwiseai
Stripe checkout.session.completed — user moved to cwa-customers group with plan and channel fields set
Stripe subscription cancelled — user moved to cwa-cancelled group
Newsletter/signup forms — all three properties POST to the proxy or the CWA /api/mailerlite/subscribe endpoint with a tag field that maps to a group ID
PewSearch lead capture (/api/leads/capture) — fire-and-forget proxy call to CWA
ITW newsletter (/api/newsletter) — same proxy pattern

Key Groups (from `mailerlite-groups.ts`)

Groups are populated at setup time via /api/mailerlite/setup. Names follow the kebab-case pattern property-segment:

cwa-newsletter, cwa-customers, cwa-trial, cwa-demo-booked, cwa-starter-kit, cwa-cancelled
sermonwise-users, sermonwise-pro
sharewise-users, sharewise-paid
pewsearch-premium, pewsearch-claims
itw-subscribers, itw-premium
ministry-digest

Custom Subscriber Fields

The following custom fields are created in MailerLite (all text type):

church_name, church_id, plan, channel, subscription_status, source_property, denomination, city, state, signup_date, products_used

Key Environment Variables

Variable	Used In	Purpose
`MAILERLITE_API_KEY`	churchwiseai-web	Bearer token for all direct API calls
`MAILERLITE_PROXY_SECRET`	All three codebases	Shared secret verifying proxy requests (`x-ml-proxy-key` header)
`MAILERLITE_PROXY_URL`	pewsearch, ITW	Full URL to CWA's `/api/mailerlite/subscribe` endpoint
`MAILERLITE_WEBHOOK_SECRET`	churchwiseai-web	HMAC-SHA256 secret for verifying inbound MailerLite webhook events

CLI / API Patterns & Gotchas

Proxy endpoint auth: PewSearch and ITW POST to MAILERLITE_PROXY_URL with:

x-ml-proxy-key: <MAILERLITE_PROXY_SECRET>
Content-Type: application/json

{ "email": "...", "name": "...", "source": "pewsearch", "tag": "church_recommendations" }

The proxy maps tag to a group ID via tagToGroup() in mailerlite-groups.ts. If the tag has no mapping, the subscriber syncs without group assignment (not an error).

Upsert semantics: POST /subscribers on the MailerLite API is a true upsert — safe to call on every checkout or signup. No need to check whether a subscriber already exists.

Group IDs are hardcoded constants: Group IDs live in mailerlite-groups.ts as ML_GROUPS. They were populated once by the setup endpoint. If you need to add a new group, run POST /api/mailerlite/setup after adding the definition to ML_GROUP_DEFINITIONS, then commit the new ID to mailerlite-groups.ts.

Rate limit on proxy: The subscribe proxy enforces 5 requests per minute per IP via rate-limit.ts. This is intentional to prevent abuse; batch imports should be done via direct API or MailerLite dashboard import.

Dev mode / missing key: If MAILERLITE_API_KEY is not set, all functions in mailerlite.ts silently return without calling the API. This enables local development without a key. No error is thrown.

API base URL: https://connect.mailerlite.com/api (not the older api.mailerlite.com)

Failure Modes & Recovery

Failure	Behavior	Recovery
`MAILERLITE_API_KEY` not set	Silent no-op in all mailerlite.ts functions	Set the env var; subscribers already in Supabase, re-sync when needed
`MAILERLITE_PROXY_SECRET` mismatch	Proxy returns 401 to PewSearch/ITW	Verify secret matches across all three .env files
Webhook signature invalid	Webhook returns 401; bounce/unsub event not processed	Check `MAILERLITE_WEBHOOK_SECRET` matches the MailerLite webhook config
Group ID missing/wrong	Subscriber synced without group assignment	Rerun `/api/mailerlite/setup` to recreate groups; update `ML_GROUPS` constants
MailerLite API 429 / outage	Console error logged; user flow unaffected (fire-and-forget)	Retry manually via API or dashboard bulk import from Supabase export
`email_subscribers` table out of sync	Bounce/unsub events not reflected	Re-trigger webhook delivery from MailerLite dashboard

Webhook events handled:

subscriber.bounced → updates email_subscribers.status = 'bounced'
subscriber.unsubscribed → updates email_subscribers.status = 'unsubscribed'

Cost Model / Usage Limits

Free tier: Up to 1,000 subscribers and 12,000 emails/month
Paid tiers: Scale by subscriber count; expect to upgrade when total subscribers across all groups exceeds 1,000
Automations: Available on paid plans. As of March 2026 no paid automations are active; groups are used for segmentation and manual campaign targeting.
API rate limits: MailerLite enforces per-minute limits (undocumented but observed around 60 req/min). The proxy's 5 req/min IP limit is well within this.

MailerLite Automations — Status (April 2026)

9 automations exist. 5 are disabled. The split: MailerLite handles leads (non-customers), the Lifecycle Email System handles customers (premium_churches).

#	Automation	Status	Trigger Group	Notes
1	CWA Newsletter Welcome Sequence	✅ ACTIVE	`cwa-newsletter`	Primary lead nurture. Keep. Newsletter signups + guide downloads. 54% open rate.
2	Cross-Promo: PewSearch → CWA	✅ ACTIVE	`pewsearch-claims`	PewSearch claimants → CWA. Keep.
3	Cross-Promo: ITW → SermonWise	✅ ACTIVE	`itw-subscribers`	ITW leads → SermonWise. Keep. 0 sends so far.
4	Cross-Promo: SermonWise → ITW	✅ ACTIVE	`sermonwise-users`	SermonWise leads → ITW. Keep. 0 sends so far.
5	Cross-Promo: CWA → ShareWise	⚠️ ACTIVE — CONFLICT	`cwa-customers`	5 in queue. Lifecycle cron also sends `crosspromo_cwa_share`. DISABLE before launch.
6	Win-Back: Cancelled Customers	⚠️ ACTIVE — CONFLICT	`cwa-cancelled`	0 sends. Lifecycle cron also sends winback. DISABLE before launch.
7	7-Day AI Ministry Course	❌ DISABLED (Apr 2026)	`cwa-newsletter`	Incomplete, double-fired with Newsletter Welcome. Content in `lifecycle-emails.ts` as `course_day1-7` (not yet wired to cron).
8	CWA Starter Kit Buyer Nurture	❌ DISABLED (Apr 2026)	`cwa-starter-kit`	December-launch content, 0 sends ever. Needs rewrite before re-enabling.
9	CWA Trial Nurture	❌ DISABLED	`cwa-trial`	Disabled. Trial churches covered by lifecycle cron onboarding sequence.

Two pending actions before launch:

Disable automation #5 (CWA → ShareWise) — conflicts with lifecycle cron
Disable automation #6 (Win-Back) — conflicts with lifecycle cron

Lifecycle Email System — Relationship to MailerLite

The lifecycle system (churchwiseai-web/src/lib/lifecycle-emails.ts) sends all timed/triggered emails via Resend (not MailerLite). MailerLite remains the subscriber CRM — subscriber data flows TO MailerLite for segmentation, but emails flow FROM Resend. Architecture doc: knowledge/architecture/lifecycle-email-system.md.

What MailerLite still does:

Stores subscriber groups for segmentation (agents and campaigns reference these groups)
Receives subscriber sync events (checkout, cancellation, signup) for CRM purposes
Handles Care broadcasts (sent via MailerLite's campaign API from the CareTab)
Manages unsubscribe/bounce events (webhook → Supabase email_subscribers)

What MailerLite no longer does (moved to lifecycle cron + Resend):

Customer onboarding emails (premium_churches — handled by lifecycle cron)
Win-back emails for cancelled customers (handled by lifecycle cron)
CWA → ShareWise cross-promo for paying customers (handled by lifecycle cron at day 7)
Trial nurture (disabled — lifecycle cron onboarding covers trial churches)

All properties must collect explicit marketing consent before syncing subscribers to MailerLite.

Implementation Pattern

The CWA onboard form (churchwiseai-web/src/app/onboard/components/OnboardForm.tsx) is the reference implementation:

CAN-SPAM countries (US, CA): checkbox pre-checked by default
GDPR countries (all others): checkbox unchecked, requires explicit opt-in
Country detection: Timezone-based (Intl.DateTimeFormat().resolvedOptions().timeZone)
Storage: premium_churches.marketing_opt_in column (boolean)
Gate: MailerLite sync only fires when marketing_opt_in is true

Per-Property Compliance Status

Property	Form	Opt-In Checkbox	GDPR Logic	MailerLite Gate
ChurchWiseAI Onboard	`/onboard`	Yes	Yes (timezone)	Yes (`marketing_opt_in`)
PewSearch Claim (paid)	`/claim/[slug]` → `ClaimForm.tsx`	Yes	Yes (timezone)	Yes (stored in `premium_churches`)
PewSearch Free Claim	`PastorLeadCapture.tsx` → `/api/leads/capture`	Yes	Yes (timezone)	Yes (`marketing_opt_in !== false`)
PewSearch Newsletter	`EmailCapture.tsx` → `/api/subscribe`	Implicit (subscribe = consent)	No	No gate (implicit consent)
ITW Signup	`/signup`	Yes (newsletter checkbox)	No GDPR logic	Conditional on checkbox
ITW Footer Newsletter	`FooterNewsletter` → `/api/newsletter`	Implicit	No	No gate

Rules for Agents

NEVER sync to MailerLite without checking opt-in status for claim/signup flows
Newsletter signups are implicit consent (subscribing IS the consent action) — no additional gate needed
When adding new signup forms, always include the marketing opt-in checkbox with timezone-based GDPR default
Transactional emails (welcome, payment failed, trial ending) do NOT require marketing consent — they go through Resend directly

What it is / why we use it​

Account Info​

How Used Per Product​

Subscriber Lifecycle — When Subscribers Are Synced​

Key Groups (from mailerlite-groups.ts)​

Custom Subscriber Fields​

Key Environment Variables​

CLI / API Patterns & Gotchas​

Failure Modes & Recovery​

Cost Model / Usage Limits​

MailerLite Automations — Status (April 2026)​

Lifecycle Email System — Relationship to MailerLite​

Marketing Opt-In Compliance (CAN-SPAM / GDPR)​

Implementation Pattern​

Per-Property Compliance Status​

Rules for Agents​

See Also​