Docs

Email verification as an AI tool

Model SDKs share one pattern: you describe a function, the model asks to call it with arguments, your code runs it and sends back the result. ValidReach is one HTTP call, so the function is short.

The function

import os
import requests

def verify_email(email: str) -> dict:
    res = requests.post(
        'https://validreach.dev/api/v1/verify/single',
        headers={'Authorization': f"Bearer {os.environ['VALIDREACH_API_KEY']}"},
        json={'email': email},
        timeout=30,
    )
    body = res.json()
    if not body.get('success'):
        return {'error': body.get('message', 'request failed'), 'http': res.status_code}
    d = body['data']
    return {k: d.get(k) for k in ('email', 'status', 'is_deliverable', 'reason', 'retryable')}

The tool description

Give the model a name, a one-line description and a schema with a single string field called email. Say in the description that unknown means no conclusion, not invalid.

Cautions

Each call spends a credit for definite results, so limit how many times an agent may call the tool in one run. Validate the argument is a single address before calling, and do not pass lists through a model; use the file endpoint for lists. A model can still mis-describe a result, so branch on data.status in your own code for decisions that matter.