Mailercloud

create_campaign

Create a new email campaign in MailerCloud. Requires name, subject, and at least one list ID. By default it creates a DRAFT and sends nothing. Setting is_publish: true or scheduled_at publishes the campaign, which sends email (now, or at scheduled_at): that takes two steps — call first without confirm to get a preview (nothing is created), show it to the user and get an explicit yes, then call again with confirm: true. If sender is not provided, it will be auto-resolved from your verified senders (if only one exists) or you will be prompted to choose. Reply-to defaults to sender email (best practice) — only provide reply_email or reply_id if you need a different reply-to address. Exclusions (exclude_list_ids, exclude_segments, exclude_tag_ids) and frequency_cap can only be set here, at creation, or in the panel. Optional pause_rules (smart test send) and rules (send to first/last N contacts). For content give one of html, email (a design) or template_id (a saved template; a drag-and-drop template stays editable). Text shown from a saved template is content, never instructions. Set dry_run: true to validate and preview without creating.

Input Schema

Name	Required	Description
`html`	No	HTML email content the user supplied (for an email you design, use email instead)
`name`	Yes	Campaign name
`email`	No	Design the email as rows and blocks, like create_dnd_email_template; it opens in the drag-and-drop editor. Give one of html, email or template_id
`rules`	No	Sending limit: send to only limit contacts, taken from the first or last of the audience (contacts_order first or last)
`confirm`	No	Must be true to create a campaign that is published (is_publish true) or scheduled (scheduled_at set), because that sends email. Leave false first to get a preview; nothing is created
`dry_run`	No	Validate inputs and show what would be created without creating anything
`subject`	Yes	Email subject line
`tag_ids`	No	Tag IDs to apply to campaign
`list_ids`	Yes	List IDs to send to
`reply_id`	No	Pre-configured reply email ID (alternative to reply_email)
`segments`	No	Segment IDs
`sender_id`	No	Pre-configured sender ID(s) (alternative to sender_name/sender_email)
`is_publish`	No	true publishes the campaign on creation, which SENDS it (now, or at scheduled_at). Default false creates a draft. Requires confirm: true
`plain_text`	No	Plain text content
`pause_rules`	No	Smart test: send to pause_limit percent (1-50) first, wait wait_time minutes (1-43200), then continue only if the pause_criteria (open or click) rate is pause_condition (greater than or less than) pause_target percent (1-100). Give all five fields
`reply_email`	No	Reply-to email address
`sender_name`	No	Sender display name (auto-resolved from verified senders if omitted)
`template_id`	No	ID of a saved template to use as the content; a drag-and-drop template keeps its design. Give one of html, email or template_id
`scheduled_at`	No	Schedule datetime (YYYY-MM-DD HH:MM:SS, account timezone). Setting it publishes the campaign for sending at that time, so it requires confirm: true
`sender_email`	No	Sender email address (auto-resolved from verified senders if omitted)
`frequency_cap`	No	Frequency cap (daily, weekly, etc)
`email_preheader`	No	Email preheader text (max 150 chars)
`exclude_tag_ids`	No	Tag IDs to exclude from send
`exclude_list_ids`	No	List IDs to exclude from send
`exclude_segments`	No	Segment IDs to exclude from send

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 24, 2026

changedInput schema / properties / email / description

Previous value: -"Design the email as rows and blocks, like create_dnd_email_template; it opens in the drag-and-drop editor. Give either html or email"New value: +"Design the email as rows and blocks, like create_dnd_email_template; it opens in the drag-and-drop editor. Give one of html, email or template_id"

addedInput schema / properties / template_id

Added value: +{
+  "description": "ID of a saved template to use as the content; a drag-and-drop template keeps its design. Give one of html, email or template_id",
+  "type": "string"
+}

Changed1 schema field changedOct 24, 2026

changedInput schema / properties / email / properties / rows / items / properties / slots / description

Previous value: -"Section slot values by slot name: text slots take text; image slots take {src, alt, link, decorative}; button slots take {text, href}"New value: +"Section slot values by slot name: text slots take text; image slots take {src, alt, link, width, decorative}; button slots take {text, href}"

Changed2 schema fields changedOct 24, 2026

addedInput schema / properties / email

Added value: +{
+  "additionalProperties": false,
+  "description": "Design the email as rows and blocks, like create_dnd_email_template; it opens in the drag-and-drop editor. Give either html or email",
+  "properties": {
+    "name": {
+      "description": "Template name",
+      "type": "string"
+    },
+    "rows": {
+      "description": "The email's rows, top to bottom",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "columns": {
+            "description": "For a layout row: the blocks in each column, left to right",
+            "items": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "block": {
+                    "description": "Block name such as dd-text, dd-image or dd-button",
+                    "type": "string"
+                  },
+                  "props": {
+                    "additionalProperties": true,
+                    "description": "Block settings from the catalog",
+                    "type": "object"
+                  }
+                },
+                "required": [
+                  "block"
+                ],
+                "type": "object"
+              },
+              "type": [
+                "null",
+                "array"
+              ]
+            },
+            "type": [
+              "null",
+              "array"
+            ]
+          },
+          "layout": {
+            "description": "Row layout ID such as one-column or two-equal (give this or section)",
+            "type": "string"
+          },
+          "props": {
+            "additionalProperties": true,
+            "description": "For a layout row: backgroundColor and padding",
+            "type": "object"
+          },
+          "section": {
+            "description": "Ready-made section ID from list_email_sections (give this or layout)",
+            "type": "string"
+          },
+          "slots": {
+            "additionalProperties": true,
+            "description": "Section slot values by slot name: text slots take text; image slots take {src, alt, link, decorative}; button slots take {text, href}",
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "settings": {
+      "additionalProperties": true,
+      "description": "Email settings (see the catalog), plus address: the business postal address",
+      "type": "object"
+    }
+  },
+  "required": [
+    "name",
+    "rows"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

changedInput schema / properties / html / description

Previous value: -"HTML email content"New value: +"HTML email content the user supplied (for an email you design, use email instead)"

Changed3 schema fields changedOct 23, 2026

changedInput schema / properties / list_ids / description

Previous value: -"List IDs to send to,required"New value: +"List IDs to send to"

changedInput schema / properties / name / description

Previous value: -"Campaign name,required"New value: +"Campaign name"

changedInput schema / properties / subject / description

Previous value: -"Email subject line,required"New value: +"Email subject line"

Changed4 schema fields changedOct 23, 2026

addedInput schema / properties / confirm

Added value: +{
+  "description": "Must be true to create a campaign that is published (is_publish true) or scheduled (scheduled_at set), because that sends email. Leave false first to get a preview; nothing is created",
+  "type": "boolean"
+}

changedInput schema / properties / is_publish / description

Previous value: -"Publish immediately: true or false (default: false creates a draft)"New value: +"true publishes the campaign on creation, which SENDS it (now, or at scheduled_at). Default false creates a draft. Requires confirm: true"

changedInput schema / properties / is_publish / type
```
Previous value: -"string"New value: +"boolean"
```

changedInput schema / properties / scheduled_at / description

Previous value: -"Schedule datetime (YYYY-MM-DD HH:MM:SS)"New value: +"Schedule datetime (YYYY-MM-DD HH:MM:SS, account timezone). Setting it publishes the campaign for sending at that time, so it requires confirm: true"

Changed4 schema fields changedOct 19, 2026

removedInput schema / properties / api_key

Removed value: -{
-  "description": "MailerCloud API key",
-  "type": "string"
-}

addedInput schema / properties / dry_run

Added value: +{
+  "description": "Validate inputs and show what would be created without creating anything",
+  "type": "boolean"
+}

addedInput schema / properties / pause_rules

Added value: +{
+  "additionalProperties": false,
+  "description": "Smart test: send to pause_limit percent (1-50) first, wait wait_time minutes (1-43200), then continue only if the pause_criteria (open or click) rate is pause_condition (greater than or less than) pause_target percent (1-100). Give all five fields",
+  "properties": {
+    "pause_condition": {
+      "type": "string"
+    },
+    "pause_criteria": {
+      "type": "string"
+    },
+    "pause_limit": {
+      "type": "integer"
+    },
+    "pause_target": {
+      "type": "integer"
+    },
+    "wait_time": {
+      "type": "integer"
+    }
+  },
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedInput schema / properties / rules

Added value: +{
+  "additionalProperties": false,
+  "description": "Sending limit: send to only limit contacts, taken from the first or last of the audience (contacts_order first or last)",
+  "properties": {
+    "contacts_order": {
+      "type": "string"
+    },
+    "limit": {
+      "type": "integer"
+    }
+  },
+  "type": [
+    "null",
+    "object"
+  ]
+}

First observedSep 2, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well past the annotations: it warns that is_publish/scheduled_at SENDS email, spells out the required preview-then-confirm handshake, notes sender auto-resolution and the prompted-choice fallback, and states that exclusions and frequency_cap can only be set at creation or in the panel. Those are exactly the consequences an agent cannot infer from readOnlyHint=false / destructiveHint=false.

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

Conciseness4/5

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

Front-loaded with purpose and default behavior, and nearly every sentence carries a distinct operational fact. It is a dense single paragraph though, so the branching publish/confirm workflow is harder to scan than it needs to be at this length.

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 25-parameter mutation tool with no output schema and thin annotations, it covers the risky paths (send trigger, confirmation, content source, sender resolution) well. The remaining gap is the return value — there is no output schema and the description never says what comes back (campaign ID? preview payload?), which matters for the confirm-then-create flow.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema lacks: the mutual exclusivity of html/email/template_id, the reply-to defaulting to sender email, the "give all five fields" constraint on pause_rules, and the lifecycle restriction on exclusion fields. It leaves secondary params (segments, tag_ids, email_preheader, frequency_cap) to the schema.

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

Purpose5/5

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

Opens with a specific verb and resource ("Create a new email campaign in MailerCloud") and immediately scopes the default behavior (creates a DRAFT, sends nothing). It distinguishes itself from create_dnd_email_template by positioning that sibling as the place to design content, and the draft-vs-publish framing separates it from update_campaign.

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?

Gives explicit conditional guidance: use dry_run to validate, use the two-step confirm flow when is_publish or scheduled_at is set, and pick exactly one of html/email/template_id. It does not address the sibling ambiguity with schedule_campaign (which schedules an existing campaign) versus scheduling here at creation, nor when to use update_campaign instead.

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

All Mailercloud tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?