---
title: "Search Inboxes"
method: GET
path: "/v0/inboxes/search"
tags: ["inboxes"]
---

# Search Inboxes

`GET /v0/inboxes/search`

## Request

- Base URL: `https://api.agentmail.to`
- URL: `https://api.agentmail.to/v0/inboxes/search`
- Auth: HTTP bearer

Searches inboxes in the organization by address or display name, ranked
by relevance. Each word in the query matches the start of a word in the
address or display name, so `sup` matches `support@example.com` but
`port` does not. An exact address match always ranks first. `limit`
cannot exceed 100. A page can be empty and still carry a
`next_page_token`; keep paging until the token is absent.

## Query parameters

- `q` string, required
- `limit` integer: Limit of number of items returned.
- `page_token` string: Page token for pagination.

## Response `200`

Response with status 200

- InboxesSearchInboxesResponse
  - `count` integer, required: Number of items returned.
  - `limit` integer: Limit of number of items returned.
  - `next_page_token` string: Page token for pagination.
  - `inboxes` InboxesInbox[], required: Ordered by relevance, best match first.
    - `pod_id` string, required: ID of pod.
    - `inbox_id` string, required: The ID of the inbox.
    - `email` string, required: Email address of the inbox.
    - `display_name` string: Display name: `Display Name <username@domain.com>`.
    - `client_id` string: Client ID of inbox.
    - `status` 'active' | 'paused': Whether the inbox sends and receives mail. `paused` stops both: sends return `403` with code `inbox_paused`, and incoming mail is not delivered and not bounced, then or on resume. Mail already in the inbox, its drafts, and its API keys are kept. Set `active` to resume.
    - `pause_at` string, date-time: When the inbox pauses itself. Within about five minutes after this time, the inbox becomes paused exactly as if `status` had been set to `paused`, and `pause_at` is cleared. Must be in the future; returned in UTC. A manual pause or resume does not change it.
    - `signature` InboxesInboxSignature: A signature AgentMail adds to every message the inbox sends: send, reply, reply-all, forward, and drafts, including scheduled ones. It goes right after your content, above any quoted or forwarded message. It is not added again when your body already contains it, and it is not added to Visa TAP messages.
      - `text` string, required: Signature for the plain-text part. At most 1,000 characters.
      - `html` string: Signature for the HTML part. At most 4,000 characters, so link images by URL rather than embedding them. When omitted, the HTML part gets `text` with its line breaks.
    - `metadata` InboxesMetadata: Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and string values are each limited to 256 characters. When updating metadata, send a key with a null value to remove that key.
    - `updated_at` string, date-time, required: Time at which inbox was last updated.
    - `created_at` string, date-time, required: Time at which inbox was created.

## Other responses

- `400`: Error response with status 400

## Changes

- **2026-10-29** `a9792efe7bdf`: 1 info
  - added the optional property `inboxes/items/signature` to the response with the `200` status
- **2026-10-28** `074503eed059`: 1 info
  - added the optional property `inboxes/items/pause_at` to the response with the `200` status
- **2026-10-16** `3f5c7830c952`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/inboxes/search/get.md)

---

[API](https://skmtc.dev/agentmail-to/apis/api.md) - [All operations](https://skmtc.dev/agentmail-to/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentmail-to/apis/api/revisions/a9792efe7bdf?raw)