> ## Documentation Index > Fetch the complete documentation index at: https://docs.mermail.app/llms.txt > Use this file to discover all available pages before exploring further. # Search emails > **Plans:** `Free` · `Developer` · `Enterprise` Full-text / field search across mailbox messages. Returns `{ emails, totalCount }`. **API credits:** 1 (read). ## OpenAPI ````yaml /openapi/openapi.json get /api/v1/mailboxes/{mailboxId}/search openapi: 3.1.0 info: title: Mermail API version: 1.0.0 description: > Programmatic Mermail API for scripts, agents, and integrations. ## Authentication Authorize with an API key from **Settings → API Keys**: ``` x-api-key: sk-proj-… ``` ## Plans Each endpoint page shows plan badges (**Public**, **All plans**, or **Developer+**). Free can call the core catalog; Developer-gated paths need Developer or Enterprise. ## Try it Every endpoint page includes an interactive playground. Click **Try it**, paste your API key into the `x-api-key` field, fill path/query/body fields (prefilled from examples), and send a live request to `https://console.mermail.app`. You can also copy the generated cURL / JavaScript / Python snippet. ## Credits | Class | Cost | | --- | ---: | | read | 1 | | write | 2 | | email_send | 5 | | provision | 10 | | ai_light | 15 | | ai_heavy | 25 | contact: name: Mermail email: contact@mermail.app url: https://mermail.app servers: - url: https://console.mermail.app description: Production security: - apiKeyAuth: [] tags: - name: Public description: No authentication - name: Usage description: Credits and email quotas - name: Workspaces description: Workspaces, members, storage - name: Domains description: Custom email domains (Developer+) - name: Mailboxes description: Agent inboxes - name: Emails description: Send, list, search, folders - name: AI agent description: Mailbox agent chat - name: Task triage description: Task triagers (all plans) - name: RAG description: Knowledge documents and recall - name: Integrations description: Composio, Telegram, push - name: Affiliate description: Affiliate program paths: /api/v1/mailboxes/{mailboxId}/search: get: tags: - Emails summary: Search emails description: >- **Plans:** `Free` · `Developer` · `Enterprise` Full-text / field search across mailbox messages. Returns `{ emails, totalCount }`. **API credits:** 1 (read). parameters: - name: mailboxId in: path required: true description: Mailbox public_id (UUID), hosted alias id, or current email schema: type: string example: aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee - name: query in: query required: false description: Free-text query across subject, body, sender, recipients schema: type: string example: order shipping - name: folder in: query required: false description: Folder id filter schema: type: string - name: from in: query required: false description: Sender contains schema: type: string - name: to in: query required: false description: Recipient contains schema: type: string - name: subject in: query required: false description: Subject contains schema: type: string - name: date_start in: query required: false description: ISO start date schema: type: string example: '2026-07-01T00:00:00.000Z' - name: date_end in: query required: false description: ISO end date schema: type: string - name: is_read in: query required: false description: true/1 for read only schema: type: string - name: is_starred in: query required: false description: true/1 for starred only schema: type: string - name: category in: query required: false description: Category filter schema: type: string - name: has_attachment in: query required: false description: Truthy to require attachments schema: type: string - name: page in: query required: false description: page schema: type: integer example: 1 - name: limit in: query required: false description: limit schema: type: integer example: 25 responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/EmailListResponse' example: emails: - id: msg_7f3a2c1b subject: Order question sender: alice@example.com recipient: support@mail.acme.com cc: null bcc: null date: '2026-07-14T09:00:00.000Z' read: false starred: false is_urgent: false category: customer_support body: Hi, where is my order? folder_id: INBOX folder_name: Inbox thread_id: thr_9aabb snippet: Hi, where is my order? scan_status: null attachments: [] totalCount: 42 '401': description: Missing, invalid, expired, or revoked API key / token content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized '402': description: API credits exhausted for this workspace period content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid request '403': description: Forbidden — plan gate, wrong workspace, or missing role content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Forbidden '429': description: Rate limit exceeded (workspace RPM or email send limits) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Too many requests headers: Retry-After: schema: type: integer description: Seconds until the rate limit window resets security: - apiKeyAuth: [] components: schemas: EmailListResponse: type: object properties: emails: type: array items: $ref: '#/components/schemas/Email' totalCount: type: integer Error: type: object required: - error properties: error: type: string example: Unauthorized code: type: string Email: type: object properties: id: type: string subject: type: string sender: type: string recipient: type: string date: type: string format: date-time read: type: boolean starred: type: boolean category: type: string folder_id: type: string thread_id: type: string snippet: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key (`sk-proj-…`) from Settings → API Keys. Required for sold API calls outside the Mermail console. ````