outreach

AI Agent Integration Guide for outreach-send-core

This file exists to make the package implementation path explicit for coding agents.

Goal

Integrate outreach-send-core by:

• implementing the send repository adapter
• wiring the send engine dependencies
• using GoogleFirstSeedProvider for production prospect discovery
• treating GooglePlacesSeedProvider as legacy/demo-only multi-source discovery unless you are intentionally debugging or extending that older path

Do not rewrite the engine logic unless you are intentionally modifying package behavior. The intended extension points are:

• OutreachRepository
• OutboundMailer
• EmailVerifier
• linkBuilder
• templateBuilder
• resolveReplyTo
• resolveGlobalDailyCap
• buildFallbackSubject
• ProspectSeedProvider

Fastest Correct Path

1. Implement OutreachRepository.
2. Instantiate createOutreachEngine(...).
3. Pass a mailer, link builder, and template builder.
4. Optionally pass an email verifier and verification evaluator.
5. Instantiate GoogleFirstSeedProvider(...) for production discovery.
6. Call provider.search(criteria) from your discovery job or admin action.
7. Import only result.seeds into the send pool.
8. Surface result.reviewCandidates in review UX, but do not auto-send or auto-approve them.
9. Call sendApprovedBatch(campaignId) from a job, queue worker, or admin action.

Required Repository Contract

You must implement all of these methods exactly:

• getCampaign(campaignId: string): Promise<OutreachCampaign>
• countSentSince(campaignId: string, since: Date): Promise<number>
• listApprovedSendCandidates(campaignId: string, limit: number): Promise<OutreachSendCandidate[]>
• getSuppressedEmailSet(normalizedEmails: string[]): Promise<Set<string>>
• suppressEmail(input: OutreachSuppressionInput): Promise<void>
• recordSuppressedSend(input: RecordSuppressedSendInput): Promise<void>
• recordFailedSend(input: RecordFailedSendInput): Promise<void>
• recordSentSend(input: RecordSentSendInput): Promise<void>

Required Shapes

OutreachCampaign

{
  id: string
  name?: string | null
  dailySendCap: number
}

OutreachSendCandidate

{
  prospect: {
    id: string
    campaignId: string
    companyName: string
    businessType?: string | null
    businessSummary?: string | null
  }
  contact?: {
    id: string
    email: string
    normalizedEmail: string
    name?: string | null
  } | null
  preview?: {
    id: string
    publicUrl?: string | null
  } | null
}

Non-Negotiable Invariants

• contact.normalizedEmail must already be lowercase and trimmed.
• countSentSince(...) must count successful sends, not failed or suppressed attempts.
• countSentSince(...) must be scoped to the requested campaign.
• listApprovedSendCandidates(...) must not return more than limit items.
• Candidate order matters. The engine processes candidates in the order returned by the repository.
• getSuppressedEmailSet(...) must return only the subset of input emails that are suppressed.
• preview.publicUrl must be a real public URL if the candidate is intended to send.
• Each attempted candidate ends in exactly one persisted outcome: recordSuppressedSend(...), recordFailedSend(...), or recordSentSend(...).

Canonical Engine Algorithm

When an agent calls sendApprovedBatch(campaignId), the package does this:

1. Load the campaign with getCampaign(campaignId).
2. In parallel: countSentSince(campaignId, startOfToday) resolveGlobalDailyCap(campaign)
3. Compute: campaignDailyCap = floor(max(campaign.dailySendCap, 0)) globalDailyCap = floor(max(configuredOrOverrideCap, 0)) dailyCap = min(campaignDailyCap, globalDailyCap) remainingDailyCap = max(dailyCap - sentTodayCount, 0)
4. If remainingDailyCap === 0, return immediately with all send counts at 0.
5. Fetch raw candidates with listApprovedSendCandidates(campaignId, remainingDailyCap).
6. Set approvedCount = rawCandidates.length.
7. Filter candidates: if contact is missing, increment skippedMissingContactCount if preview.publicUrl is missing, increment skippedMissingPreviewCount otherwise keep the candidate for send processing
8. Query existing suppressions with getSuppressedEmailSet(...) using the kept candidates’ normalizedEmail values.
9. If an EmailVerifier exists and isEnabled() is true, verify all non-suppressed emails in one batch.
10. If the verifier throws, the engine blocks sends for unsuppressed candidates and records them as failed.
11. For each kept candidate, increment attemptedCount.
12. Build a fallback subject before any suppression or send outcome is recorded.
13. If the candidate email is already suppressed: call recordSuppressedSend(...)
14. Else if verification is enabled but unavailable or missing for the candidate: call recordFailedSend(...)
15. Else if verification returns a result and the evaluator says sendable: false: optionally call suppressEmail(...) call recordSuppressedSend(...)
16. Else: build links resolve reply-to build the final template call mailer.send(...) call recordSentSend(...)
17. If mailer.send(...) throws: call recordFailedSend(...)
18. Return the aggregate SendBatchResult.

Meaning of Result Counters

• approvedCount: raw candidates returned by the repository before filtering missing contact/preview.
• attemptedCount: candidates with both a contact and a preview URL.
• sentCount: successful mailer sends recorded by recordSentSend(...).
• failedCount: failed attempts recorded by recordFailedSend(...).
• suppressedCount: existing suppressions plus verification-blocked suppressions recorded by recordSuppressedSend(...).
• skippedMissingContactCount: raw candidates dropped because contact was missing.
• skippedMissingPreviewCount: raw candidates dropped because preview.publicUrl was missing.
• firstError: first failure string encountered during batch execution.

Method-by-Method Semantics

getCampaign

Must return the campaign record used for caps and email context.

Minimum requirement:

• id
• dailySendCap

countSentSince

Use your send log table or equivalent source of truth.

Correct behavior:

• count only successful sends
• filter by campaignId
• filter by sentAt >= since

listApprovedSendCandidates

Return prospects approved for outreach in the order you want them processed.

Recommended behavior:

• prefilter to approved prospects only
• join the primary or selected contact
• join the preview record
• apply limit

It is acceptable to return candidates with missing contact or preview, but the engine will skip them and track that in the result counters.

getSuppressedEmailSet

This is a membership query, not a full export. Given a list of normalized emails, return a set containing only the ones that are suppressed.

suppressEmail

Persist a durable suppression record.

Recommended fields to store:

• email
• normalizedEmail
• domain
• reason
• source
• campaignId
• prospectId
• contactId
• metadata

recordSuppressedSend

Persist an outreach attempt that was intentionally not sent because the recipient was suppressed or verification blocked the send.

recordFailedSend

Persist an outreach attempt that should have sent but failed because verification was unavailable, the verifier returned no result, or the mailer threw an error.

recordSentSend

Persist a successful outbound send.

Recommended fields to store:

• candidate identifiers
• subject
• preview URL
• provider message ID
• provider metadata
• sentAt

Minimal Adapter Skeleton

import type {
  OutreachCampaign,
  OutreachRepository,
  OutreachSendCandidate,
  OutreachSuppressionInput,
  RecordFailedSendInput,
  RecordSentSendInput,
  RecordSuppressedSendInput,
} from 'outreach-send-core'

export class AppOutreachRepository implements OutreachRepository {
  async getCampaign(campaignId: string): Promise<OutreachCampaign> {
    // Query campaign table and return dailySendCap.
  }

  async countSentSince(campaignId: string, since: Date): Promise<number> {
    // Count successful sends for this campaign where sentAt >= since.
  }

  async listApprovedSendCandidates(
    campaignId: string,
    limit: number,
  ): Promise<OutreachSendCandidate[]> {
    // Return approved prospects plus contact and preview data.
  }

  async getSuppressedEmailSet(normalizedEmails: string[]): Promise<Set<string>> {
    // Query suppressions WHERE normalized_email IN (...)
  }

  async suppressEmail(input: OutreachSuppressionInput): Promise<void> {
    // Insert durable suppression record.
  }

  async recordSuppressedSend(input: RecordSuppressedSendInput): Promise<void> {
    // Insert send log row with status = 'suppressed'.
  }

  async recordFailedSend(input: RecordFailedSendInput): Promise<void> {
    // Insert send log row with status = 'failed'.
  }

  async recordSentSend(input: RecordSentSendInput): Promise<void> {
    // Insert send log row with status = 'sent'.
  }
}

Minimal Engine Wiring

import {
  BrevoOutboundMailer,
  BouncerEmailVerifier,
  createOutreachEngine,
  evaluateBouncerEmailVerification,
} from 'outreach-send-core'

const engine = createOutreachEngine({
  repository: new AppOutreachRepository(),
  mailer: new BrevoOutboundMailer({
    apiKey: process.env.BREVO_API_KEY,
    fromEmail: process.env.EMAIL_FROM,
    fromName: process.env.EMAIL_FROM_NAME,
  }),
  emailVerifier: new BouncerEmailVerifier({
    apiKey: process.env.BOUNCER_API_KEY,
  }),
  evaluateEmailVerification: evaluateBouncerEmailVerification,
  resolveGlobalDailyCap: async () => 50,
  resolveReplyTo: async () => 'hello@example.com',
  linkBuilder: async ({ campaign, contact, preview }) => ({
    previewUrl: preview.publicUrl,
    unsubscribeUrl: `https://example.com/unsubscribe?email=${encodeURIComponent(contact.email)}`,
    registerUrl: `https://example.com/register?campaign=${campaign.id}`,
  }),
  templateBuilder: async ({ prospect, links }) => ({
    subject: `Preview for ${prospect.companyName}`,
    htmlContent: `<a href="${links.previewUrl}">Open preview</a>`,
    textContent: `Open preview: ${links.previewUrl}`,
    tags: ['outreach'],
  }),
})

await engine.sendApprovedBatch('campaign_123')

What Not To Do

• Do not count suppressed or failed attempts as successful sends in countSentSince(...).
• Do not return uppercase or untrimmed normalizedEmail values.
• Do not call recordSentSend(...) before the mailer succeeds.
• Do not assume approvedCount === attemptedCount.
• Do not skip persistence of suppressed and failed outcomes.
• Do not use GooglePlacesSeedProvider as a replacement for the send repository. Prospect search is a separate feature.
• Do not import reviewCandidates into the automatic send pool.
• Do not silently fall back to OpenStreetMap, generic web search, or LLM hints in production when GoogleFirstSeedProvider is being used.
• Do not treat a degraded Google-first result as a success case that should trigger automation imports.

Production Prospect Search

Use GoogleFirstSeedProvider for production discovery.

Fastest Correct Path

import {
  GoogleFirstSeedProvider,
  type ProspectSeedProvider,
  type SearchCriteria,
} from 'outreach-send-core'

const provider: ProspectSeedProvider<string> = new GoogleFirstSeedProvider({
  apiKey: process.env.GOOGLE_PLACES_API_KEY,
  publicServiceUserAgent: process.env.PUBLIC_SERVICE_USER_AGENT,
  publicServiceReferer: process.env.PUBLIC_SERVICE_REFERER,
  maxExpandedMunicipalities: 12,
  searchBudgetMs: 120000,
  crawlPageLimit: 5,
  maxEnrichmentCandidates: 100,
})

const result = await provider.search({
  country: 'IT',
  language: 'it',
  cities: ['Milano'],
  provinces: [],
  businessTypes: ['clothing_store'],
  keywords: [],
  limit: 100,
})

const acceptedSeeds = result.seeds
const reviewQueue = result.reviewCandidates ?? []

Discovery Contract

GoogleFirstSeedProvider.search(criteria) returns:

• seeds accepted-only prospects that are safe to import into the automatic send pool
• reviewCandidates borderline prospects that must stay out of automation until a human reviews them
• diagnostics counts and notes that explain what happened during discovery

Production Invariants

• seeds are accepted-only.
• reviewCandidates are not accepted.
• reviewCandidates must never be auto-imported into the approved send pool.
• Production discovery uses Google Places as the business identity source of truth.
• Public crawling is allowed only after a Google business has already been accepted as the business-of-record.
• If Google Places is unavailable or the API key is missing, the provider returns a degraded result instead of silently falling back to noisy sources.

Meaning Of Discovery Output

• result.seeds accepted businesses that passed identity, type, website, and contact gates
• result.reviewCandidates businesses that look plausible but have weak evidence such as low-quality contact data
• diagnostics.acceptedCount number of accepted prospects in result.seeds
• diagnostics.reviewCount number of review-queue prospects
• diagnostics.rejectedCount number of rejected prospects
• diagnostics.rejectionCountsByStage rejection reasons grouped by gate, such as type_gate.type_mismatch
• diagnostics.reviewCounts review reasons such as low_quality_role or off_domain_email

Expected Production Behavior

• A wrong-type business like Amplifon must be rejected for clothing_store discovery.
• A valid apparel store with a matching business-domain email can be accepted.
• A valid apparel store with a weak contact such as a privacy or DPO address should move to reviewCandidates, not seeds.
• A missing Google Places API key should produce a degraded result with zero imports, not a fallback import.

Legacy Multi-Source Search Notes

The bundled GooglePlacesSeedProvider remains available as a province-aware multi-source finder while keeping the same search(criteria) entrypoint.

Important behavior:

• returned seeds are already filtered to accepted outreach-worthy prospects
• primaryEmail and qualityScore may be present on each returned seed
• diagnostics can include rawCandidateCount, acceptedCandidateCount, rejectionCounts, and sourceContributionCounts
• Italian province inputs can expand into smaller municipalities during discovery

Use this class only if you are intentionally working on the older multi-source finder. Do not make it the default production discovery provider for new integrations.

Acceptance Checklist

An implementation is correct if all of these are true:

• A batch with no remaining cap returns immediately with zero attempts.
• A candidate missing contact increments skippedMissingContactCount.
• A candidate missing preview.publicUrl increments skippedMissingPreviewCount.
• An already suppressed recipient produces recordSuppressedSend(...) and no mailer call.
• A verifier outage produces recordFailedSend(...) for unsuppressed candidates and no mailer call.
• A blocked verification decision can create a suppression via suppressEmail(...).
• A successful send produces exactly one recordSentSend(...).
• A thrown mailer error produces exactly one recordFailedSend(...).
• Production discovery imports only result.seeds.
• Production discovery never auto-imports reviewCandidates.
• A missing or invalid Google Places key yields a degraded production discovery result instead of a noisy fallback import.

Source Of Truth

If this file and code ever disagree, the code in src/engine.ts and src/types.ts is the source of truth.

This site is open source. Improve this page.