Skip to main content
Glama

append_batch_emails

Append a chunk of emails (up to 4096) to a batch created by submit_batch with final set to false, so a list can grow past the single-call cap. Use it only for a batch whose intake is still open; to start a batch use submit_batch. It reserves and queues the chunk exactly like submit_batch and runs the check set the batch was submitted with: omit checks on every chunk (naming another set is refused with append_batch_emails.checks_mismatch). Set final to true on the last chunk (an empty emails list is allowed) to close intake; the batch then completes once every job finishes. A final chunk that would leave the batch under 20 distinct valid addresses is refused and the batch stays open. 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": {
      "batch_uuid": "<batch_uuid>",
      "emails": "<emails>"
    },
    "name": "append_batch_emails"
  }
}

Input Schema

NameRequiredDescriptionDefault
finalNoWhether this is the batch's final chunk (defaults to true). Set false to keep intake open for a further append_batch_emails call.
checksNoOptional check wire strings (syntax, mx, smtp, disposable, role, free, catchall). Omit them: the chunk then runs, and is billed for, the check set the batch was submitted with. Naming a different set is refused (append_batch_emails.checks_mismatch); naming the same one is accepted.
emailsYesEmail addresses to verify in this chunk (up to 4096). May be empty to close intake without adding more emails. A final chunk is refused when the batch would close with fewer than batch_min (20) distinct valid addresses; the batch then stays open.
batch_uuidYesPublic batch UUID of an open batch (created by submit_batch with final: false).
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, matching the one used on the original submit_batch call. When present, this chunk 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 streamed caller should pass the same checks on every chunk so the whole batch runs one check set."New value: +"Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall). Omit them: the chunk then runs, and is billed for, the check set the batch was submitted with. Naming a different set is refused (append_batch_emails.checks_mismatch); naming the same one is accepted."
  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. A streamed caller should pass the same checks on every chunk so the whole batch runs one check set."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 streamed caller should pass the same checks on every chunk so the whole batch runs one check set."
    • changedInput schema / properties / emails / description
      Previous value: -"Email addresses to verify in this chunk (up to 4096). May be empty to close intake without adding more emails."New value: +"Email addresses to verify in this chunk (up to 4096). May be empty to close intake without adding more emails. A final chunk is refused when the batch would close with fewer than batch_min (20) distinct valid addresses; the batch then stays open."
  3. First observed

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the reserved/queued cost model, the check-set inheritance rule and the named checks_mismatch refusal, the intake-closing behavior of final=true, the batch completion condition, the minimum-20-distinct-valid-addresses refusal that leaves the batch open, and the required email:verify:bulk scope. This is unusually complete for a mutation tool.

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?

The core action and cap are front-loaded, and nearly every clause carries operational information (errors, scope, closing rules). It is a dense single paragraph with stacked parentheticals, which costs some scannability, but nothing is filler.

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

Completeness4/5

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

For a multi-call lifecycle tool with no annotations and no output schema, the description covers preconditions, error paths, billing inheritance, and completion semantics. The remaining gap is that it never says what a successful append returns (batch state, accepted count, job ids), which matters given there is no output schema.

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

Parameters3/5

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

Schema description coverage is 100%, so all five parameters are already documented, including final, checks, emails, and custom_ids. The description reinforces the checks-omission rule and the empty-emails close-out case, but adds little parameter meaning that the schema does not already contain. Baseline 3 is correct.

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 specific verb and resource (append a chunk of emails to an existing batch) plus the 4096 cap, and explicitly distinguishes itself from submit_batch. An agent can tell exactly what it does and what it is not for without opening the schema.

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 explicit when-to-use ('only for a batch whose intake is still open'), names the alternative ('to start a batch use submit_batch'), and describes the close-out path via final=true. Both the routing decision and the multi-call workflow are spelled out.

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