Documentation

DocsCore ConceptsDomains & Deliverability

Domains & Deliverability

Getting emails into the inbox — not the spam folder — requires proper domain authentication, gradual volume ramp-up, and ongoing reputation monitoring.

Custom Domain Setup

Before sending from a branded address, verify your domain. OutreachAgent requires two DNS records:

DKIM (TXT record) — Cryptographic signature proving emails are authorized by your domain. Publish the provided public key at outreachagent._domainkey.yourdomain.com.
SPF (TXT record) — Declares OutreachAgent's IP ranges are authorized senders. Add include:spf.outreachagent.dev to your SPF record.

Domain Verification Lifecycle

Domain Status Flow

pending → verifying → verified (success)
                    → failed    (retry)

After adding DNS records, OutreachAgent polls every 60 seconds for up to 72 hours. Both DKIM and SPF must validate for the domain to become verified.

Domain Schema

{
  id: string,
  name: string,
  status: "pending" | "verifying" | "verified" | "failed",
  dkimStatus: "missing" | "pending" | "verified",
  spfStatus: "missing" | "pending" | "verified",
  createdAt: string,
  dnsRecords?: [{ type, host, value, priority? }]
}

TypeScript

// Add a domain
const domain = await client.createDomain("yourdomain.com");
console.log(domain.dnsRecords); // DNS records to publish

// Check verification status
const status = await client.getDomain(domain.id);
console.log(status.dkimStatus); // "missing" | "pending" | "verified"
console.log(status.spfStatus);  // "missing" | "pending" | "verified"

curl

# Add a domain
curl -X POST https://api.outreachagent.dev/v1/domains \
  -H "Authorization: Bearer $OUTREACHAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "yourdomain.com"}'

# Check verification status
curl https://api.outreachagent.dev/v1/domains/dom_abc123 \
  -H "Authorization: Bearer $OUTREACHAGENT_API_KEY"

Domain Warm-up (Opt-in)

Warm-up is opt-in, not auto-enforced. Domains added to OutreachAgent may already have established sending reputation from other tools. Start warm-up via the API when needed:

Warm-up Ramp Schedule (daily send limit)

Week 1:  5 emails/day
Week 2:  15 emails/day
Week 3:  30 emails/day
Week 4+: Warm-up complete, no limit enforced

TypeScript

// Start warm-up for a new domain
await client.startDomainWarmup("dom_abc123");

// Check warm-up progress
const domain = await client.getDomain("dom_abc123");
console.log(domain.warmupDay);          // 5
console.log(domain.currentDailyLimit);  // 5
console.log(domain.warmupRecommended);  // false (already started)

// Stop warm-up (domain already warmed externally)
await client.stopDomainWarmup("dom_abc123");

curl

# Start warm-up
curl -X POST https://api.outreachagent.dev/v1/domains/dom_abc123/warmup/start \
  -H "Authorization: Bearer $OUTREACHAGENT_API_KEY"

# Stop warm-up
curl -X POST https://api.outreachagent.dev/v1/domains/dom_abc123/warmup/stop \
  -H "Authorization: Bearer $OUTREACHAGENT_API_KEY"

Newly added domains show warmupRecommended: true until warm-up is started. If the domain is already warmed up from another tool, you can safely ignore this flag or call warmup/stop to dismiss it.

Deliverability Metrics

Monitor via GET /v1/metrics/summary:

UsageSummary

{
  totalSent: number,
  totalDelivered: number,
  deliveryRate: number,    // 0–1, target > 0.95
  bounceRate: number,      // 0–1, target < 0.02
  complaintRate: number,   // 0–1, target < 0.001
  rejectionRate: number    // 0–1, investigate if spikes
}

If bounce rate exceeds 2% or complaint rate exceeds 0.1% for 24 hours, OutreachAgent pauses sending for the affected inbox and alerts the organization owner.