# Mermail Mailbox Search

> Mermail Mailbox Search is a paid API for AI agents from console.mermail.app, paid per call via x402, price unknown, status unknown (last checked 2026-10-11).

Searches emails in an AI agent's Mermail mailbox by sender, recipient, subject, date range, folder, or semantic query

## Facts

- Endpoint: GET https://console.mermail.app/api/agent/v1/mailboxes/%7BmailboxId%7D/search?utm_source=zero.xyz
- Price: price unknown
- Payment: x402
- Status: unknown
- Last checked: 2026-10-11
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/mermail-mailbox-search-c16e36c2
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_JSJGeStYu8wHWIx7T98VA

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability mermail-mailbox-search-c16e36c2
```

Example prompt: Search my Mermail agent inbox for emails from sales@acme.com received after January 1st 2025, limit to 20 results, and only show clean (not flagged) messages.

## When to prefer this

Use this endpoint when an AI agent needs to search or filter its Mermail inbox for specific emails by sender, subject, date range, folder, or keyword query. Prefer this over listing all emails when you need targeted retrieval. Ideal for agents that need to find sales leads, customer support messages, verification codes, or any structured workflow triggered by incoming email content.

## Known failure modes

- Invalid or missing mailboxId returns 404 not found
- date_start or date_end not in valid ISO 8601 datetime format returns 400 bad request
- limit out of range (below 1 or above 100) returns 400 validation error
- Unauthorized access to mailbox returns 401 or 403
- No matching emails returns empty array with totalCount 0
- require_scan_status filter with no matching emails returns empty result set

## How this service works

An inbox and wallet for your AI agent. Find and nurture sales leads, resolve customer support, and handle online purchases with controlled payments.

## Output

Returns a JSON object containing a list of matching emails (each with id, subject, sender, recipient, date, read status, snippet, body if requested, thread_id, scan_status, and content_omitted flag) plus a totalCount of matching messages. Results respect filters for sender, recipient, subject, folder, date range, query string, and scan status.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "headers": {
     "type": "object",
     "additionalProperties": {
      "type": "string"
     }
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "to": {
       "type": "string"
      },
      "from": {
       "type": "string"
      },
      "limit": {
       "type": "integer",
       "maximum": 100,
       "minimum": 1
      },
      "query": {
       "type": "string"
      },
      "folder": {
       "type": "string"
      },
      "subject": {
       "type": "string"
      },
      "date_end": {
       "type": "string",
       "format": "date-time"
      },
      "date_start": {
       "type": "string",
       "format": "date-time"
      },
      "metadata_only": {
       "type": "boolean"
      },
      "agent_safe_content": {
       "type": "boolean"
      },
      "require_scan_status": {
       "enum": [
        "clean",
        "flagged",
        "skipped"
       ],
       "type": "string"
      }
     },
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "emails",
      "totalCount"
     ],
     "properties": {
      "emails": {
       "type": "array",
       "items": {
        "type": "object",
        "required": [
         "id",
         "subject",
         "sender",
         "recipient",
         "date"
        ],
        "properties": {
         "id": {
          "type": "string"
         },
         "body": {
          "type": "string"
         },
         "date": {
          "type": "string",
          "format": "date-time"
         },
         "read": {
          "type": "boolean"
         },
         "sender": {
          "type": "string"
         },
         "snippet": {
          "type": "string"
         },
         "subject": {
          "type": "string"
         },
         "recipient": {
          "type": "string"
         },
         "thread_id": {
          "type": [
          
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "emails": [
   {
    "id": "email_1",
    "date": "2026-09-20T00:00:00.000Z",
    "sender": "noreply@example.com",
    "subject": "Verification code",
    "recipient": "agent@mermail.app",
    "scan_status": "clean"
   }
  ],
  "totalCount": 1
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/mermail-mailbox-search-c16e36c2/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from console.mermail.app](https://www.zero.xyz/host/console.mermail.app/llms.txt)