Skip to main content
Glama

submit_batch

Submit a list of emails (up to 4096 per call) for bulk verification and return a batch_uuid. Use it for 20 or more addresses; for fewer use verify_email, since a batch closed by this call needs at least 20 distinct valid addresses. Billed per unique valid address, and governed by the plan's batch_max (see get_pricing). The optional checks list picks which checks run (syntax, mx, smtp, disposable, role, free, catchall). Each check is billed at its own price, returned by get_pricing. Omitting checks runs every check your plan allows, which is the most reliable answer and costs the most tokens; naming fewer costs less. A check outside your plan is refused. Processing is asynchronous: follow progress with get_batch and read per-email results with get_batch_results. Set final to false to keep intake open and feed more chunks with append_batch_emails. Requires the email:verify:bulk scope.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "emails": "<emails>"
    },
    "name": "submit_batch"
  }
}

Input Schema

NameRequiredDescriptionDefault
finalNoWhether this is the batch's only or final chunk (defaults to true). Set false to keep intake open, then feed further chunks with append_batch_emails.
checksNoOptional check wire strings (syntax, mx, smtp, disposable, role, free, catchall). Each check is billed at its own price (see get_pricing). Omit to run every check your plan allows, the most reliable answer and the most tokens; naming fewer costs less. A check outside your plan is refused.
emailsYesEmail addresses to verify (up to 4096). Billed per unique valid address and governed by the caller's plan batch_max (see get_pricing). A batch closed by this call (final: true, the default) needs at least batch_min (20) distinct valid addresses; verify fewer with verify_email.
custom_idsNoOptional per-email client references, index-aligned 1:1 with emails. Echoed back verbatim in get_batch_results so you can map each result to your input row. Do not put the email address or any PII here, use your own row identifier (e.g. a CRM id).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • removedInput schema / properties / api_key
      Removed value: -{
      -  "description": "Optional pm_live_ (or pm_test_) API key. When present, this batch is billed and scoped against that key's own account instead of the caller's session account, and the key must carry the email:verify:bulk scope. Omit to use the caller's own session account.",
      -  "type": [
      -    "string",
      -    "null"
      -  ]
      -}
    • changedInput schema / properties / checks / description
      Previous value: -"Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); defaults to every check the caller's plan allows, smtp included. A check outside the plan is refused."New value: +"Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall). Each check is billed at its own price (see get_pricing). Omit to run every check your plan allows, the most reliable answer and the most tokens; naming fewer costs less. A check outside your plan is refused."
  2. Changed2 schema fields changed
    • changedInput schema / properties / checks / description
      Previous value: -"Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); defaults to the plan's allowed checks minus smtp. SMTP is opt-in and still subject to plan gating."New value: +"Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); defaults to every check the caller's plan allows, smtp included. A check outside the plan is refused."
    • changedInput schema / properties / emails / description
      Previous value: -"Email addresses to verify (up to 4096). Billed per unique valid address and governed by the caller's plan batch_max (see get_pricing)."New value: +"Email addresses to verify (up to 4096). Billed per unique valid address and governed by the caller's plan batch_max (see get_pricing). A batch closed by this call (final: true, the default) needs at least batch_min (20) distinct valid addresses; verify fewer with verify_email."
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden and does: billing per unique valid address, plan batch_max, per-check pricing, plan-restricted checks refused outright, default checks running everything your plan allows, asynchronous processing, and that final=false keeps intake open for append_batch_emails.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool does and its threshold before lifecycle, billing, and check semantics. It is dense with no filler sentences, but the checks and final behavior are restated almost verbatim from the schema descriptions, which is mild redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter, async, plan-gated, billed ingestion tool with no output schema, it covers everything an agent needs: the returned batch_uuid, how to poll progress, how to chunk intake, the billing model, the plan limits, and the required auth scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so a baseline 3 would hold, but the description adds real meaning: the cost/coverage tradeoff for omitting checks, the plan refusal rule, and the operational consequence of final=false. It does not add much beyond the schema's PII warning and 1:1 alignment note on custom_ids, so it stops short of a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource — submit a list of emails for bulk verification — and states the return value (batch_uuid). It is clearly distinguished from verify_email (small lists), get_batch (progress), get_batch_results (per-email output), and append_batch_emails (chunked intake).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit threshold: use this for 20+ addresses, use verify_email for fewer, justified by the batch_min requirement on a closed batch. It also names the follow-up tools for each lifecycle stage (get_batch, get_batch_results, append_batch_emails) and the prerequisite scope email:verify:bulk.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources