# stensul-create-email

> Creates an empty draft in a library from a list of module keys. Prefer `stensul-build-email` for normal creation.

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

- Scope: `emails:write`
- Access: write

Use it when an empty structure is all you need. Under variations mode `all`, a request for several variations in one email cannot be expressed; the tool refuses rather than guessing. The result embeds a preview.

## Inputs

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `library_key` | string | yes | Key of the library to create the email in. |
| `name` | string | yes | Email name. |
| `modules` | string[] | no | Module keys from the library, in order (from `stensul-get-libraries`). |
| `subject_line` | string | no | Subject line, when the library enables it. |
| `preheader` | string | no | Preheader, when the library enables it. |
| `title` | string | no | Title, when the library enables it. |
| `language` | string | no | Language code. |
| `tags` | string[] | no | Tags configured in the library. |
| `project_id` | string (24-char hex id) | no | Project to assign the email to. |
| `type` | string | no | Email type, for example `draft` or `template`. |
| `active_variation_id` | string (24-char hex id) | no | Variation to activate. Opt-in only. |
| `confirmed_repeated_modules` | boolean | no | Set `true` only after the user confirmed a repeated module key under variations mode `all`. |
| `include` | string | no | Include related resources in the response. |

## Example request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "stensul-create-email",
    "arguments": {
      "library_key": "northwind_marketing",
      "name": "Northwind – empty newsletter shell",
      "modules": [
        "header",
        "hero",
        "two_column_cards",
        "footer"
      ]
    }
  }
}
```

## Response

The new draft with an embedded preview. If images lack alt text, the result ends with an accessibility list to resolve in one follow-up call.

## 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. |
| 422 | Field not enabled for this library | `stensul-update-email-settings` sent a title, subject line or preheader the library doesn't enable, so the whole call is declined. | Send only fields the library enables (see `stensul-get-libraries`). |