Docs Concepts

Email Verification

Understand email verification and validation in mailshit.

Overview

Email verification helps ensure emails reach real recipients. mailshit provides verification at two levels:

  1. API Endpoint - Standalone email verification
  2. Flow Verification - Validation gates in your workflow

Why Verify Emails?

Protect Sender Reputation

Sending to invalid addresses hurts your reputation:

  • High bounce rates damage deliverability
  • ISPs may block your sending domain
  • Email providers may suspend your account

Improve Deliverability

Verified addresses are more likely to:

  • Accept your emails
  • Not mark them as spam
  • Engage with content

Save Money

Don’t pay to send to invalid addresses:

  • Most providers charge per email
  • Invalid sends are wasted money

Verification Checks

Format Validation

Basic structure check:

  • Contains @ symbol
  • Valid local part (before @)
  • Valid domain part (after @)

Domain Check

Verifies the domain exists and is reachable.

MX Records

Checks for Mail Exchange records:

  • Indicates domain can receive email
  • No MX records = can’t receive email

Disposable Detection

Identifies temporary email services:

  • Mailinator
  • Guerrilla Mail
  • 10 Minute Mail

These addresses are often used for spam or abuse.

Role-Based Detection

Identifies generic addresses:

  • info@
  • support@
  • admin@
  • webmaster@

These often go to shared inboxes or aren’t monitored.

API Verification

Use /verify for standalone verification:

curl -X POST https://api.mailsh.it/v1/verify \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

Response:

{
  "email": "test@example.com",
  "verification": {
    "valid": true,
    "format": true,
    "domain": true,
    "mxRecords": true,
    "disposable": false,
    "role": false
  }
}

Flow Verification Nodes

Add verification gates to your flow:

Email Domain Verification

Validates the _to address before sending:

[Template] → [Email Verification] → [Provider Output]

If invalid:

{
  "success": false,
  "type": "validation_failed",
  "error": "Invalid email address",
  "field": "_to"
}

Required Fields Verification

Ensures specific variables are provided:

Configure which variables are required:

  • firstName
  • orderNumber
  • etc.

If missing:

{
  "success": false,
  "type": "validation_failed",
  "error": "Missing required fields: firstName",
  "field": "firstName"
}

Custom Regex Verification

Validate variables against patterns:

  • Pattern: ^\d{5}$ (5 digits)
  • Field: zipCode

If no match:

{
  "success": false,
  "type": "validation_failed",
  "error": "Field zipCode does not match required pattern",
  "field": "zipCode"
}

Verification Flow

When flow has verification nodes:

1. Render template
2. Run ALL verification nodes
3. If ANY fail → return error
4. If ALL pass → continue to output

Verifications run before sending, protecting your sender reputation.

When to Use Verification

Always Verify

  • User-provided email addresses
  • Imported contact lists
  • Form submissions

Consider Verifying

  • Emails from trusted internal systems
  • Previously verified addresses

Skip Verification

  • Test/development emails
  • Internal team addresses
  • When speed is critical and risk is low

Best Practices

Verify Early

Check emails when users provide them, not just when sending.

Handle Failures Gracefully

if (result.type === 'validation_failed') {
  // Show user-friendly error
  // Don't expose technical details
}

Cache Results

Verification results can be cached:

  • Email format doesn’t change
  • Domain/MX status changes rarely

Don’t Block on Role/Disposable

These are warnings, not failures:

  • Some legitimate users use them
  • Decide based on your use case

Verification Limits

Verification counts against your API rate limit:

  • Consider batching
  • Cache results
  • Use flow verification instead of separate API calls