Email verification for AI agents

Overview

MailTooth runs a remote, stateless Streamable HTTP MCP server. Your agent connects to one URL, discovers the verify_emailtool, validates its inputs from the published schema, and receives both a concise model-readable summary and the complete structured verification result.

The server supports current MCP Streamable HTTP clients and the stateless 2025 protocol family. Legacy standalone SSE endpoints and local stdio transport are not required.

Before you connect

You need three things:

1. A MailTooth account with enough credits for the verification type your agent will use.
2. A dedicated active API key. Set a conservative per-minute limit and total request limit for this one agent or workflow.
3. An MCP client that supports remote Streamable HTTP servers and custom request headers.

Five-minute setup

1. Open API keys, create a key named for the agent, and copy the secret once.
2. Add the MailTooth endpoint and an Authorization header to your MCP client. Start with the generic configuration below or jump to a client-specific recipe.
3. Restart or reconnect the client, then confirm that it discovers exactly one tool named verify_email.
4. Ask: “Verify person@example.com with MailTooth.” Review the tool arguments before approving the first call.

{
  "mcpServers": {
    "mailtooth": {
      "type": "http",
      "url": "https://api.mailtooth.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MAILTOOTH_API_KEY"
      }
    }
  }
}

Client configuration formats differ: Claude, Cursor, and Windsurf usemcpServers; VS Code uses servers. Copy the recipe for your client rather than renaming fields by guesswork.

Endpoint and authentication

Authenticate every MCP request with an existing MailTooth API key. Bearer authentication is recommended because it is supported by the widest range of remote MCP clients. The x-api-key header remains available when a client supports arbitrary headers.

A missing, malformed, revoked, or inactive key is rejected at the HTTP layer with 401 Unauthorized. No credits are reserved for authentication failures.

Connect popular agents

Choose one recipe. The configuration is global when you want MailToothin every workspace and project-scoped when a team should share the server definition. Keep the actual key in a user-local secret store even when the non-secret configuration is committed.

export MAILTOOTH_API_KEY='YOUR_MAILTOOTH_API_KEY'

claude mcp add --transport http mailtooth 'https://api.mailtooth.com/mcp' \
  --scope user \
  --header "Authorization: Bearer $MAILTOOTH_API_KEY"

claude mcp list
claude mcp get mailtooth

For a team-shared project definition, commit this .mcp.jsonfile without the secret and have every teammate setMAILTOOTH_API_KEY locally.

{
  "mcpServers": {
    "mailtooth": {
      "type": "http",
      "url": "https://api.mailtooth.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MAILTOOTH_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "mailtooth": {
      "type": "http",
      "url": "https://api.mailtooth.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MAILTOOTH_API_KEY"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mailtooth-api-key",
      "description": "MailTooth API key",
      "password": true
    }
  ],
  "servers": {
    "mailtooth": {
      "type": "http",
      "url": "https://api.mailtooth.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mailtooth-api-key}"
      }
    }
  }
}

{
  "mcpServers": {
    "mailtooth": {
      "serverUrl": "https://api.mailtooth.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAILTOOTH_API_KEY}"
      }
    }
  }
}

import { Agent, hostedMcpTool, run } from "@openai/agents";

const mailtooth = hostedMcpTool({
  serverLabel: "mailtooth",
  serverUrl: "https://api.mailtooth.com/mcp",
  headers: {
    Authorization: `Bearer ${process.env.MAILTOOTH_API_KEY}`,
  },
  allowedTools: ["verify_email"],
  requireApproval: "always",
});

const agent = new Agent({
  name: "Lead intake agent",
  instructions:
    "Verify every address before accepting it. Use addressStatus for Quick/Standard and mailbox.status for Deepcheck.",
  tools: [mailtooth],
});

const result = await run(
  agent,
  "Check person@example.com and tell me whether it is safe to contact.",
);

console.log(result.finalOutput);

Any other MCP client

Select the client's remote HTTP or Streamable HTTP server type, enter https://api.mailtooth.com/mcp, and add an Authorization header. Do not choose stdio, WebSocket, or a legacy SSE-only transport. If the client has no way to attach a static header, it cannot currently authenticate to MailTooth.

verify_email tool reference

MailTooth exposes one deliberately focused tool. A smaller tool surface reduces ambiguity for models and lets every call share the same validation, billing, rate-limit, and audit guarantees as the REST API.

enriched and pro are deprecated aliases for deepcheck. See the email verification guidefor the complete checks and response-field availability by type.

curl --no-buffer 'https://api.mailtooth.com/mcp' \
  --request POST \
  --header 'Authorization: Bearer YOUR_MAILTOOTH_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl --no-buffer 'https://api.mailtooth.com/mcp' \
  --request POST \
  --header 'Authorization: Bearer YOUR_MAILTOOTH_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2025-11-25' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "verify_email",
      "arguments": {
        "email": "person@example.com",
        "type": "deepcheck"
      }
    }
  }'

Read tool results

A successful call contains two representations of the same decision.content is a compact JSON summary optimized for the model;structuredContent is the complete typed object for your application, logs, routing, and deterministic post-processing.

{
  "content": [
    {
      "type": "text",
      "text": "{\"email\":\"person@example.com\",\"addressStatus\":\"valid\",\"mailboxStatus\":\"deliverable\",\"riskLevel\":\"low\",\"score\":98,\"confidence\":\"high\",\"verificationType\":\"deepcheck\",\"disposable\":false,\"roleBased\":false,\"creditsCharged\":2,\"creditsRemaining\":498}"
    }
  ],
  "structuredContent": {
    "email": "person@example.com",
    "verificationType": "deepcheck",
    "addressStatus": "valid",
    "mailbox": {
      "status": "deliverable",
      "isCatchAll": false,
      "signals": []
    },
    "risk": {
      "level": "low",
      "signals": []
    },
    "score": 98,
    "confidence": "high",
    "signals": [],
    "details": {
      "...": "complete verification result"
    },
    "meta": {
      "modelVersion": "deliverability-v2"
    },
    "creditsCharged": 2,
    "creditsRemaining": 498,
    "usage": {
      "apiKeyRemainingCalls": 999,
      "rateLimit": {
        "limit": 60,
        "remaining": 59,
        "resetAt": "2026-08-10T10:01:00.000Z"
      }
    }
  }
}

Design reliable agent workflows

Let the model decide when to call the tool, but keep the business decision deterministic in your application. TreatstructuredContent.addressStatus and structuredContent.mailbox.status as the source of truth rather than parsing prose from the final assistant response.

Credits, quotas, and rate limits

MCP uses the same account balance and API-key quotas as REST. The selected cost is reserved immediately before verification. Completed requested outcomes keep the charge. Quick and Standard remain chargeable when mailbox status is intentionally not_checked. Unknown required outcomes and failed executions are refunded automatically.

The successful structured result includes creditsCharged,creditsRemaining, apiKeyRemainingCalls, and the current rate-limit reset timestamp. Use these fields for budget alerts and graceful pauses.

Errors and retry policy

Connection and authentication problems appear as HTTP errors. Errors that occur while invoking verify_email return a normal MCP tool result with isError: true and a stable JSON error object inside the text content.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"code\":\"API_KEY_RATE_LIMIT_EXCEEDED\",\"message\":\"This API key has exceeded its per-minute rate limit.\",\"statusCode\":429,\"retryAfterSeconds\":17}}"
    }
  ]
}

Recommended retry behavior

1. Retry API_KEY_RATE_LIMIT_EXCEEDED only afterretryAfterSeconds.
2. Retry temporary 500/503 failures with exponential backoff, jitter, and a small maximum attempt count.
3. Do not retry invalid authentication, insufficient credits, or total key-limit errors until configuration changes.
4. Schedule unknown verification results for a later business retry; do not loop in the same agent turn.

Security and governance

• Create one API key per agent, environment, and workflow.
• Use the smallest practical per-minute and lifetime limits.
• Store keys in secret inputs, environment variables, or a vault.
• Never place keys in prompts, browser code, telemetry, or Git.
• Keep human approval enabled until tool behavior is understood.
• Allowlist only verify_email when the client supports tool filtering.
• Monitor usage analytics and rotate or revoke unusual keys immediately.
• Do not treat inferred names or gender associations as verified identity.

MCP tool annotations correctly declare the tool as non-destructive but not read-only or idempotent because it consumes credits and updates usage records. Clients may therefore show an approval step before a call.

Troubleshooting

Frequently asked questions