LinkedIn Outreach

LinkedIn outreach uses a bring-your-own Chrome extension model. heycmo's backend drafts and approves the actions; the customer's browser runs them via DOM events on their own machine. heycmo never sees, stores, or proxies the LinkedIn session cookie — LinkedIn auth lives entirely in the customer's browser.

This is the only LinkedIn automation posture that doesn't put the customer's account at restriction risk.

Configuration

Action types

The queue table has a single action column with three values:

Caps are per-customer per rolling-24h window — not calendar day, because customer timezones vary and LinkedIn's rate-limit clock is effectively a sliding window.

Hard limits

From linkedin-outreach-policy.ts:

export const MAX_CONNECTIONS_PER_DAY = 15;
export const MAX_MESSAGES_PER_DAY    = 30;
export const MAX_COMMENTS_PER_DAY    = 50;
export const MAX_CONNECTION_NOTE_LENGTH = 280;
export const MAX_MESSAGE_LENGTH         = 2000;
export const MAX_COMMENT_LENGTH         = 1000;
export const DRAFT_EXPIRY_DAYS          = 7;

A warm account safely sends 15–20 connection invites per day. Tools that push 30+ are what cause restrictions within 1–3 weeks. We default conservative.

The LinkedIn UI truncates connection notes at ~280 chars (even though the API technically allows 300), so we cap at 280 to avoid surprise truncations.

Schema

model LinkedinOutreachQueue {
  id               String    @id @default(uuid()) @db.Uuid
  customerId       String    @db.Uuid
  action           String    /// 'connection_request' | 'message' | 'comment'
  status           String    @default("pending_review")
  prospectUrl      String
  prospectName     String?
  prospectCompany  String?
  prospectRole     String?
  body             String
  dayOffset        Int       @default(0)
  intentSource     String?
  intentReason     String?
  approvedAt       DateTime?
  approvedByUserId String?   @db.Uuid
  sentAt           DateTime?
  resultUrl        String?
  errorMessage     String?
  lockedUntil      DateTime?
  expiresAt        DateTime  @default(dbgenerated("now() + interval '7 days'"))

  @@unique([customerId, prospectUrl, action, dayOffset])
}

Status flow:

pending_review ──approve──▶ approved ──claim──▶ (locked for 5 min) ──result──▶ sent
                  │                   │                                │
                  └─skip──▶ skipped   └──cap hit──▶ stays approved      └──▶ failed
                  │
                  └─7 days──▶ expired

URL validation: 1st-degree only

isValidLinkedInProfileUrl(url) accepts only /in/<slug> URLs:

✅ https://linkedin.com/in/jane-doe
✅ https://www.linkedin.com/in/jane-doe/
✅ linkedin.com/in/jane-doe
❌ https://linkedin.com/company/...
❌ https://linkedin.com/in/  (empty slug)

For connection_request and message actions, the prospect URL must pass this check. For comment actions, the URL can be any linkedin.com/... URL — comments come from feed-scrape signals on posts, not profiles.

Pre-flight per action

Three separate pre-flights, each returning { ok, reasons[] }:

• preflightConnectionRequest — URL must be /in/; note (if present) ≤280 chars.
• preflightMessage — URL must be /in/; body required, ≤2000 chars.
• preflightComment — URL must be a LinkedIn URL; body required, ≤1000 chars.

Queue lifecycle

Drafting (heycmo)

Mia's lead-outreach workflow (or the customer manually) inserts a row with status='pending_review'. The unique index (customerId, prospectUrl, action, dayOffset) makes drafting idempotent — re-running a workflow can never duplicate.

Approval

The customer reviews the draft in /outreach/linkedin and either approves or skips. Approval sets status='approved', stamps approvedAt + approvedByUserId. Skipping sets status='skipped' (terminal).

Claim by extension

The Chrome extension polls GET /api/linkedin/queue/:customerId/next every 90–300 seconds (randomized). The endpoint runs claimNextJob(customerId), which:

1. SELECT ... FOR UPDATE SKIP LOCKED for the oldest approved row whose lockedUntil is null or expired and whose expiresAt is in the future.
2. Inside the same transaction, runs canSendNow({ customerId, action }). If capped, returns null without locking (the row stays available; the cap will clear in 24h).
3. Otherwise, sets lockedUntil = now() + 5 min and returns the job.

The 5-minute lock means: if the extension tab is closed mid-action or the user's machine sleeps, the job becomes claimable again on the next tick.

Result reporting

After running the DOM action, the extension POSTs to /api/linkedin/queue/:customerId/:id/result with { success, resultUrl?, errorMessage? }. On success: markJobSent sets status='sent', stamps sentAt, clears lockedUntil. On failure: markJobFailed sets status='failed' with the truncated error message.

Randomized intervals

The extension itself enforces 90–300s randomized intervals between actions (not the backend). This is deliberate — the variance has to come from the actor's machine, not from server-side scheduling, to look like organic behavior.

7-day draft expiry

A daily cron calls expireStaleDrafts():

await prisma.linkedinOutreachQueue.updateMany({
  where: {
    status: { in: ['pending_review', 'approved'] },
    expiresAt: { lt: new Date() },
  },
  data: { status: 'expired' },
});

Drafts that have been sitting for more than 7 days are stale — the prospect's situation has changed, the intent signal is cold. Expiring keeps the queue clean and forces fresh research instead of stale outreach.

API endpoints

All endpoints are tenant-scoped under /api/linkedin/queue/:customerId/...:

UI at /outreach/linkedin

The page surfaces:

• Pending review — drafts Mia or the customer have queued, awaiting approval. One-click approve or skip.
• Approved & in flight — what the extension will pick up next.
• Sent — completed actions, with resultUrl (the resulting connection request, DM, or comment URL when LinkedIn returns one).
• Failed / expired — for triage.

Counters along the top show today's sends per action vs the cap (12 / 15 connection requests today).

Privacy posture

The whole point of the BYO-extension model:

• heycmo's backend never holds the LinkedIn session cookie.
• heycmo's backend never proxies LinkedIn HTTP requests.
• The actor IP that LinkedIn sees is the customer's IP, not a datacenter IP.
• All DOM actions run inside the customer's logged-in tab.

The contract with LinkedIn is clean: the customer is the actor, heycmo is the authoring tool. The server-side caps and 7-day draft expiry exist so the customer can't accidentally turn it into an aggressive automation tool.

Source files

• apps/api/agent/lib/linkedin-outreach-policy.ts — caps, validators, pre-flights, canSendNow, claimNextJob, expireStaleDrafts
• apps/api/agent/lib/__tests__/linkedin-outreach-policy.test.ts — full unit coverage
• apps/api/infra/server.ts — endpoints (search for /api/linkedin/)
• apps/web/src/pages/LinkedInOutreach.tsx — customer UI
• Chrome extension — separate repo + Web Store listing (linked from the in-app onboarding)