Best Practices

A checklist for getting from API key to production sending without damaging your domain reputation. Follow these guidelines before enrolling real contacts into workflows.

1. Set Up Your Domain

The sandbox domain (mail.outreachagent.dev) is for testing only. For real outreach, add a custom domain, configure SPF and DKIM, and verify it.

• Add your domain via POST /v1/domains and configure the DNS records returned in the response.
• Use a subdomain for outreach (e.g. outreach.yourdomain.com) to isolate reputation from your primary domain.
• Complete the warmup schedule before sending at volume: week 1 at 5/day, week 2 at 15/day, week 3 at 30/day, week 4+ unrestricted.
• Set daily send limits with PUT /v1/send-limits to match your warmup stage.

See Domains & Deliverability for the full setup walkthrough.

2. Verify Contacts Before Sending

Hard bounces permanently damage sender reputation. Always verify email addresses before enrolling contacts into workflows.

• Verify individual contacts with POST /v1/contacts/:contactId/verify.
• For larger lists, use POST /v1/contacts/verify-bulk.
• Contacts marked invalid are automatically rejected from enrollment.
• Treat catch_all and unknown results with caution — monitor bounce rates closely when sending to these addresses.

See Email Verification for risk levels and configuration.

3. Write Like a Human

Cold email that sounds like a template gets ignored or marked as spam. Write like a real person sending a one-to-one message.

• Subject lines: plain, lowercase-friendly, no fake urgency. "Quick question" and "Following up" are red flags.
• Body copy: short sentences, conversational tone. Fragments and lowercase are fine. No walls of text.
• Follow-ups: every follow-up needs a fresh angle — a new observation, a different value prop, or a relevant piece of research. Never send "just bumping this."
• Personalization: reference something specific about the recipient or their company. Don't fake familiarity — use real research or explicit hypotheses.

Use the Cold Outreach Writer skill for AI-assisted drafting that follows these principles.

4. Test Before You Send

Never enroll real contacts into an untested workflow. Use these three tools in order:

Step 1: Simulate the workflow — dry-run the entire flow to verify branching and timing without sending anything.

const sim = await client.simulateWorkflow("wf_abc", {
  contactId: "con_xyz"
});
// Returns step-by-step trace of which nodes execute and why

Step 2: Preview all templates — render every email in the workflow for a real contact to check for missing variables or bad copy.

const preview = await client.previewWorkflow("wf_abc", {
  contactId: "con_xyz"
});
// preview.previews = [{ nodeId, label, subject, html, missingVariables }]

Step 3: Send a test email to yourself — deliver a real email from a specific node to your own inbox.

const result = await client.testSendWorkflow("wf_abc", {
  nodeId: "n1",
  to: "you@yourteam.com",
  contactId: "con_xyz",
  variables: { hook: "your recent product launch" }
});
// Delivers to you@yourteam.com — check your inbox

5. Send Smart

How you send matters as much as what you send. Configure workflows to mimic natural human sending patterns.

• Send windows: restrict sends to business hours in the recipient's timezone (e.g. 8am–11am). Cold email at 2am hurts reply rates and raises spam flags.
• Delay jitter: add jitterMinutes to delay nodes so emails don't all fire at the exact same minute. This makes sending patterns look natural.
• Inbox rotation: for lists over 50 contacts, use inboxIds on send nodes with round_robin or random rotation. Each contact sticks to one sender for the entire sequence.
• Exit criteria: always set exitCriteria: [{ trigger: "reply" }] at minimum. Stop sending when someone responds.
• Volume ramp: match your daily send limits to your warmup stage. Don't jump from 5/day to 500/day.

See Cold Email Deliverability for send window configuration and jitter examples.

6. Stay Compliant

OutreachAgent enforces opt-out automatically, but you need to configure it correctly.

• Set optOutMode on every workflow — "reply" (default) adds List-Unsubscribe headers and suppresses contacts who reply with unsubscribe intent.
• Include {{ unsubscribe_text }} in your templates for a soft opt-out line (e.g. "If this isn't relevant, just let me know and I won't reach out again.").
• Unsubscribed contacts are automatically suppressed and cannot be re-enrolled.
• Use a real sender identity and don't misrepresent who you are or why you're reaching out.

7. Monitor and React

Check GET /v1/metrics/summary regularly. These are your target thresholds:

• Delivery rate: above 95%
• Bounce rate: below 2%
• Complaint rate: below 0.1%

const metrics = await client.getMetricsSummary();
if (metrics.bounceRate > 0.02) console.warn("Bounce rate above 2%");
if (metrics.complaintRate > 0.001) console.warn("Complaint rate above 0.1%");

8. Common Mistakes

Quick reference of things that go wrong:

• Using the sandbox domain for real outreach — mail.outreachagent.dev is shared and not authenticated for your brand. Always use a verified custom domain.
• Skipping warmup — sending 500 emails on day one from a new domain is the fastest way to land in spam.
• Sending to unverified lists — a single batch with a high bounce rate can tank your domain reputation permanently.
• Enrolling contacts without testing the workflow — use simulate, preview, and test-send before publishing.
• Writing generic, template-sounding copy — "I hope this email finds you well" is a spam signal. Write like a person.
• Ignoring metrics — check delivery, bounce, and complaint rates after every campaign. Don't wait for the auto-pause to tell you something is wrong.
• Sending too fast, too soon — ramp volume gradually. Match send limits to your warmup stage.
• No exit criteria — always stop sending when someone replies. Sending follow-ups after a reply is a fast path to spam complaints.