stensul-add-email-module

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

write: changes contentScope emails: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

emailIdstring (24-char hex id)required
Email ID.
moduleNamestringrequired
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.
beforeModuleIdstring | numberoptional
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.
moduleOrdinalintegeroptional
The number the user picked from a previous disambiguation question. Send it with the same moduleName and moduleListToken.
moduleListTokenstringoptional
The token from the previous disambiguation question, passed back unchanged. If the library changed since, the tool asks again.
moduleKeystringoptional
A module key already known from an earlier read. When present, name resolution is skipped.
save_versionintegeroptional
The email's version as you last read or wrote it. On a conflict nothing is added.

Errors people hit

What you see	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.

All errors: Errors and troubleshooting.

{
  "emailId": "64f0c0ffee0000000000abcd",
  "moduleName": "the testimonial block",
  "beforeModuleId": "2817004",
  "save_version": 8
}

{
  "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.

Described from the tool's definition. Captured responses from a Stensul-internal tenant will replace this.

Example values use invented brands and ids. Tool definition captured 2026-10-07.