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

verify-email