# Search your mail and files

`GET https://api.mailmasker.org/api/v1/search`

Find email and files by words, people, dates or type, in one search.

- Who can use it: Any signed-in account
- Area: Search
- Answers 200 OK when it works
- Page: https://developer.mailmasker.org/search

Mail matches on its subject and text, files on their name and text; with `q` the best matches come first, otherwise the newest. Results come in two lists, `mail` and `drive`, each up to `limit` long. Files someone has shared with you are included, with their address in `shared_by`. `filters` shows how your request was read, and `indexed` is false until something of yours has been indexed.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `q` | query | no | Words to find. Put a phrase in double quotes, use OR between words for either one, and a minus before a word to leave it out. | `invoice` |
| `person` | query | no | A name or address. Finds mail from or to them, and photos they are tagged in. |  |
| `from` | query | no | Only items dated on or after this day, as YYYY-MM-DD. |  |
| `to` | query | no | Only items dated on or before this day, as YYYY-MM-DD. |  |
| `source` | query | no | both (the default), mail or drive. |  |
| `mailbox` | query | no | Only mail in this folder, spelled as the results' `mailbox` shows it, such as INBOX. |  |
| `has_attachments` | query | no | 1 for only mail that has attachments. |  |
| `mime` | query | no | Only files of this type, such as image or application/pdf. |  |
| `type_in` | query | no | Only these types, repeated for more than one. A group (cat:pictures), a whole kind (image/*) or one type (image/png). For mail it matches the attachments. |  |
| `type_ex` | query | no | Leave these types out, written the same way as type_in. |  |
| `tag` | query | no | Only photos with this tag, or a tag filed under it. |  |
| `shared` | query | no | What to do with files others have shared with you. include (the default), exclude, or only. |  |
| `in_trash` | query | no | 1 to search your deleted files instead. |  |
| `min_size` | query | no | Only files of at least this many bytes. |  |
| `max_size` | query | no | Only files of at most this many bytes. |  |
| `limit` | query | no | The most results from mail, and from files. 50 if you leave it out, 200 at most. |  |
| `offset` | query | no | Skip this many results first, to get the next page. |  |

## Good to know

- With no words and no filter, nothing is searched and both lists come back empty. Choosing only a `source` doesn't count as a filter.
- A mail result's `message_id` is the search's own number for it, not the `uid` that Read a message takes.
- Files you have kept out of search (marked private in drive, alone or by their folder) never come back.

## Examples

cURL:

```bash
curl -s 'https://api.mailmasker.org/api/v1/search?q=invoice' \
  -H "Authorization: Bearer $TOKEN"
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->get('https://api.mailmasker.org/api/v1/search',
    { Authorization => "Bearer $ENV{TOKEN}" },
    form => { q => 'invoice' })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

```bash
homelab-cli search invoice
```

## Response

200 OK:

```json
{
  "account": "you@example.com",
  "indexed": true,
  "filters": {
    "q": "invoice", "person": "", "from": "", "to": "", "mailbox": "",
    "mime": "", "tag": "", "shared": "include", "source": "both",
    "type_in": [], "type_ex": [], "in_trash": 0, "has_attachments": 0,
    "limit": 50, "offset": 0
  },
  "mail": [
    {
      "message_id": 4182,
      "subject": "Your November invoice",
      "sent_at": "2026-11-03 21:42:10-06",
      "received_at": "2026-11-03 21:42:12-06",
      "size_bytes": 48211,
      "has_attachments": 1,
      "is_seen": 1,
      "mailbox": "INBOX",
      "rank": 0.4,
      "from_addr": "billing@example.com",
      "from_name": "Example Billing",
      "snippet": "Thanks for your order. Your invoice for November is attached."
    }
  ],
  "drive": [
    {
      "drive_item_id": 913,
      "drive_file_id": 2207,
      "file_uuid": "6f1c2a9e-3b4d-4c5e-9f70-1a2b3c4d5e6f",
      "file_name": "invoice-october.pdf",
      "folder_path": "Bills",
      "size_bytes": 88340,
      "uploaded_at": "2026-11-02 08:15:30.402113-06",
      "content_created_at": null,
      "deleted_at": null,
      "mime_type": "application/pdf",
      "rank": 0.2,
      "snippet": "Invoice for October. Amount due"
    }
  ]
}
```