Skip to main content
Glama
thenavidm

Beehiiv MCP Server

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Create newsletter list

create_newsletter_list
Destructive

Creates a new newsletter list in Beehiiv to group subscribers. Requires confirm=true for the action and newsletter_lists:write for OAuth.

Instructions

Create newsletter list. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require newsletter_lists:write.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoThe name of the newsletter list.
slugNoA unique slug for the newsletter list. Auto-generated from the name if not provided.
accountNoNamed private account from BEEHIIV_ACCOUNTS. Defaults to BEEHIIV_DEFAULT_ACCOUNT or the first configured account.
confirmNoSet true only when the user asked for exactly this action.
headersNo
payloadNoComplete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file.
utm_mediumNoThe utm_medium appended to links in posts sent to this list.
utm_sourceNoThe utm_source appended to links in posts sent to this list.
descriptionNoA description of the newsletter list.
payload_fileNoLocal JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged.
utm_campaignNoThe utm_campaign appended to links in posts sent to this list.
auto_subscribeNoWhether new subscribers are automatically subscribed to this list.
email_settingsNo
publication_idYesThe prefixed ID of the publication object
utm_params_enabledNoWhether UTM parameters are appended to links in posts sent to this list. Omit to inherit from the publication.
show_in_preference_centerNoWhether the list appears on the subscriber Manage Preferences page, where subscribers can opt in to or out of it. Defaults to `false`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed22 schema fields changedv3.0.1
    • addedInput schema / $defs
      Added value: +{
+  "NewsletterListEmailSettings": {
+    "additionalProperties": false,
+    "description": "The sending identity for posts sent to this list. Any field omitted is inherited from the publication.",
+    "properties": {
+      "from_address": {
+        "description": "Email address to send from. Must be an existing from address owned by the publication. Returns 422 if not found.",
+        "type": "string"
+      },
+      "reply_to_address": {
+        "description": "Email address to set as Reply-To. Must be a verified reply-to address owned by the publication. Returns 422 if not found.",
+        "type": "string"
+      },
+      "sender_name": {
+        "description": "The sender name preset, expressed as a composition key: either a single token, or ` | | `. Tokens are `brand`, `list`, `authors_first` and `authors_full`; connectors are `from`, `with`, `by`, `at`, `comma`, `colon` and `space`. For the list Weekly Digest on the publication Bee Informed, `list|by|brand` renders as \"Weekly Digest by Bee Informed\". Pass `null` to clear the override and inherit from the publication.",
+        "pattern": "^(brand|list|authors_first|authors_full)(\\|(from|with|by|at|comma|colon|space)\\|(brand|list|authors_first|authors_full))?$",
+        "type": "string"
+      }
+    },
+    "title": "NewsletterListEmailSettings",
+    "type": "object"
+  },
+  "headers": {
+    "additionalProperties": {
+      "type": "string"
+    },
+    "description": "Custom email headers for posts sent to this list. Merges with publication headers at send time, with this list's values winning on a key collision. Set a value to `null` to suppress a header inherited from the publication. System-managed headers (e.g. List-Unsubscribe, X-SMTPAPI) cannot be overridden.",
+    "type": "object"
+  }
+}
    • changedInput schema / properties / confirm / description
      Previous value: -"Must be true for every account mutation. Confirms only the user-requested action."New value: +"Set true only when the user asked for exactly this action."
    • addedInput schema / properties / email_settings / $ref
      Added value: +"#/$defs/NewsletterListEmailSettings"
    • removedInput schema / properties / email_settings / additionalProperties
      Removed value: -false
    • removedInput schema / properties / email_settings / description
      Removed value: -"The sending identity for posts sent to this list. Any field omitted is inherited from the publication."
    • removedInput schema / properties / email_settings / properties
      Removed value: -{
-  "from_address": {
-    "description": "Email address to send from. Must be an existing from address owned by the publication. Returns 422 if not found.",
-    "type": "string"
-  },
-  "reply_to_address": {
-    "description": "Email address to set as Reply-To. Must be a verified reply-to address owned by the publication. Returns 422 if not found.",
-    "type": "string"
-  },
-  "sender_name": {
-    "description": "The sender name preset, expressed as a composition key: either a single token, or ` | | `. Tokens are `brand`, `list`, `authors_first` and `authors_full`; connectors are `from`, `with`, `by`, `at`, `comma`, `colon` and `space`. For the list Weekly Digest on the publication Bee Informed, `list|by|brand` renders as \"Weekly Digest by Bee Informed\". Pass `null` to clear the override and inherit from the publication.",
-    "pattern": "^(brand|list|authors_first|authors_full)(\\|(from|with|by|at|comma|colon|space)\\|(brand|list|authors_first|authors_full))?$",
-    "type": "string"
-  }
-}
    • removedInput schema / properties / email_settings / title
      Removed value: -"NewsletterListEmailSettings"
    • removedInput schema / properties / email_settings / type
      Removed value: -"object"
    • addedInput schema / properties / headers / $ref
      Added value: +"#/$defs/headers"
    • removedInput schema / properties / headers / additionalProperties
      Removed value: -{
-  "type": "string"
-}
    • removedInput schema / properties / headers / description
      Removed value: -"Custom email headers for posts sent to this list. Merges with publication headers at send time, with this list's values winning on a key collision. Set a value to `null` to suppress a header inherited from the publication. System-managed headers (e.g. List-Unsubscribe, X-SMTPAPI) cannot be overridden."
    • removedInput schema / properties / headers / type
      Removed value: -"object"
    • addedInput schema / properties / payload / properties / email_settings / $ref
      Added value: +"#/$defs/NewsletterListEmailSettings"
    • removedInput schema / properties / payload / properties / email_settings / additionalProperties
      Removed value: -false
    • removedInput schema / properties / payload / properties / email_settings / description
      Removed value: -"The sending identity for posts sent to this list. Any field omitted is inherited from the publication."
    • removedInput schema / properties / payload / properties / email_settings / properties
      Removed value: -{
-  "from_address": {
-    "description": "Email address to send from. Must be an existing from address owned by the publication. Returns 422 if not found.",
-    "type": "string"
-  },
-  "reply_to_address": {
-    "description": "Email address to set as Reply-To. Must be a verified reply-to address owned by the publication. Returns 422 if not found.",
-    "type": "string"
-  },
-  "sender_name": {
-    "description": "The sender name preset, expressed as a composition key: either a single token, or ` | | `. Tokens are `brand`, `list`, `authors_first` and `authors_full`; connectors are `from`, `with`, `by`, `at`, `comma`, `colon` and `space`. For the list Weekly Digest on the publication Bee Informed, `list|by|brand` renders as \"Weekly Digest by Bee Informed\". Pass `null` to clear the override and inherit from the publication.",
-    "pattern": "^(brand|list|authors_first|authors_full)(\\|(from|with|by|at|comma|colon|space)\\|(brand|list|authors_first|authors_full))?$",
-    "type": "string"
-  }
-}
    • removedInput schema / properties / payload / properties / email_settings / title
      Removed value: -"NewsletterListEmailSettings"
    • removedInput schema / properties / payload / properties / email_settings / type
      Removed value: -"object"
    • addedInput schema / properties / payload / properties / headers / $ref
      Added value: +"#/$defs/headers"
    • removedInput schema / properties / payload / properties / headers / additionalProperties
      Removed value: -{
-  "type": "string"
-}
    • removedInput schema / properties / payload / properties / headers / description
      Removed value: -"Custom email headers for posts sent to this list. Merges with publication headers at send time, with this list's values winning on a key collision. Set a value to `null` to suppress a header inherited from the publication. System-managed headers (e.g. List-Unsubscribe, X-SMTPAPI) cannot be overridden."
    • removedInput schema / properties / payload / properties / headers / type
      Removed value: -"object"
  2. First observedv2.0.0

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known. The description adds genuinely new context beyond the annotations: it changes account state, requires a confirm=true gate, and needs the newsletter_lists:write scope. It still does not say what a non-idempotent create does on repeat calls or what the response returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences with zero filler: the action first, then the state-change/confirm requirement, then the auth scope. Every sentence carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter, nested-object, no-output-schema tool, the schema is rich (88% coverage) and the annotations carry the safety profile, so the description does not need to restate field semantics. It fills the key gaps an agent cannot infer from structure alone (state mutation, confirm gate, OAuth scope), though it says nothing about the multiple body-input modes (payload, payload_file, flags).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 88%, so the schema already documents nearly all 16 parameters in detail (payload vs. flags, utm fields, email_settings, headers). The description only touches the confirm parameter, adding no syntax or format meaning beyond what the schema provides, which makes the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ("Create newsletter list") that maps unambiguously to the create operation, distinguishing it from sibling verbs like update_newsletter_list and delete_newsletter_list. It is clear but does not explicitly name or contrast with those siblings, which keeps it short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a concrete usage rule: confirm=true is required "for the user-requested action," and states the OAuth scope (newsletter_lists:write) needed for integrations. That is clear context for invoking the tool correctly, but no alternatives or when-not conditions are offered, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools