{"uid":"cap_JSJGeStYu8wHWIx7T98VA","slug":"mermail-mailbox-search-c16e36c2","name":"Mermail Mailbox Search","description":"An inbox and wallet for your AI agent. Find and nurture sales leads, resolve customer support, and handle online purchases with controlled payments.","url":"https://console.mermail.app/api/agent/v1/mailboxes/%7BmailboxId%7D/search?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"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":["string","null"]},"scan_status":{"enum":["clean","flagged","skipped",null],"type":["string","null"]},"content_omitted":{"type":"boolean"}},"additionalProperties":true}},"totalCount":{"type":"integer","minimum":0}},"additionalProperties":true}}}}},"responseSchema":{"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}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"unprobed","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"unknown","summary":"price unknown","primary":{"kind":"unknown","protocol":"x402","network":"base","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"unknown","protocol":"x402","network":"base","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_57lD8xWWDkgutu5Umtxct","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0","costPer":"request","priority":0,"asset":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Searches emails in an AI agent's Mermail mailbox by sender, recipient, subject, date range, folder, or semantic query","exampleAgentPrompt":"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.","exampleUseCases":[{"title":"Sales lead triage from inbox","prompt":"Check my Mermail mailbox for any emails mentioning 'pricing' or 'demo request' that came in this week — show me up to 25 results with clean scan status so I can follow up on leads."},{"title":"Customer support queue review","prompt":"Search my agent's Mermail inbox for all emails from customers asking about 'refund' or 'broken order' since October 1st, limited to 50 results, so I can start resolving support tickets."},{"title":"Verification code retrieval","prompt":"Find the most recent email in my Mermail mailbox with 'verification code' or 'OTP' in the subject, sent after 3pm today, so my agent can complete the sign-up flow."}],"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-11T06:49:20.008Z","isFirstParty":false,"canonicalSlug":"mermail-mailbox-search-c16e36c2"}