Email Verification

Setup

Read your credentials from ~/.gooseworks/credentials.json:

export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])")
export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))")

If ~/.gooseworks/credentials.json does not exist, tell the user to run: npx gooseworks login

All endpoints use Bearer auth: -H "Authorization: Bearer $GOOSEWORKS_API_KEY"

Check if an email address is valid, exists, and can receive mail. Prevent bounces before sending.

When to Use

• User wants to verify an email before sending
• User asks "is this email address real?"
• Cleaning an email list
• Before cold outreach to avoid bounces
• Validating user-provided email addresses

How It Works

Uses Hunter or Tomba APIs to verify email deliverability through multiple checks including syntax, domain, and mailbox verification.

Usage

Verify with Hunter

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"hunter","path":"/v2/email-verifier","query":{"email":"john@example.com"}}'

Verify with Tomba

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tomba","path":"/v1/email-verifier","query":{"email":"jane@company.com"}}'

Parameters

• email (required) - The email address to verify

Response

Hunter Response

Returns data object:

• status (string) - valid, invalid, accept_all, or unknown
• score (integer) - Confidence score 0-100
• result (string) - deliverable, undeliverable, or risky (deprecated — use status)
• regexp (boolean) - Syntax is valid
• gibberish (boolean) - Address looks random
• disposable (boolean) - Temporary email service
• webmail (boolean) - Free webmail provider (Gmail, Yahoo, etc.)
• mx_records (boolean) - Domain has MX records
• smtp_server (boolean) - SMTP server responds
• smtp_check (boolean) - Mailbox exists on server
• accept_all (boolean) - Server accepts all addresses
• block (boolean) - Email is blocked
• sources (array) - Web pages where this email was found

Tomba Response

Returns data.email object:

• status (string) - valid, invalid, or accept_all
• result (string) - deliverable, undeliverable, or risky
• score (integer) - Confidence score 0-100
• smtp_provider (string) - Email provider name (e.g., "Google Workspace")
• mx (object) - records array of MX hostnames
• mx_check, smtp_server, smtp_check (boolean) - Verification checks
• accept_all, greylisted, block (boolean) - Server behavior flags
• gibberish, disposable, webmail, regex (boolean) - Address quality checks
• whois (object) - Domain registration: registrar_name, referral_url, created_date

Also returns data.sources array with uri, website_url, extracted_on, last_seen_on, still_on_page.

Result Types

Status	Meaning	Action
valid	Mailbox exists and accepts mail	Safe to send
invalid	Mailbox doesn't exist or domain has no MX	Don't send
accept_all	Server accepts any address — can't confirm mailbox	Send with caution
unknown	Couldn't verify (timeout, greylisting)	Verify manually

Examples

User: "Check if hello@acme.com is a real email"

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"hunter","path":"/v2/email-verifier","query":{"email":"hello@acme.com"}}'

User: "Verify sarah.jones@startup.io before I send my pitch"

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tomba","path":"/v1/email-verifier","query":{"email":"sarah.jones@startup.io"}}'

Error Handling

• 400 - Missing or malformed email parameter
• 401 - Invalid API key — check orth auth
• 429 - Rate limit exceeded — wait and retry
• If both APIs return unknown, the mail server is likely blocking verification — try later
• Tomba may return greylisted: true — means the server deferred; retry after a few minutes

Tips

• Always verify emails before bulk sending to protect sender reputation
• "Valid" doesn't guarantee delivery - content still matters
• Role-based emails (info@, sales@) may be valid but less effective for outreach
• Disposable emails (tempmail, etc.) are detected and flagged
• Some corporate domains block verification - "unknown" doesn't mean invalid