# stensul-add-email-module

> Adds one module (a whole section) from the library to a draft, found by what the user called it.

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

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

Pass what the user called the block as `moduleName` and let the tool resolve it to a module in the library; never guess a module key. If no module matches, nothing is added. If several match, the tool returns a numbered question and a `moduleListToken`: ask the user, then call again with the same `moduleName`, the `moduleOrdinal` they picked and the token unchanged. Without `beforeModuleId` the new module lands as the last content block, above the library's fixed footer if it has one. To place it somewhere else, read the email first and pass the id of the module that sits in that spot now. Fixed headers and footers are governed by the library and can never be added. The result includes a preview of the updated email, so no separate preview call is needed.

## Inputs

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `emailId` | string (24-char hex id) | yes | Email ID. |
| `moduleName` | string | yes | What the user called the block, in their own words (for example "the testimonial block"). The tool resolves it to a module. Ignored when `moduleKey` is sent. |
| `beforeModuleId` | string \| number | no | Module instance id from `stensul-read-email` (not the module key) of the block that sits where the new one should go. The new module is inserted just before it. Omit to add it as the last content block. |
| `moduleOrdinal` | integer | no | The number the user picked from a previous disambiguation question. Send it with the same `moduleName` and `moduleListToken`. |
| `moduleListToken` | string | no | The token from the previous disambiguation question, passed back unchanged. If the library changed since, the tool asks again. |
| `moduleKey` | string | no | A module key already known from an earlier read. When present, name resolution is skipped. |
| `save_version` | integer | no | The email's version as you last read or wrote it. On a conflict nothing is added. |

## Example request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "stensul-add-email-module",
    "arguments": {
      "emailId": "64f0c0ffee0000000000abcd",
      "moduleName": "the testimonial block",
      "beforeModuleId": "2817004",
      "save_version": 8
    }
  }
}
```

## Response

The added module and the email's new `save_version`, with a preview of the updated email. Or a numbered question when several modules match the name, or a refusal that says why nothing was added.

## 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. |
| 409 | Version conflict | The email changed since your last read, and you passed its old `save_version`. | Read the email again and re-apply your change on the current version. Never retry by dropping `save_version`. |
| 422 | Fixed header or footer can't be added | `stensul-add-email-module` was asked for a module the library fixes at the top or bottom of every email. | Nothing to fix. Those modules are governed by the library. Report it and don't offer a substitute. |
| 422 | The "before" module is not in this email | The email changed since it was read, so the module named in `beforeModuleId` is gone. | Read the email again and ask the user where the new module should go now. |
| 403 | API error (403): Sent emails cannot be edited. | The email has already been sent. | Nothing to fix. Copy it and edit the copy. |