Acquira CRM Internal Documentation

Executive Summary

Use this as the quick operating context before working in campaigns, inbox, contacts, or health checks.

#	Name	Description
1	CRM purpose	Acquira CRM is the workspace for contacts, pipeline, 1:1 email, 1:1 SMS, calls, inbox, and campaigns.
2	Current readiness	Production is usable with monitored caveats around duplicate cleanup, manual-review duplicate groups, GitHub Actions billing/spending-limit recovery, advanced nested segment groups, and database governance follow-ups.
3	Campaign model	Email campaigns use Resend. SMS campaigns use Twilio Marketing Messaging Service. Gmail remains for 1:1 email and inbox history.
4	Main guardrail	Do not bypass consent, unsubscribe, suppression, STOP/START, approval, scheduler lock, or manual pause rules.
5	Documentation rule	This internal operations guide is the operator-facing source. Health checks are audit history and escalation detail.

Workflow

The CRM flow from intake through outreach, campaign tracking, and reporting.

#	Name	Description
1	Lead intake	Airtable remains the upstream intake and source-metadata surface for new contact records.
2	CRM sync	Airtable contacts sync into CRM through webhook and scheduled fallback sync. CRM-created contacts can mirror back with CRM Contact ID.
3	Contact work	Operators use Contacts for search, grouped filters, location, owner, pipeline context, tasks, activity, email/SMS opt-in state, duplicates, merged-record indicators, and campaign history.
4	Pipeline movement	Completed outbound email, SMS, or call activity can mark the related opportunity as Contacted.
5	1:1 email	Gmail sends 1:1 email and logs outbound activity on the contact. Gmail inbox sync links shared-mailbox history to contacts.
6	1:1 SMS	Twilio sends 1:1 SMS when the contact has a valid phone and active SMS opt-in. 1:1 SMS does not force STOP copy.
7	Email campaigns	Resend sends campaign email and tracks delivery, open, click, bounce, suppression, and unsubscribe events.
8	SMS campaigns	Twilio Marketing Messaging Service sends, pauses, resumes, and tracks SMS campaigns.
9	Inbound SMS compliance	STOP/START/HELP style replies are logged, update SMS opt-in state, and mirror linked consent changes back to Airtable.
10	Calls	Twilio Voice powers browser calling, inbound routing, final call status logging, caller ID selection, and recording callbacks.
11	Call recordings	Recorded calls move from Twilio to Google Shared Drive, then Gemini creates transcript and summary output linked back to CRM activity.
12	Reporting	Dashboard and health views rely on stored snapshots, provider events, sync logs, and campaign recipient rows.

Integration and Automation Inventory

The active systems and scheduled automations that keep the CRM running.

#	Name	Description
1	Next.js on Vercel	Hosts the CRM app, API routes, campaign scheduler endpoint, sync endpoints, and health routes.
2	Supabase Postgres	Stores contacts, opportunities, activities, campaigns, campaign recipients, provider events, users, tasks, preferences, templates, and sync logs.
3	Google OAuth and Gmail API	Authenticates users, powers shared inbox sync, contact email history, and 1:1 email sending.
4	Google Pub/Sub	Delivers Gmail push notifications to the CRM webhook when Gmail watches are active.
5	Google Shared Drive and Gemini	Stores retained call recordings and generates transcript and summary output.
6	Airtable	Upstream source for contact intake, source fields, initial consent state, webhook events, and fallback sync reconciliation.
7	Resend	Sends campaign email and posts provider events into CRM.
8	Twilio SMS and Voice	Sends 1:1 and campaign SMS, receives inbound replies, handles delivery callbacks, browser dialing, inbound calls, and recordings.
9	Campaign scheduler	GitHub Actions starts every 5 minutes and calls the campaign cron route once per minute during the runner window.
10	Gmail watch renewal	GitHub and Vercel cron routes call the watch renewal route. Manual renewal on 2026-05-22 confirmed all 5 connected users active, including buyers@acquira.com.
11	Call recording processor	GitHub Actions calls the recording processor every 5 minutes.
12	CI	GitHub Actions runs Prisma validate, lint, typecheck, and build on pushes and PRs.
13	Hosted documentation	Cloudflare Pages hosts the redacted, task-first interactive docs for teammate use.

SMS Campaign Guidelines

Rules for safe Twilio campaign use.

#	Name	Description
1	Use opted-in contacts only	SMS campaigns should only target contacts with phone numbers and active SMS opt-in.
2	Keep campaign STOP language	Campaign SMS must include Acquira identity and STOP opt-out language. The CRM appends it when missing.
3	Use Marketing route	SMS campaigns should stay inside the approved Twilio Marketing Messaging Service.
4	Respect hard caps	Campaigns are governed by hard caps and readiness checks instead of approval. Email defaults: 1,000 recipients per campaign, 2,000 recipients per day, 2 campaign starts per day. SMS defaults: 500 recipients per campaign, 500 recipients per day, 2 campaign starts per day.
5	Expect batch pacing	CRM processes SMS campaign sends in controlled batches, currently up to 500 recipients per CRM pass by default.
6	Review paused campaigns	Do not resume a paused SMS campaign until failure reasons, opt-outs, pending recipients, and recipient quality have been reviewed.
7	Monitor delivery health	Campaigns only pause when an operator pauses them. Operators should still review failures, opt-outs, pending recipients, and Twilio status during larger sends.
8	Clean duplicates first	Review duplicate phone groups before larger SMS sends. Campaign recipient add already skips repeat phone numbers within the same SMS campaign, but cleanup keeps reporting and contact history clearer.
9	Do not use cold non-consented lists	The CRM must not be used to bypass Twilio A2P and consent rules.

Email Campaign Guidelines

Rules for safe Resend campaign use.

#	Name	Description
1	Use Resend for broad campaigns	Campaign and bulk email should use Resend when sender reputation is healthy. Gmail remains available for 1:1 email, inbox history, and paced personal-sender fallback campaigns.
2	Use verified senders	Use verified @acquira.com sender fields configured for Resend.
3	Keep unsubscribe footer	Do not remove or bypass the CRM unsubscribe footer for campaign email.
4	Respect suppression	Bounced, suppressed, complained, and unsubscribed contacts should remain excluded.
5	Use test sends	Send a test before production sends, especially when using HTML.
6	Treat opens carefully	Open rate is directional because privacy tools and image blocking can inflate or hide opens.
7	Use delivered as denominator	Open rate, click rate, and unsubscribe rate should use delivered recipients as the denominator.
8	Rich email editing and images are supported	The CRM stores campaign bodies as email-ready HTML, but operators use a normal rich editor for writing, line breaks, bold, italic, underline, links, headings, and left/center/right alignment. Hosted HTTPS image URLs are supported. Storage-backed upload, drag/drop, and paste are available when BLOB_READ_WRITE_TOKEN is configured.
9	Segment conservatively	Website leads with an email address are treated as subscribed unless they unsubscribe, complain, bounce into suppression, or are manually suppressed. Segment broad marketing carefully to protect sender reputation.
10	Treat Resend limits as account-wide	Resend quotas and rate limits are shared by the Resend team/account, not multiplied per CRM user or sender.
11	Use Transactional capacity for CRM sends	CRM campaigns send through Resend Email API, not Broadcasts. Resend dashboard verified Transactional Pro at 229 / 50,000 monthly emails used, daily limit Unlimited, and 5 req/s team rate limit on 2026-05-19.
12	Remember CRM pacing	CRM email campaigns are hard-capped at 1,000 recipients per campaign and process with Resend batch sending in chunks of 100 emails per API call. Gmail fallback campaigns default to 25 recipients per scheduler pass and 500 recipients per sender per Eastern day. Once a Gmail fallback campaign starts or sends, the campaign detail page shows sender, sent-today, remaining-today, and batch-pace counts. SMS campaigns are hard-capped at 500 recipients per campaign by default.
13	Review the campaign detail page	Email campaign detail pages are organized around Campaign Readiness, Test Send, Campaign Health, Clicked Links, Geography, and Recipients. Sender Health is reviewed from the Email Campaigns tab because it applies across campaigns.
14	Use reusable image assets	Upload, paste, or save hosted image URLs from the email editor. Uploaded images are saved as reusable Image assets and inserted as centered HTML image blocks by default.
15	Use open/read trends as scheduling guidance	The Email Campaigns tab includes Open/Read Trends based on campaign recipient send time and open/click data in Eastern time. Treat this as scheduling guidance, not a perfect read receipt, because email clients can block or proxy open tracking.
16	Add audiences from Contacts when needed	For reusable targeting, save filters in Contacts, then use bulk add-to-campaign or available campaign audience tools before sending. Preview or review recipient eligibility before production sends.
17	Use Gmail automated fallback carefully	If Dante, Nathan, or Andi need to use their own Gmail, select their sender in the email campaign editor. The CRM sends eligible recipients through that connected Gmail account in small scheduler batches instead of using Resend.

Email Status and Error Reference

Concise definitions for unusual campaign status and delivery messages.

#	Name	Description
1	Suppressed	Contact is blocked from campaign email because CRM or Resend marked the address ineligible. Common causes are bounce, complaint, provider suppression, unsubscribe, or manual block.
2	Bounced	Recipient mailbox or provider rejected the email. Review before retrying; repeated bounces hurt sender reputation.
3	Failed	CRM or provider could not send the message. Check the recipient error detail, commonly invalid email format, missing recipient, provider rejection, or malformed send payload.
4	Complained	Recipient marked the email as spam or complaint-equivalent. Do not resend marketing email without a clear compliance review.
5	Email subscribed	Contacts with an email address are treated as subscribed for CRM marketing unless they have unsubscribed, complained, bounced into suppression, or were manually suppressed.
6	Opened	Resend reported an open-tracking event. This means the tracking pixel loaded, not necessarily that the recipient carefully read the email.
7	Clicked	Resend reported a link click. Campaign detail shows clicked links when the provider event includes a URL.

Duplicate and Merge Guide

How duplicate and merged contact states should be interpreted.

#	Name	Description
1	Duplicate tag	A Duplicate tag means another active contact currently shares the same normalized email or phone. Review the contact detail before sending broad campaigns.
2	Merge button	The Merge button appears when active duplicate candidates are available. Merging keeps the selected primary contact and consolidates activities, campaign recipient history, categories, tasks, provider events, suppressions, and opportunity context.
3	Merged tag	A Merged tag means the contact has merge history. The system records merge details in Activity, not in the editable Notes field.
4	Campaign protection	When adding recipients, the CRM skips repeat email addresses for email campaigns and repeat phone numbers for SMS campaigns, even if duplicates have not been manually merged yet.
5	Cleanup cadence	Run a duplicate review before larger email or SMS campaigns so reporting, contact ownership, and activity history stay clean.

Approval and Guardrail Summary

Controls that protect against accidental sends, compliance misses, and duplicate processing.

#	Name	Description
1	Email approval removed	Email approval is removed. Hard caps and reputation checks are the active guardrails.
2	SMS approval removed	SMS approval is removed. Hard caps, opt-in checks, destination validation, and Twilio delivery monitoring are the active guardrails.
3	Send-state protection	SENDING, PAUSED, and SENT campaigns cannot be manually re-sent.
4	Paused campaign protection	PAUSED campaigns are intentionally skipped by scheduler recovery until an operator resumes them.
5	Scheduler locking	Campaign cron uses locks and atomic claiming to reduce duplicate sends.
6	Stale sending recovery	Scheduler can recover stale SENDING campaigns that still have pending recipients.
7	Email unsubscribe and suppression	Campaign email includes tokenized unsubscribe support and blocks unsubscribed, bounced, complained, suppressed, and otherwise ineligible recipients.
8	Unknown email consent	Website leads with unknown CRM email-marketing field values are treated as subscribed unless they have unsubscribed or are suppressed.
9	SMS opt-in and keywords	SMS sends require phone and active opt-in state. STOP-style replies opt out. START-style replies restore opt-in.
10	Manual pause	Campaigns no longer auto-pause. Operators can manually pause campaigns when delivery health, audience quality, or content requires review.
11	Webhook and cron protection	Resend webhooks validate signed events when configured. Twilio webhooks validate signatures in production. Protected cron endpoints require CRON_SECRET.
12	Domain safety	Do not edit Google Workspace MX records when changing Resend or CRM DNS.
13	Pipeline automation	Completed outbound email, SMS, and call activity can mark New Lead opportunities as Contacted.

Current Limitations

Known issues and boundaries that should stay visible until resolved.

#	Name	Description
1	Gmail watches	Manual Gmail Watch Renewal run on 2026-05-22 confirmed 5 active watches. buyers@acquira.com is active through 2026-05-28T18:07:43Z. Continue normal scheduled renewal monitoring.
2	Resend plan totals	Resend dashboard verified Transactional Pro at 50,000 monthly emails, unlimited daily sends, Marketing Free, and 5 req/s team rate limit on 2026-05-19. Vercel production includes RESEND_MONTHLY_EMAIL_QUOTA=50000, RESEND_DAILY_EMAIL_QUOTA=unlimited, and RESEND_MARKETING_CONTACT_QUOTA=1000, so this is no longer an active caveat unless the plan changes.
3	Email consent completeness	Most email contacts still have unknown marketing status. The CRM now makes this visible in contact details and email campaign readiness, but operators should still segment broad marketing carefully.
4	Duplicate contacts	Duplicate email and phone groups remain, including test values. Campaign recipient add skips repeat email or phone recipients within the same campaign, but cleanup is still needed for cleaner reporting and contact history.
5	Legacy merge audit history	Exact duplicate merge audit notes start with the 2026-05-20 merge safeguard release. Older merges deleted duplicate records without a durable merge event, so historical merge details should not be reconstructed unless verified from an external backup or database log.
6	SMS campaign queue	Live production check on 2026-05-26 showed all campaigns in SENT status and 0 pending campaign recipients. FL June Biz Tour is no longer an active paused-queue caveat; continue reviewing SMS failure reasons and blocked carrier/landline history before reusing similar audiences.
7	Advanced image asset management	Campaign editor supports hosted image URLs plus Vercel Blob-backed upload, drag/drop, paste, centered logo insertion, and rich-editor text/image alignment. The Health Dashboard now shows Image Uploads and Campaign Image Storage readiness. Advanced image library management such as replace, rename, and image dimension controls remains a future enhancement.
8	Twilio carrier queue limits	CRM now shows SMS campaign throughput, pacing, pending queue, and configured quota math. Carrier-side queue limits and billing remain Twilio Console source-of-truth items.
9	Advanced nested segment groups	Contacts supports reusable saved filters and campaign recipient assignment workflows. More complex nested segment groups remain a future enhancement unless operators need deeper targeting.
10	Gmail fallback metrics	Gmail fallback campaigns create campaign recipient sent status and outbound contact activity when sent, but do not produce Resend delivery, open, click, bounce, or complaint metrics.
11	Database baseline	Prisma migration, Supabase policy baseline, RLS review, and activity retention policy remain governance follow-ups.

Current Cost Model

Current subscription posture and what still needs billing confirmation.

#	Name	Description
1	Vercel	Current CRM hosting is modeled as Hobby at $0/mo. Pro reference is $20/user/mo.
2	Supabase	Current CRM database is modeled as Free at $0/mo. Pro reference starts at $25/mo.
3	Resend	Dashboard verified Transactional Pro for acquira under andi@acquira.com. Current model uses $20/mo for 50,000 transactional emails/month, unlimited daily sends, and Marketing Free with 1,000 contacts. Paid transactional overage reference is $0.90/1,000 emails when pay-as-you-go is enabled.
4	Twilio local numbers	CRM has 4 active local numbers. Prior model uses $1.15/number/mo, or $4.60/mo fixed number cost before usage.
5	Twilio usage	SMS, inbound voice, outbound voice, call recording, carrier fees, and A2P fees are usage-based. Twilio Console Usage is the billing source of truth.
6	Airtable	Shared company cost. Prior CRM docs listed $264/mo, but seat count and billing should be confirmed.
7	Google Workspace and Drive	Shared company subscription used for OAuth, Gmail, Workspace accounts, Drive storage, and retained call artifacts.
8	Gemini / OpenAI	Usage-based AI costs. Gemini is active for call transcript and summary processing.
9	Cloudflare Pages	Hosted docs are deployed to Cloudflare Pages and treated as low/no incremental CRM cost unless billing says otherwise.
10	GitHub Actions and DNS	Schedulers and CI are treated as included unless usage exceeds included GitHub limits. Namecheap/DNS is shared company infrastructure.

#	Name	Description
1	Minimum CRM-specific fixed subscription	$0 Vercel Hobby + $0 Supabase Free + $20 Resend Transactional Pro + $4.60 Twilio numbers = $24.60/mo, before SMS, voice, recording, carrier, A2P, AI, and taxes.
2	SMS campaign usage formula	outbound SMS segments x ($0.0083 Twilio base + carrier fee). Current public long-code carrier fee references are roughly $0.0035-$0.0050 per outbound segment, so 1,000 outbound single-segment SMS is roughly $11.80-$13.30, before inbound replies, failed-message fees, A2P fees, and taxes.
3	Resend overage formula	Included quota is 50,000 transactional emails/month. If pay-as-you-go is enabled, additional transactional volume is modeled as ceil(overage_emails / 1000) x $0.90.
4	Shared company tools included separately	Airtable, Google Workspace, domain/DNS, GitHub, and Cloudflare may already be paid by Acquira. If finance includes the prior Airtable estimate, the modeled fixed cost becomes $24.60 + $264.00 = $288.60/mo, before usage.
5	Current billed truth source	Use Resend Billing/Usage, Twilio Console Usage, Vercel Billing, Supabase Billing, Airtable billing, and Google Workspace billing for invoice-level truth. The CRM model is an operating estimate, not an accounting ledger.

Use this guide first when you need the CRM setup explained without implementation detail.

Primary CRM

Current Caveats