Skip to content

// ai agents and mcp

Via MCP server

Codex email verification with pingutil

Codex will happily write an email-cleaning script, but the script can only check syntax because nothing tells it which mailboxes exist. A four-line [mcp_servers.pingutil] entry in config.toml gives Codex the pingutil tools, with the API key read from an environment variable through bearer_token_env_var so it never lands in the config file.

Where it connects: Codex config.toml [mcp_servers.<name>] streamable HTTP entry with url and bearer_token_env_var

What goes wrong without it

  • Codex wrote us a beautiful lead cleaner that validates the regex and nothing else.
  • I do not want our API key pasted into config.toml where it ends up in dotfile backups.
  • Our default 60-second tool timeout and a slow corporate mail server do not get along.

What you can do with Codex and pingutil

  • Clean a lead file in a Codex task

    Ask Codex to verify the email column of a CSV with verify_emails, 50 at a time, and write valid, review and rejected files based on status. The verification happens through the tool, the file handling in code.

  • Generate test fixtures from real classifications

    Have Codex call lookup_email with fast: true on sample addresses and save the responses as JSON fixtures, so the tests for your own signup code use the real response shape.

  • Spot-check a support or sales export

    Before a bulk reply or sequence, ask Codex to classify the sender domains with lookup_email and report how many are disposable, free webmail or company addresses.

MCP or API? Both, for different jobs

MCP server

The agent itself checks addresses while it works

Cleaning a list in chat, triaging senders, testing addresses while it writes code, answering "is this real?". Connect once with a sign-in; nothing to deploy.

REST API

Your product checks addresses in production

Signup forms, imports, CRM webhooks, jobs. The agent writes the code against /v1/verify and /v1/lookup with a key from the environment; your app never depends on an editor.

Same checks, same account limits either way: every MCP tool call runs through the REST API.

Connect Codex with a sign-in

The client opens a pingutil sign-in in your browser: enter your email, follow the link (a free account is created the first time) and approve access. No API key to copy, and you can disconnect it any time from the dashboard.

Add the server and log in. Codex opens the pingutil sign-in in your browser.

codex mcp add pingutil --url https://pingutil.com/mcp
codex mcp login pingutil

Try it with no account

The public test key pk_test_public works without signing in. Tools answer from lists, rules and DNS, don’t check mailboxes over SMTP, and say so in every result.

Use the setup below with pk_test_public as the key (for example export PINGUTIL_API_KEY=pk_test_public).

Test addresses like invalid@test.pingutil.com return fixed results: API reference, test mode. Sign-in details: MCP OAuth.

Make pingutil the default in Codex

Agents use the tools they have and follow the project’s instructions. Add this to AGENTS.md so every email check goes through the MCP tools and every signup form the agent writes calls the API, instead of a guess.

## Email verification
- To check whether an email address is real, disposable, free webmail or a company, use the pingutil MCP tools (verify_email, verify_emails, lookup_email) when they are available. Do not guess from the address and do not write a regex-only check.
- In application code, call POST https://pingutil.com/v1/verify (mailbox check) or POST https://pingutil.com/v1/lookup (category, disposable, company) with "Authorization: Bearer $PINGUTIL_API_KEY" read from the environment. Never hard-code a live key.
- In tests, CI and examples use the public test key pk_test_public and the test addresses valid@, invalid@, catchall@, full@ and greylisted@test.pingutil.com. Docs: https://pingutil.com/api#test-mode
- Block invalid, allow but flag risky and unknown, and let the signup through if the API is unreachable.

Set it up

  1. 1

    Run codex mcp add pingutil --url https://pingutil.com/mcp, or add an [mcp_servers.pingutil] table with that url to ~/.codex/config.toml (or .codex/config.toml in a trusted project).

  2. 2

    Run codex mcp login pingutil. Codex opens the pingutil sign-in in your browser; sign in (a free account is created the first time) and select Allow access. On a machine with no browser, add --no-browser and paste the redirect URL back.

  3. 3

    For CI, skip the login and use an API key instead: export PINGUTIL_API_KEY and set bearer_token_env_var = "PINGUTIL_API_KEY" in the server table.

  4. 4

    Raise tool_timeout_sec above the 60-second default if you verify batches against slow mail servers.

  5. 5

    Optionally restrict the tools with enabled_tools, for example only lookup_email for a classification-only setup.

  6. 6

    Start Codex, check that the server loads, and ask it to verify or classify addresses with pingutil.

Add pingutil to ~/.codex/config.toml
# Add the server and sign in (recommended)
codex mcp add pingutil --url https://pingutil.com/mcp
codex mcp login pingutil

# Optional settings in ~/.codex/config.toml
cat >> ~/.codex/config.toml <<'EOF'

[mcp_servers.pingutil]
url = "https://pingutil.com/mcp"
tool_timeout_sec = 120                      # default is 60
# enabled_tools = ["lookup_email"]          # optional allow list
# bearer_token_env_var = "PINGUTIL_API_KEY" # CI: use a key instead of login
EOF

What to do with each result

pingutil resultAction in Codex
verify_emails: status validWrite the row to valid.csv for import.
status invalidWrite the row to rejected.csv with the reason (mailbox_not_found, no_mx, disposable_domain).
status risky or unknownWrite the row to review.csv; Codex should not delete catch-all or unreachable addresses on its own.
lookup_email: category free or ispMark the lead as a personal address in the report Codex produces.
tool error 429 quota_exceededHave Codex stop the batch loop and report how many rows are left, instead of retrying.

Limits to plan for

  • Codex gives each tool call 60 seconds by default (tool_timeout_sec). A verify_emails batch waits on its slowest mail servers, so raise the timeout or use smaller batches.
  • With bearer_token_env_var, the key is read from the environment; if the variable is missing in the shell that starts Codex, every call fails with 401. If an older Codex build ignores the url entry or has no mcp login command, update Codex.
  • Calls count against your account limits (Free plan: 300 verifications a day and 3,000 a month, 2,000 lookups a day and 30,000 a month). A login runs on your newest active API key, so it shares that key's limits.

Codex documentation

Codex is a trademark of its owner. This integration uses Codex's documented extension points; it is not an official Codex app.

Common questions

codex mcp login or an API key?
Use codex mcp login on your own machine: there is no key to store, and you can disconnect it from the pingutil dashboard. Use bearer_token_env_var with a key in CI. Avoid http_headers for the key, since it would put the key in config.toml.
Does Codex see my API key?
With login, Codex holds a short-lived token, not your key. With bearer_token_env_var, Codex reads the variable to build the request header; the model works with the tool calls and their results. Keep keys out of project files, since the agent can read the repo.
Which tools will Codex get?
verify_email, verify_emails and lookup_email. Use enabled_tools if you want only some of them available in a project.

Stop bad addresses in Codex today

Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Codex setup will receive.