TempMail MCP
TempMail MCP is a Model Context Protocol server that gives AI agents temporary email addresses and lets them receive, inspect, and verify emails — enabling closed-loop email-based registration flows.
Create temporary mailboxes across 6 providers (mail.tm, Guerrilla Mail, 1secmail, Catchmail, MailDrop, mail.cx)
List providers and domains to see available options and email domains
Check received emails with message summaries and full message content
Wait for emails by polling until a matching email arrives (filter by subject/sender, configurable timeout)
Extract verification codes automatically from verification emails in 6 languages
Manage mailboxes within a session: list created mailboxes and delete them
Auto-register API keys for MailDrop and mail.cx via pure HTTP calls — no browser needed
Use free providers without API keys, and optionally persist keys via environment variables
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TempMail MCPCreate a temp email and extract the verification code from the signup email."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TempMail MCP
A Model Context Protocol server that provides temporary email services for AI agents, enabling closed-loop verification of email-based registration flows.
For AI agents: Read the AI Guide for tool-by-tool instructions, decision trees, and workflow patterns.
AI 代理指南: 阅读 中文指南 获取工具使用说明、决策树和工作流模式。
Features
Multi-provider aggregation — 6 temp-mail providers behind one unified interface
No API key required for 4 out of 6 providers (Mail.tm, Guerrilla Mail, 1secmail, Catchmail)
Auto-registration — automatically obtain MailDrop and mail.cx API keys via pure HTTP API calls (no browser needed)
Verification code extraction — automatically extracts OTP/verification codes from incoming emails in 6 languages (English, Chinese, Japanese, Russian, French, German)
Wait-for-email — blocking/long-poll until a matching email arrives
Session management — tracks created mailboxes in-memory for the MCP session
Zero heavy dependencies — no Puppeteer, no Playwright, just Node.js built-in modules
Related MCP server: agent-inbox
Supported Providers
Provider | API Key | Free Tier | Special Features |
Mail.tm | No | 8 QPS | Full REST API, account-based |
Guerrilla Mail | No | Unlimited | Session-based, 60-min expiry, custom username |
1secmail | No | Unlimited | Simplest API, implicit mailbox |
Catchmail | No | 1 req/s | Custom domains via MX records |
MailDrop | Yes (auto-obtainable) | 300 req/day | Claim-based mailboxes, RSA pubkey auth |
Mail.cx | Yes (auto-obtainable) | 500 req/day | Long-poll, SSE push, magic-link auth |
Tip: Use the
auto_registertool to automatically obtain MailDrop and mail.cx API keys — no manual signup needed.
Installation
From npm
npm install -g @bencibro/tempmail-mcpOr use directly with npx (no install needed):
npx @bencibro/tempmail-mcpFrom source
git clone https://github.com/Bencibr/tempmailmcp.git
cd tempmailmcp
npm install
npm run buildConfiguration
Environment Variables
Variable | Required | Description |
| No | API key for MailDrop. Auto-obtainable via |
| No | API token for Mail.cx. Auto-obtainable via |
Claude Desktop / Cursor / MCP Client Config
Option A: Using npx (recommended, no install needed)
Add to your MCP client configuration (e.g. claude_desktop_config.json):
{
"mcpServers": {
"tempmail": {
"command": "npx",
"args": ["-y", "@bencibro/tempmail-mcp"],
"env": {
"MAILDROP_API_KEY": "your-maildrop-api-key",
"MAILCX_API_TOKEN": "your-mailcx-api-token"
}
}
}
}If you only need the free providers (no API keys), simply omit the env block:
{
"mcpServers": {
"tempmail": {
"command": "npx",
"args": ["-y", "@bencibro/tempmail-mcp"]
}
}
}Option B: Global install
npm install -g @bencibro/tempmail-mcpThen use tempmail-mcp as the command:
{
"mcpServers": {
"tempmail": {
"command": "tempmail-mcp",
"env": {
"MAILDROP_API_KEY": "your-maildrop-api-key",
"MAILCX_API_TOKEN": "your-mailcx-api-token"
}
}
}
}Don't have an API key? Use the auto_register tool to automatically obtain a free MailDrop or mail.cx API key — no browser needed, pure HTTP API calls. See Auto-Register below.
Available Tools
list_providers
List all available temporary email providers and their capabilities.
get_domains
Get the list of available email domains for a given provider.
provider (optional, default
"mail.tm"): Provider name.
create_mailbox
Create a new temporary email mailbox.
provider (optional, default
"mail.tm"): Provider name.username (optional): Preferred username (local part).
domain (optional): Preferred domain.
get_messages
Get the list of received emails for a mailbox.
address: The temporary email address.
get_message
Get the full content of a specific email.
address: The temporary email address.
messageId: The message ID (from
get_messages).
wait_for_email
Block until a matching email arrives. Returns the first matching message.
address: The temporary email address.
subjectContains (optional): Filter by subject substring.
fromContains (optional): Filter by sender substring.
timeoutMs (optional, default
60000): Timeout in ms.pollIntervalMs (optional, default
3000): Poll interval in ms.
get_verification_code
Wait for a verification email and automatically extract the verification code. Supports verification emails in 6 languages: English, Chinese (简体/繁体), Japanese, Russian, French, and German.
Uses a multi-strategy extraction algorithm:
Contextual matching — looks for language-specific keywords (e.g.
code,验证码,認証,код,vérification,Bestätigung) near a code-like tokenStandalone digit codes — falls back to pure-digit codes (6-digit prioritized), filtering out years and false positives
Alphanumeric codes — last-resort fallback to uppercase alphanumeric tokens, filtering out pure-letter words
address: The temporary email address.
subjectContains (optional): Filter (e.g.
"verification","confirm","code","验证").fromContains (optional): Filter by sender.
timeoutMs (optional, default
60000): Timeout in ms.
list_mailboxes
List all temporary mailboxes created in this session.
delete_mailbox
Delete a temporary mailbox and all its messages.
address: The temporary email address.
auto_register
Automatically register an account and obtain an API key/token for a provider. Pure HTTP API — no browser, no Puppeteer.
maildrop
Uses RSA key generation + HTTP API:
Generates an RSA 2048 keypair (Node.js
cryptomodule)POST /api/register.phpwith the public keySigns
timestamp-usernameto create a passcodePOST /api/login.phpto authenticatePOST /api/account/keys.phpto create an API key (md_...)
mail.cx
Uses magic-link sign-in flow:
Creates a temp mailbox via mail.tm (no API key needed)
POST /v1/auth/magic-link/requestto send a magic link to the temp emailPolls mail.tm for the magic link email
POST /v1/auth/magic-link/verifywith the token — returns the API token directly (tm_live_...)
Parameters:
provider (required):
"maildrop"or"mail.cx"tokenName (optional, default
"tempmail-mcp"): Name for the token (mail.cx only).username (optional): Username for the account (maildrop only).
timeoutMs (optional, default
120000): Overall timeout in milliseconds.
Returns the API key/token and automatically registers the provider in the current session. To make it permanent, set the corresponding environment variable (MAILDROP_API_KEY or MAILCX_API_TOKEN).
Usage Examples
Auto-Register to Get a Free API Key
MailDrop (fast, ~2 seconds):
1. auto_register (provider: "maildrop")
→ { apiKey: "md_...", email: "tmp_xxx@maildrop.cc", ... }
2. [Set MAILDROP_API_KEY=md_... in your MCP config]
3. list_providers
→ Now includes "maildrop" in the provider list!mail.cx (~15-30 seconds, waits for email):
1. auto_register (provider: "mail.cx")
→ { apiKey: "tm_live_...", email: "abc@emalupe.com", ... }
2. [Set MAILCX_API_TOKEN=tm_live_... in your MCP config]
3. list_providers
→ Now includes "mail.cx" in the provider list!Both providers are automatically available in the current session after registration — no restart needed.
Typical Registration Verification Flow
1. create_mailbox (provider: "mail.tm")
→ { address: "abc123@somedomain.com", ... }
2. [Register on target website using the temp email address]
3. get_verification_code (address: "abc123@somedomain.com", subjectContains: "verification")
→ { code: "829451", from: "noreply@example.com", subject: "Your verification code", ... }
4. [Enter the code on the target website to complete registration]
5. delete_mailbox (address: "abc123@somedomain.com")Manual Email Checking
1. create_mailbox (provider: "guerrillamail", username: "mytest")
→ { address: "mytest@guerrillamailblock.com", ... }
2. get_messages (address: "mytest@guerrillamailblock.com")
→ { count: 2, messages: [{ id: "1", from: "...", subject: "..." }, ...] }
3. get_message (address: "mytest@guerrillamailblock.com", messageId: "1")
→ { id: "1", from: "...", subject: "...", bodyText: "...", bodyHtml: "..." }Development
# Install dependencies
npm install
# Build
npm run build
# Run locally
node dist/index.js
# Watch mode
npm run dev
# Test auto-registration
node test-auto-register-api.mjs maildrop # Test MailDrop only
node test-auto-register-api.mjs mailcx # Test mail.cx only
node test-auto-register-api.mjs all # Test bothArchitecture
┌──────────────────────────────────────────────────────┐
│ MCP Client (Claude) │
│ │ │
│ stdio / Streamable HTTP │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ TempMail MCP Server │ │
│ │ │ │
│ │ ┌─── Tools ───────┐ │ │
│ │ │ create_mailbox │ │ │
│ │ │ get_messages │ │ │
│ │ │ wait_for_email │ │ │
│ │ │ get_verification │ │ │
│ │ │ auto_register │ │ │
│ │ │ ... │ │ │
│ │ └──────────────────┘ │ │
│ └──────────┬───────────┘ │
│ │ │
│ ┌──────────▼───────────┐ │
│ │ Provider Manager │ │
│ │ (adapter pattern) │ │
│ └──────────┬───────────┘ │
│ │ │
│ ┌────────┬────────┼────────┬──────────┐ │
│ ▼ ▼ ▼ ▼ ▼ │
│ Mail.tm Guerrilla 1secmail Catchmail MailDrop │
│ Mail Mail.cx │
└──────────────────────────────────────────────────────┘
Auto-Register Flow (pure HTTP, no browser):
┌───────────────┐ ┌───────────────┐
│ MailDrop │ │ mail.cx │
│ │ │ │
│ RSA keygen │ │ mail.tm temp │
│ ↓ │ │ mailbox │
│ POST register│ │ ↓ │
│ ↓ │ │ POST magic │
│ RSA sign │ │ link request │
│ ↓ │ │ ↓ │
│ POST login │ │ Poll for email│
│ ↓ │ │ ↓ │
│ POST create │ │ POST verify │
│ API key │ │ → API token │
│ → md_... │ │ → tm_live_... │
└───────────────┘ └───────────────┘License
MIT
Available Tools
10 toolsauto_registerA
Automatically register an account and obtain an API key/token for a provider. Uses pure HTTP API calls — no browser automation needed. Supported providers: 'maildrop' and 'mail.cx'. The resulting API key/token is automatically registered in the current session and also returned for the user to save.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | Yes | The provider to auto-register. 'maildrop': uses RSA key generation + HTTP API to register and obtain an md_ API key. 'mail.cx': uses magic-link sign-in flow (creates a temp mailbox via mail.tm, receives the magic link, follows it, and creates an API token). | |
| username | No | Username for the account (maildrop only). If omitted, a random one is generated. | |
| timeoutMs | No | Overall timeout in milliseconds. Default: 120000 (2 minutes). | |
| tokenName | No | Name for the created API token (mail.cx only). Default: 'tempmail-mcp'. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that an account is created externally, that the resulting key/token is auto-registered in the current session, and that it is returned for the user to save. It does not detail failure behavior, but the core side effects are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. It front-loads the main purpose, then adds the key behavioral detail about HTTP-only calls and session registration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, supported providers, and outcome. However, there is no output schema and the description only vaguely says the key/token is 'returned' without describing the return shape or error/timeout behavior, which leaves a meaningful gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented there. The description adds minimal extra semantic value beyond naming supported providers and the overall outcome, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (register an account), the resource (a provider account), the output (API key/token), and the method (pure HTTP API calls). This distinguishes it from sibling tools that create mailboxes or retrieve messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for automatic provider registration without browser automation, and it lists the supported providers. It does not explicitly name alternative tools or exclude cases, but the use case is well implied by the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_mailboxB
Create a new temporary email mailbox. Returns the email address and account details.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Preferred domain. If omitted, a random one is chosen from the provider's available domains. | |
| provider | No | Provider name (e.g. 'mail.tm', 'guerrillamail', '1secmail', 'catchmail', 'maildrop', 'mail.cx'). Defaults to 'mail.tm'. | |
| username | No | Preferred username (local part of the email). If omitted, a random one is generated. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full disclosure burden. It does disclose the mutation nature ('Create'), the ephemeral lifecycle ('temporary'), and the return value, but it omits failure modes (e.g., unavailable username/domain), idempotency, and any side effects or provider resource consumption that would help an agent anticipate outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler; the primary action is front-loaded and the second sentence about the return value earns its place. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The input schema is fully self-documenting and all parameters are optional, but annotations and output schema are absent, leaving the description as the sole behavior and return disclosure. It covers the basics but lacks output shape detail, failure behavior, and sibling routing, which are meaningful gaps for a resource-creating tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: domain, provider, and username each have descriptions including defaults and behavior when omitted. The tool description adds no parameter-level meaning, so the baseline of 3 applies per the high-coverage rule.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Create') and resource ('temporary email mailbox') and states the return value ('email address and account details'), making the core purpose clear. It does not explicitly differentiate itself from siblings such as auto_register or list_mailboxes, so it misses the sibling-distinguishing bar for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives. The description never mentions conditions like 'use this when you need a fresh disposable address' and names no sibling or exclusion, leaving the agent to infer selection from the tool name and the word 'temporary' alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_mailboxA
Delete a temporary mailbox and all its messages (if supported by the provider).
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The temporary email address to delete. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the destructive effect (deletes the mailbox and all its messages) and adds the provider-support caveat. It doesn't mention irreversibility, permissions, or what happens when a provider doesn't support it, but it covers the core risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the core action first, followed by the scope and a qualifying caveat. Every word earns its place; no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive operation, the description covers what is deleted, the parameter, and a conditional limitation. Without an output schema or annotations, it might have noted provider-detection or error behavior, but the essential guidance for a correct call is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter, address, is already described as 'The temporary email address to delete.' The description adds no further parameter detail, so it meets the baseline but doesn't enrich beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Delete') and resource ('temporary mailbox') and adds the scope of the action (messages). It is clearly distinct from all siblings, none of which are deletions, so an agent can select it unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case apparent: clean up a temporary mailbox and its messages. It doesn't explicitly say 'use when done with the mailbox' or list alternatives, but no sibling provides a deletion operation, so the when-to-use context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_domainsB
Get the list of available email domains for a given provider.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | No | Provider name. Defaults to 'mail.tm'. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It communicates a read-only 'Get' operation, but it does not disclose whether the provider parameter is optional, what the response format looks like, whether domains are filtered, or whether any network-dependent behavior or failure modes exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no superfluous wording. Key information—action, resource, and scope—is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list-retrieval tool with one optional parameter and no output schema, the description conveys the essential behavior. It could be slightly stronger by noting the default provider or the expected return shape, but these are relatively minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and already documents the provider parameter and its default value. The description's phrase 'for a given provider' loosely maps to the parameter but adds no semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get'), a clear resource ('list of available email domains'), and a scope ('for a given provider'). It is easily distinguishable from sibling tools like list_providers, which returns providers rather than domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or related steps such as choosing a provider first or using the returned domain with create_mailbox. Usage context is only implied by the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_messageA
Get the full content of a specific email message (body text, HTML, attachments metadata).
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The temporary email address that received the message. | |
| messageId | Yes | The message ID (from 'get_messages' result). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. 'Get' correctly signals a non-mutating read operation, and the description specifies the return payload (body text, HTML, attachments metadata). It does not disclose error behavior, rate limits, or authorization needs, but for a simple retrieve-by-ID tool this is a limited gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 16-word sentence that front-loads the action and resource, then lists the return components. Every word earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two required parameters, no nested objects, and no output schema, the description adequately conveys what will be returned. It does not cover error cases or explicitly state that messageId comes from get_messages, but the schema addresses the latter. Slightly more context in the description would be beneficial, but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both address and messageId already have clear descriptions in the input schema. The tool description itself adds no parameter-level detail beyond the resource being retrieved. Baseline 3 applies because the schema does the heavy lifting for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get the full content of a specific email message', a specific verb and resource, and enumerates the return components: body text, HTML, attachments metadata. The word 'specific' and 'full content' clearly distinguish it from the sibling get_messages tool without needing to reference it directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving a single message after it has been identified, but it does not explicitly state when to prefer it over get_messages or wait_for_email. It does not mention that a messageId must first be obtained from get_messages, though the input schema does provide this context. The usage guidance is adequate but relies on inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_messagesB
Get the list of received emails for a temporary mailbox. Returns message summaries (ID, from, subject, date).
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The temporary email address to check for messages. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. It communicates a read-only list operation and states the return fields, which is meaningful. However, it does not disclose side effects, pagination, empty-result behavior, or how it handles invalid addresses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with the action and resource front-loaded, followed by the return format. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool with a clear output description, the definition is mostly complete. It lacks explicit sibling differentiation and minor edge-behavior details, but those are not critical for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter address is already fully described in the schema, and the tool description adds no extra meaning beyond implying it identifies the mailbox to check. Baseline 3 is appropriate because schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear operation: 'Get the list of received emails' for a temporary mailbox, and specifies the output content (message summaries with ID, from, subject, date). It is distinguishable from the sibling get_message by the word 'list' and 'summaries', though it does not explicitly name or contrast that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use get_messages versus siblings like get_message, wait_for_email, or get_verification_code. The only usage signal is implicit: this tool returns summaries rather than full message details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_verification_codeA
Wait for a verification/confirmation email and automatically extract the verification code from it. Returns the extracted code. This is a convenience tool that combines 'wait_for_email' + code extraction.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The temporary email address to check. | |
| timeoutMs | No | Timeout in milliseconds. Default 60000 (60s). | |
| fromContains | No | Filter: only look at emails from senders containing this substring. | |
| subjectContains | No | Filter: only look at emails whose subject contains this (e.g. 'verification', 'confirm', 'code'). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It explains the core behavior of waiting and extracting, but it does not mention timeout behavior, what happens if no verification code is found, how filters are applied, or any side effects like polling or cleanup. This is a meaningful gap for a tool that blocks until an email arrives.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler. The primary action and result are front-loaded, and the relationship to wait_for_email is explained in one clause. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description tells the agent what the tool returns (extracted code) and its purpose, but it leaves out failure behavior and timeout semantics despite no output schema existing. An agent cannot anticipate errors like a missing code or expired timeout, which are common for this kind of tool. The high schema coverage covers parameters but not behavioral edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline applies. The schema already explains address, timeoutMs, fromContains, and subjectContains. The description adds context that the email is a verification/confirmation email and that extraction targets the code, which slightly enriches why those filters matter, but it does not add detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: wait for a verification/confirmation email and extract the code. It also explicitly names its relationship to the sibling 'wait_for_email' by calling itself a convenience tool that combines wait_for_email with code extraction, clearly distinguishing it from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use this tool: whenever a verification code is needed from an email, as it wraps wait_for_email plus extraction. It implies this is preferable for that use case, but it does not explicitly state when not to use it (e.g., if raw email content is needed, use get_message).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_mailboxesA
List all temporary mailboxes created in this session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add value by clarifying the session-scoped nature of the results and implicitly signaling a read-only operation via 'List'. However, it does not disclose return format, what fields each mailbox entry contains, or how 'session' is defined — gaps that matter for downstream chaining to tools like get_messages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 9-word sentence that front-loads the verb and resource. Every word earns its place, with no filler, abbreviations, or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no nested objects, no output schema), the description captures the essential behavior completely. Mentioning the return shape (e.g., addresses or IDs) would be helpful for tool chaining but is not critical for such a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the baseline for 0-parameter tools is 4. The description correctly implies the tool takes no input, and there is nothing further it needs to explain about arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a specific resource ('temporary mailboxes'), and a scope qualifier ('created in this session'). It is easily distinguishable from sibling tools: list_providers targets providers, create_mailbox/delete_mailbox are mutations, and get_messages/get_message target messages rather than mailboxes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'created in this session' qualifier provides clear usage context — the agent learns that only session-scoped mailboxes are returned and that persistent or previously-created mailboxes are excluded. However, it does not explicitly name alternatives or state when-not-to-use in the way a 5 would require.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_providersA
List all available temporary email providers and their capabilities.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. The word 'List' implies a read-only operation and 'all available' signals the complete result set, but the description does not disclose the return format, how capabilities are represented, or any pagination or performance characteristics. It is adequate for a simple listing tool, but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word adds meaning: the action, the resource, the scope, and the included capabilities are all communicated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema listing tool, this description is largely complete: it states what is listed and the kind of information returned. It could be slightly stronger by naming example capabilities, but the lack of complexity and parameters makes the current description sufficient for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to explain beyond the empty schema. The baseline of 4 applies because there is nothing for the description to add about parameters, and the description appropriately avoids inventing any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('all available temporary email providers') and adds the key detail that capabilities are included. This clearly distinguishes it from sibling tools like get_domains or list_mailboxes, which focus on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an agent needs to enumerate available providers before creating a mailbox or choosing a provider, but it does not explicitly state when to use this tool versus alternatives. There are no exclusions or named sibling tools for comparison, so the usage guidance remains implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
wait_for_emailA
Block (poll/long-poll) until a matching email arrives in the mailbox. Returns the first matching message. Useful for waiting for verification emails during signups.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The temporary email address to wait for emails on. | |
| timeoutMs | No | Timeout in milliseconds. Default 60000 (60s). | |
| fromContains | No | Only return emails whose sender (from) contains this substring. | |
| pollIntervalMs | No | Poll interval in milliseconds. Default 3000 (3s). | |
| subjectContains | No | Only return emails whose subject contains this substring. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses blocking/polling behavior and that it returns the first matching message. However, with no annotations provided, it omits important behavioral details such as what happens on timeout and whether the returned email is consumed or remains in the mailbox.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the mechanism front-loaded, followed by the return behavior and a concrete use case. There is no filler; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for calling the tool given full schema coverage and a clear purpose. However, since there is no output schema and no annotations, the timeout/failure behavior and the structure of the returned message are left unspecified, creating a meaningful gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters are fully documented in the input schema (100% coverage), so the baseline is 3. The description adds no parameter-specific meaning beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Block'), a resource ('matching email' in the mailbox), and the return value ('first matching message'). This clearly distinguishes it from sibling retrieval tools like get_messages, which list existing messages rather than waiting for a new one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'Useful for waiting for verification emails during signups.' It implies when to use the tool but does not explicitly mention alternatives or when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Each tool maps to a distinct action: provider discovery, mailbox lifecycle, message listing/detail, blocking wait, and code extraction. Even wait_for_email and get_verification_code are clearly differentiated by their return value and purpose.
All tool names use consistent snake_case verb_noun patterns like list_providers, create_mailbox, get_messages, and delete_mailbox. Names are predictable and convey the action clearly.
Ten tools is well-scoped for a temporary email server. Each tool covers a necessary part of the workflow without unnecessary duplication or bloat.
The domain of temporary email receiving is fully covered: provider discovery, mailbox creation/deletion/listing, message retrieval, waiting for emails, and verification code extraction. The auto_register tool nicely completes the provider setup flow.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Task-scoped email inboxes for AI agents: read mail, extract verification codes, and reply.
Real email inboxes for AI agents: create inboxes, catch verification codes, extract OTPs, reply.
Disposable email inboxes for AI agents — read messages and verification codes.
Disposable inboxes for AI agents: create, wait for delivery, and extract email content or links.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to create disposable email inboxes and automatically extract OTPs, magic links, and verification codes from incoming emails.24MIT
- AlicenseAqualityFmaintenanceEnables AI agents to create temporary email addresses, receive confirmation emails, and extract verification links, automating sign-up and email verification workflows without manual intervention.63261MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to generate temporary email addresses, receive emails, and automatically extract OTP codes and links from incoming messages for automation and testing workflows.MIT
- AlicenseAqualityAmaintenanceProvides disposable email inboxes for AI agents to automatically receive and extract OTPs and magic links, enabling seamless email verification during autonomous workflows.386MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Bencibr/tempmailmcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server