Skip to content

// ai agents and mcp

Via API

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.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and export it as PINGUTIL_API_KEY in the shell that starts Codex.

  2. 2

    Add an [mcp_servers.pingutil] table to ~/.codex/config.toml (or .codex/config.toml in a trusted project) with url = "https://pingutil.com/mcp" and bearer_token_env_var = "PINGUTIL_API_KEY". Alternatively run codex mcp add pingutil --url https://pingutil.com/mcp and add the bearer_token_env_var line by hand.

  3. 3

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

  4. 4

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

  5. 5

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

Add pingutil to ~/.codex/config.toml
# In ~/.zshrc or ~/.bashrc
export PINGUTIL_API_KEY="pk_live_..."   # from https://pingutil.com/dashboard

# Append the server to Codex's user config (TOML)
cat >> ~/.codex/config.toml <<'EOF'

[mcp_servers.pingutil]
url = "https://pingutil.com/mcp"
bearer_token_env_var = "PINGUTIL_API_KEY"   # sent as Authorization: Bearer <value>
tool_timeout_sec = 120                      # default is 60
# enabled_tools = ["lookup_email"]          # optional allow list
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.
  • The key is read from the environment named in bearer_token_env_var; if the variable is missing in the shell that starts Codex, every call fails with 401. The current Codex docs list no experimental flag for HTTP servers; if an older build ignores the url entry, update Codex.
  • Calls count against the key's account limits (Free plan: 300 verifications a day and 3,000 a month, 2,000 lookups a day and 30,000 a month). The server uses API-key auth only, no OAuth.

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

bearer_token_env_var or http_headers?
bearer_token_env_var. It names an environment variable and Codex sends its value as Authorization: Bearer, so the key is not stored in config.toml. http_headers holds static values and would put the key in the file.
Does Codex see my API key?
Codex reads the variable to build the request header; the model works with the tool calls and their results. Keep the key 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.