Email & Calendar Integration for Relationship Strength

1. Overview

Ingest email and calendar metadata from each admin user's Google Workspace or Microsoft 365 account and turn it into three transparent relationship indicators on contacts:

• Connection strength — per team-member × contact: Warm Known Cold
• Contact reachability — per team × contact: High / Medium / Low / None
• Key connection — the best person on the team to ask for an intro

2. System architecture

Five pipeline stages — ingestion, resolution, rollup, enrichment, scoring — each isolated, each restartable independently. No stage writes outside its own tables.

Stage responsibilities

3. Data model

Five new tables. No changes to Contact, ContactEmail, or Collection. Three existing tables get additive columns.

New columns on existing UCC table

Enum values (stored as strings / Rails enums)

• INTERACTION_EVENT.provider: gmail, outlook, gcal, ocal
• INTERACTION_EVENT.kind: email, meeting
• INTERACTION_EVENT.direction: inbound, outbound, attended
• UCC.strength_tier / strength_override: warm, known, cold
• CONTACT_REACHABILITY.tier: high, medium, low, none

Fields excluded from the diagram for brevity

• USER_CONTACT_STATS also has email_inbound_count_24mo, email_outbound_count_24mo, email_last_inbound_at.
• USER_ENRICHED_PROFILE.raw is actually jsonb; INTERACTION_EVENT.raw_headers is jsonb.
• INTERACTION_EVENT.contact_id is nullable (intentional — unresolved interactions).

Why these shapes

• InteractionEvent is the single normalized store. Gmail, Outlook, calendars all land here. The contact_id being nullable is deliberate: unresolved interactions wait for resolution rather than forcing a premature contact creation.
• UserContactInteractionStats is a materialized cache, not the source of truth. Nightly rebuild + incremental updates on event insert. email_activity_bitmap_12q is a 12-bit int encoding 2-way activity per quarter — cheap to maintain, powerful for sustained-relationship detection.
• UCC gets four columns, not a new table. Strength lives where the team-member⇄contact link already lives. Override is a nullable enum so the absence of an override is explicit.
• ContactReachability is denormalized per (contact, collection). A cheap row-level recompute beats a per-request aggregation over hundreds of UCCs.
• UserEnrichedProfile intentionally mirrors ContactEnrichedProfile — same enrichment engine (Findem), same shape, same webhook wiring.

4. Integration status

Google Workspace Mostly live

Microsoft 365 Greenfield

Findem Pending capabilities

5. Service layer

Rule engine + scorer

The scorer is stateless: given a User and a Contact, it reads the rollup + overlap caches and returns a deterministic result.

Result = Struct.new(:tier, :score, :reasons)
# tier:    :warm | :known | :cold
# score:   Float, for within-tier sort only
# reasons: [{ code: :twoway_12mo_5plus, met: true, detail: "7 in / 9 out" }, ...]

class RelationshipStrengthService
  def self.call(user:, contact:)
    stats = UserContactInteractionStats.find_by(user: user, contact: contact)
    overlap = WorkOverlapCache.by_pair(user, contact)
    edu = EducationOverlapCache.by_pair(user, contact)

    evaluated = RULES.map { |rule| rule.evaluate(stats, overlap, edu) }
    tier = %i[warm known cold].find { |t| evaluated.any? { |r| r.tier == t && r.met } } || :cold
    score = WEIGHTED_SCORE.call(evaluated)
    Result.new(tier, score, evaluated.select(&:met))
  end
end

Rules are declared as data, not code:

RULES = [
  Rule.new(code: :twoway_12mo_5plus, tier: :warm, signal_weight: 3.0,
           predicate: ->(s, _, _) { s && s.email_inbound_count_12mo >= 5 && s.email_outbound_count_12mo >= 5 }),
  Rule.new(code: :sustained_2yr, tier: :warm, signal_weight: 2.5,
           predicate: ->(s, _, _) { s && s.email_active_quarters_consecutive >= 8 }),
  # ... 14 more ...
]

Adding a new signal = adding a Rule row. No changes to the evaluator.

Reachability service

Pure aggregation — runs once per (contact, collection) whenever any UCC tier in that collection changes.

class ReachabilityService
  THRESHOLDS = {
    high:   ->(c) { c[:warm] >= 1 || c[:known] >= 3 || c[:cold] >= 10 },
    medium: ->(c) { c[:known] >= 1 || c[:cold] >= 5 },
    low:    ->(c) { c[:cold] >= 1 }
  }.freeze

  def self.call(contact:, collection:)
    uccs = UserContactCollection.where(contact: contact, collection: collection)
    counts = uccs.group(:strength_tier).count.symbolize_keys
    tier = THRESHOLDS.find { |_, pred| pred.call(counts) }&.first || :none
    key = uccs.order(strength_tier_ordinal: :desc, strength_score: :desc).first&.user_id
    ContactReachability.upsert({ contact_id: contact.id, collection_id: collection.id,
                                 tier: tier, key_user_id: key, **counts, computed_at: Time.now })
  end
end

Rollup worker

Two entry points:

• Incremental: on every InteractionEvent insert via after_commit, bump counters and update the activity bitmap. O(1) per event.
• Nightly full: recompute all rows touched in the last 24h. Catches drift, re-bucketizes aging windows (e.g. emails that just fell outside the 12-month window).

Findem enrichment resolver

Lookup → cache → Contact match. Conservative: ambiguous Findem responses leave contact_id null.

6. Operational envelope

Quantitative choices, rate limits, and volume estimates — the numbers reviewers ask about when deciding whether this will scale or what it will cost.

7. Phased plan

8. FAQ

The sharp questions reviewers already have.

9. Open questions

Findem capability confirmations

1. F1 — person lookup by email: does the endpoint exist? Rate limits, cost per call, response schema, confidence scoring?
2. F3 — email-only enrichment: fallback when no handle is known?
3. F4 — user enrichment: any product/TOS concern enriching authenticated users vs. external contacts?
4. F6 — investor data: does Findem expose company investor / funding rounds?
5. LinkedIn degree: does Findem track 1st-degree LinkedIn connections? Long shot; would close the last V1 gap.

Team decisions before execution

1. Ship Slice A (thin V1, 50% heuristic activation) as the first customer-facing release, or wait for Slice C?
2. "Sustained at lower volume" threshold — recommend 8 of last 8 quarters continuous. Alternative: 6 of 8.
3. Reachability editable? Recommend no in V1 — it's a pure aggregation, editing would create drift.
4. Strength-override audit: when a user overrides, keep a record of what the rule engine would have said (for future rule tuning)?
5. Backfill horizon: 24 months default. Confirm.
6. Browser-extension LinkedIn capture: worth a short spike to see if 1st-degree data is already being scraped.

10. File references

Key existing Getro code to extend or mirror.

Backend

Admin portal

11. Decision records

Short ADRs for the non-obvious choices landed during this spike. The "why we picked this" future maintainers will ask.