LangChain Email Verification Tool for AI Agents

By Aria Pramesi, founder of InboxPolicy · Updated July 20, 2026

This guide uses a small LangChain tool wrapper around POST /v1/decide, authenticated with x-api-key, or an MCP connection exposing decide_send. The API returns five actions, confidence, status, signals, cache state, and cost for pre-send branching.

Wrap the REST endpoint

The integration below depends only on the documented REST contract. This avoids coupling the workflow to a vendor-specific LangChain package.

The worked path is to wrap the real REST route. The API base URL is https://api.inboxpolicy.com, the single-address send-decision endpoint is POST /v1/decide, and authentication is an x-api-key header (a present invalid key returns 401; an absent key receives an HTTP 402 x402 challenge). The MCP server is a separate transport that maps decide_send to the same REST /v1/decide endpoint. For the framework-neutral primer on REST, MCP, x402, and agent branching, see email verification for AI agents.

The five actions a LangChain tool should branch on

POST /v1/decide returns exactly five actions — call them actions or send-decision verdicts, not a new enum:

• send
• send_with_caution
• review
• retry_later
• avoid

The full response includes request_id, email, action, reason, confidence, status, retry_at, signals (catch_all, disposable, free, role_account), from_cache, and cost. Note that retry_at is included by the route even though it is not listed in the OpenAPI response schema. Branch your agent on the action field; do not fabricate a status-to-action mapping.

A practical distinction: /v1/decide can return avoid for malformed input without billing, while /v1/verify instead raises 422 for a syntax failure. Keep that explicit. Verification eligible cache hits for the same normalized address and strictness within 72 hours when force_refresh is false are free and expose from_cache; force_refresh bypasses the lookup.

Worked example: wrap POST /v1/decide as a LangChain StructuredTool

This uses the API-key path, which is the fully source-grounded path for the example. The request fields match the route's verify schema (email, strictness, force_refresh), and the response fields are assembled by the route. Reuse the same idempotency-key when the same workflow retries — one concurrent execution is stored/replayed, while conflicting or in-flight reuse can return 409.

import json
import os
from typing import Literal
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

# LangChain API: verify this wrapper syntax against your installed version.
from langchain_core.tools import StructuredTool

Strictness = Literal["aggressive", "default", "strict"]


def inboxpolicy_decide(
    email: str,
    idempotency_key: str,
    strictness: Strictness = "default",
    force_refresh: bool = False,
) -> dict:
    """Return InboxPolicy's send-decision response for one email address.

    InboxPolicy contract: POST https://api.inboxpolicy.com/v1/decide
    with JSON {email, strictness?, force_refresh?}.
    """
    payload = {
        "email": email,
        "strictness": strictness,
        "force_refresh": force_refresh,
    }
    request = Request(
        "https://api.inboxpolicy.com/v1/decide",
        method="POST",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "content-type": "application/json",
            "x-api-key": os.environ["INBOXPOLICY_API_KEY"],
            # Reuse this exact key when the same workflow retries.
            "idempotency-key": idempotency_key,
        },
    )

    try:
        with urlopen(request, timeout=15) as response:
            return json.loads(response.read().decode("utf-8"))
    except (HTTPError, URLError) as exc:
        detail = exc.read().decode("utf-8", errors="replace") if isinstance(exc, HTTPError) else str(exc)
        raise RuntimeError(f"InboxPolicy request failed: {detail}") from exc


# Verify StructuredTool syntax against the installed LangChain version.
inboxpolicy_tool = StructuredTool.from_function(
    func=inboxpolicy_decide,
    name="inboxpolicy_decide_send",
    description=(
        "Before sending an email, call InboxPolicy. Branch on the returned action: "
        "send, send_with_caution, review, retry_later, or avoid. "
        "Do not send as a side effect of this tool."
    ),
)

Why this example is honest: it uses only InboxPolicy fields and headers present in the route and docs. It does not claim a vendor SDK, a LangChain adapter, an outbound email side effect, or Python x402 support. A caller should supply a stable workflow-specific idempotency_key; it should not generate a new key for every retry. The StructuredTool.from_function syntax and the langchain_core.tools import are not pinned or verified against a specific LangChain version; verify them against the version you run — verify them against the version you run; the InboxPolicy contract is the HTTP call, not this wrapper API.

Authenticating the call: x-api-key

The API-key path authenticates with an x-api-key header supplied through INBOXPOLICY_API_KEY. The worked wrapper assumes that key is already provisioned; purchasing and provisioning are outside this integration example. Wallet usage pricing for the separate x402 REST path is documented on the docs page.

This example does not implement the keyless x402 flow. The keyless path starts with a 402 challenge, then uses a PAYMENT-SIGNATURE header; the server settles before returning a billable product response. Keyless x402 requires an EVM wallet funded with USDC on Base and does not require an account or API key. The repository's documented x402 quickstart is JavaScript for any Python helper the repo does not ship — do not imply the wrapper above implements x402.

Keyless x402 and idempotency are not interchangeable. The non-x402 path enters an idempotency wrapper, while the x402 path settles without that wrapper. For paid agent loops, explicitly design payment and retry handling, and avoid blindly signing a second payment after an indeterminate settlement.

Alternative transport: connect through MCP

If your LangChain deployment already has a verified MCP client, you can expose InboxPolicy's remote MCP server as a tool provider instead of writing a REST wrapper. The remote endpoint is https://mcp.inboxpolicy.com with an x-api-key header; the remote handler rejects a missing or invalid key before the MCP handshake. InboxPolicy itself does not provide the LangChain client or adapter in this repository — verify the client library and Streamable HTTP compatibility separately.

The MCP server exposes seven tools — decide_send, verify_email, estimate_credits, create_verify_batch, get_batch_status, get_batch_items, and get_usage — and decide_send maps to POST /v1/decide. For the MCP-specific guide (configuration and the full tool list), see MCP email verification for agents. Batch tools are source-verified but intentionally out of scope for this single-email example.

What this example deliberately does not do

• The example uses the documented REST contract. It does not depend on a vendor-specific LangChain package.
• The example is API-key-only. It does not implement keyless x402. The payment client is a separate integration concern.
• Stable idempotency keys are caller-owned. The API fingerprints the request and replays or stores responses for the key. Do not generate a fresh key on each retry.
• /v1/decide is decision-shaped. It returns one action plus reason, confidence, status, signals, cache state, and cost. The guide branches on action; it does not fabricate a status-to-action mapping.
• Do not conflate /v1/decide and /v1/verify. /v1/verify has full verification detail and raises 422 for syntax failure; /v1/decide preserves an action response for malformed input.
• Hosted MCP authentication is key-based. Keyless x402 is a separate REST path.

Related guides

For the framework-neutral primer on REST, MCP, x402, and agent branching, see email verification for AI agents. For the MCP-specific alternative, especially if you do not need a REST wrapper, see MCP email verification for agents. For canonical endpoint, auth, quickstart, idempotency, x402, and MCP reference, see the docs.

Frequently asked questions