# GET /api/v1/email/messages

> Search or list messages in a mail folder

- Group: email
- Tier: R
- Required scope: contents:email + read:email
- Docs: https://api.inleed.com/reference/email/search-mail

## Description

Returns `total` matches and `messages[]` — `uid`, `date`, `sizeBytes`, `flags`, `subject`, `from`, `to` — newest first. No criteria = the latest messages. Bodies are never included; read one message with `read_email` using its `uid` and `folder`.

## Query parameters

- `address` — string (required). The full mailbox address, e.g. info@example.com.
- `folder` — string. Up to 80 characters. Pattern ^[A-Za-z0-9 ._\/-]+$.
- `text` — string. Free text matched against message bodies and headers, e.g. faktura 1042.
- `from` — string. Match the From header, e.g. anna@example.com or just anna.
- `to` — string. Match the To header.
- `subject` — string. Match the Subject header.
- `since` — string. Only messages on/after this date, YYYY-MM-DD.
- `before` — string. Only messages before this date, YYYY-MM-DD.
- `unseen` — boolean. Only unread messages when true.
- `limit` — integer. Page size for a collection. Range 1–50.
- `offset` — integer. Skip this many newest matches — page 2 is offset=limit.

## Request

```bash
curl -X GET "https://mcp.inleed.com/api/v1/email/messages?address=info%40example.se&folder=example.se&text=example.se&from=example.se&to=example.se&subject=example.se&since=example.se&before=example.se&unseen=true&limit=3&offset=1" \
  -H "Authorization: Bearer inl_live_…"
```

## Response · 200

```json
{
  "target": {
    "input": "example.se",
    "kind": "domain",
    "domain": null,
    "mailbox": null,
    "serviceId": 90714,
    "domainServiceId": null,
    "daUsername": "inleed42",
    "node": "web12",
    "userId": 4821,
    "note": null
  },
  "address": "info@example.se",
  "folder": "example.se",
  "total": 3,
  "offset": "example.se",
  "messages": [
    {
      "uid": 1,
      "date": "example.se",
      "sizeBytes": 3,
      "flags": "example.se",
      "subject": "example.se",
      "from": "example.se",
      "to": "example.se"
    }
  ]
}
```

## Errors

- **401** No token was presented, or the token is revoked, expired or unknown. — codes: unauthorized, token_expired, token_revoked
- **403** The token lacks a required scope, or this account does not own the resource. — codes: insufficient_scope
- **422** Validation error — codes: validation_failed
- **429** The rate limit for this token is exhausted. See `Retry-After`. — codes: rate_limited
- **500** Something went wrong on our side. The failure is logged against `requestId`. — codes: internal_error

## Related

- GET /api/v1/email/messages/folders — https://api.inleed.com/reference/email/list-mail-folders
- GET /api/v1/email/messages/detail — https://api.inleed.com/reference/email/read-email-message
- POST /api/v1/email/messages/actions/organize — https://api.inleed.com/reference/email/organize-mail