---
title: "Try a label on recent mail"
description: "What a label that AI applies would catch in the newest inbox mail, without labelling anything."
url: "https://openemail.uk/docs/api/labels/test"
area: "API"
category: "Mailbox"
---

# Try a label on recent mail

What a label that AI applies would catch in the newest inbox mail, without labelling anything.

`POST /labels/{id}/test`

## POST /labels/{id}/test

What a label that AI applies would catch in the newest inbox mail, without labelling anything.

## Example

Needs `labels:write` and `threads:read`. Send `aiInstructions` to try wording you have not saved yet, or `{}` to try what the label holds.

**curl**

```
curl -X POST "$OE/labels/USER_INVOICES/test" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "aiInstructions": "invoices and receipts" }'
```

**Response**

```
{
  "object": "label_test",
  "labelId": "USER_INVOICES",
  "examined": 20,
  "matched": [
    {
      "threadId": "thr_7c1e4a90",
      "subject": "Your September invoice",
      "sender": "billing@acme.com",
      "receivedOn": "Wed, 23 Sep 2026 10:02:44 +0000"
    }
  ]
}
```

> It reads the newest 20 inbox threads, and `examined` says how many it read. A message that arrived encrypted is skipped, and a key limited to particular addresses reads only the threads delivered to them.

> A try spends one AI action of the caller, which the labelling of arriving mail never does. With none left today it is a 429 `ai_quota_exceeded`, with no instructions in the request or on the label a 422 `invalid_parameter`, and on an install with no AI model a 409 `ai_not_configured`.

## Reference

- [`POST /labels/{id}/test`](https://openemail.uk/docs/api/reference/labels#post-labels-id-test): full reference