ADR-002: Zero-Cost Architecture for Gmail Integration

Status: Accepted Date: December 17, 2025 Decision Makers: CODITECT Engineering Team

---

Context

CODITECT must maintain zero external costs for API integrations. Gmail API offers generous free quotas, but we must design within these limits to avoid unexpected charges or service degradation.

Decision

We will use only free-tier Gmail API capabilities with rate limiting and quota management to ensure sustainable operation without external costs.

Gmail API Free Tier Limits

Resource	Free Quota	Our Design
Queries per day	1,000,000,000	< 100,000/day
Queries per 100 seconds	25,000	Rate limited
Per-user per 100 seconds	250	Token bucket
Send per day (consumer)	2,000	< 500/day
Send per day (Workspace)	10,000	< 2,000/day
Cloud Pub/Sub	Free tier	10GB/month

Features Included (Free)

1. Send Email - Via messages.send API
2. Read Email - Via messages.get/list API
3. Search Email - Via messages.list with query
4. Labels - Via labels API
5. Threads - Via threads API
6. Push Notifications - Via watch + Cloud Pub/Sub
7. Attachments - Via messages API (up to 25MB)

Features Excluded (Cost or Enterprise)

1. Gmail Add-ons - Not needed for our use case
2. Confidential Mode API - Enterprise only
3. Delegation without Workspace - Requires Workspace subscription

Rate Limiting Strategy

class GmailRateLimiter:
    """Stay well within free tier limits."""

    LIMITS = {
        "default": {"rate": 200, "per": 100},  # 80% of 250
        "send": {"rate": 50, "per": 100},       # Conservative
        "batch": {"rate": 40, "per": 100},
    }

Daily Quota Tracking

class QuotaTracker:
    """Track daily usage to prevent overages."""

    DAILY_LIMITS = {
        "send": 1500,     # 75% of 2000 (consumer)
        "queries": 80000, # Well under 1B
    }

    async def check_quota(self, operation: str) -> bool:
        current = await self._get_daily_count(operation)
        return current < self.DAILY_LIMITS.get(operation, float('inf'))

Consequences

Positive

• Zero API Costs: All features within free tier
• Sustainable Scale: Designed for thousands of users
• No Surprise Bills: Hard limits prevent overages
• Works with Consumer Gmail: Not just Workspace

Negative

• Rate Limiting: May slow down bulk operations
• Daily Caps: High-volume days may hit limits
• No Premium Features: Some enterprise features unavailable

Mitigation

• Implement queuing for non-urgent emails
• Batch operations where possible
• Alert on approaching quotas (80% threshold)
• Document Workspace benefits for enterprise customers

Cost Comparison

Approach	Monthly Cost	Emails/Day
Gmail API (our design)	$0	~2,000
SendGrid Free	$0	100
SendGrid Pro	$20+	50,000
AWS SES	~$0.10/1000	Unlimited
Mailgun	$35+	50,000

Related Decisions

• ADR-001: Email Provider Abstraction
• Google Meet ADR-002: Zero-Cost Architecture (parallel)

---

Document Control:

• Created: December 17, 2025
• Author: CODITECT Engineering Team