# stensul-list-emails

> Lists emails and templates with filters for name, type, library, tags, language, project and status.

Source: https://stensul.com/developers/reference/stensul-list-emails/ · From the live server's tool list, 2026-09-28

- Scope: `emails:read`
- Access: read

The default field set already covers browsing and picking. Leave `fields` unset unless you have a reason.

## Inputs

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | no | Search by name, author or tags. |
| `name` | string | no | Filter by email name. |
| `types` | string[] | no | Filter by email types, for example `["draft", "template"]`. |
| `library_keys` | string[] | no | Filter by library keys. |
| `tags` | string[] | no | Filter by tags. |
| `tags_match_criteria` | "any" \| "all" | no | Match criteria for the tags filter. |
| `language` | string | no | Filter by language, for example `en-US`. |
| `project_id` | string (24-char hex id) | no | Filter by project ID. |
| `is_archived` | 0 \| 1 | no | Filter archived emails. |
| `has_been_uploaded` | 0 \| 1 | no | Filter by uploaded status. |
| `has_modules_locked` | 0 \| 1 | no | Filter by locked-modules status. |
| `include` | string | no | Include related resources, for example `outputs,snippets`. |
| `fields` | string | no | Comma-separated sparse fieldset. `id` is always included. |
| `sort` | string | no | Sort criteria; prefix `-` for descending. |
| `page_number` | integer ≥ 1 | no | Page number. |
| `page_size` | integer 1–30 | no | Results per page (max 30, default 15). |

## Example request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "stensul-list-emails",
    "arguments": {
      "types": [
        "template"
      ],
      "library_keys": [
        "acme_newsletters"
      ],
      "page_size": 10
    }
  }
}
```

## Response

A page of emails with name, type, tags, project, archived and upload status, locked and outdated modules, proof and approval state, library, language and last update.

## Errors

| Status | Message | Cause | Fix |
| --- | --- | --- | --- |
| 401 | Authentication expired or missing | The session's authorization expired. | Sign in again when the host prompts. On a 401 or 403, the server's instructions tell the model to re-check sign-in first. |
| 403 | Insufficient OAuth scope (403): The token lacks the required scope | The API connection doesn't have the scope this tool needs. | An admin adds the scope to the API connection. Then sign in again: adding a scope revokes existing tokens. |
| 403 | API error (403): Action is unauthorized. | The signed-in user's role lacks the permission, for example `edit_campaign`. | Grant the permission to the user's role in Admin > Users & Roles. It works for other users on the same connection. |