{ "openapi": "3.1.0", "info": { "title": "KlickTipp MCP Tools", "description": "This specification describes the **KlickTipp MCP Server**.\n\nIt is intended for developers and integrators who want AI assistants — Claude, ChatGPT, or any other MCP-capable client — to interact with KlickTipp through the **Model Context Protocol (MCP)** instead of raw HTTP calls: to manage newsletters, contacts, tags, custom fields and opt-in processes.\n\n**What this document is for:** it is a reference, not a live console — it shows what the KlickTipp MCP server can do, so you can see what's possible before connecting anything. You do not need a KlickTipp account, an OAuth sign-in, or a running MCP client just to browse it. It is a separate documentation area from the classic KlickTipp Management API. This document is meant to show the current functional scope of the server, not a fixed contract: tools, schemas and everything else here are subject to change.\n\n> **Current tool list & source:** [`agent-plugins` repository on GitHub](https://github.com/klicktipp/agent-plugins). Tools shown in this document are subject to change — the repository always reflects the current state. Once you are connected, any MCP client can also fetch the same tool list live from the server itself with the standard MCP tools/list call.\n\n---\n\n## MCP Server\n\nThe KlickTipp MCP server lets AI assistants — Claude, ChatGPT, or any other MCP-capable client — interact with a KlickTipp account through the Model Context Protocol (MCP), instead of raw HTTP calls. The endpoint for the production environment:\n\n| | |\n|---|---|\n| **URL** | `https://mcp.klicktipp.com/mcp` |\n| **Authentication** | Managed OAuth 2.0 (no API key, no local server, no `.env` file needed) |\n| **Requirement** | A KlickTipp **Deluxe** or **Enterprise** subscription with permission to log in to the account in question |\n\n> **Good to know:** this MCP Server uses a KlickTipp managed OAuth 2.0, not the Management API's session cookie or key-based authentication.\n\n---\n\n## Getting Started\n\nA rough guide to connecting any MCP-capable client:\n\n1. **Add the server**\n In your MCP client's connector/integration settings, add a new remote MCP server pointing to this URL:\n ```\n https://mcp.klicktipp.com/mcp\n ```\n2. **Complete the OAuth sign-in**\n Your client redirects you to sign in with your KlickTipp credentials. Every tool call afterwards is made as that signed-in user, against the account they are permitted to access.\n\n3. **Call tools**\n Once connected, call the tools listed in this document by name.\n\nThe exact setup steps differ a little by client. Step-by-step instructions for Claude and for ChatGPT specifically are in the [MCP server guide](https://developers.klicktipp.com/guides/mcp-server).\n\n> Before OAuth sign-in completes, calls are expected to return `401 Unauthorized`. That is not a configuration error — it is the normal state before login. If a sign-in was interrupted or not approved, simply repeat the connection process.\n\n---\n\n## Tool Catalog\n\nThe KlickTipp MCP server exposes tools that your MCP client can call to interact with a KlickTipp account — to manage newsletters, contacts, tags, custom fields and opt-in processes. Tools are grouped by category in the sidebar.\n\n---\n\n## Security Behaviour\n\nThe MCP server is deliberately designed so an AI assistant can search and read broadly, while critical and irreversible actions stay with a human:\n\n- **Sending a newsletter always needs a separate human confirmation inside KlickTipp.** The dispatch tool only validates the newsletter and returns a short-lived, single-use confirmation link; the actual send is always confirmed separately by the logged-in user in the KlickTipp app.\n- **Some destructive actions are available over MCP** — for example, deleting a tag, a custom field or an opt-in process. These are irreversible and affect the account directly: use them deliberately, and confirm with a human before calling them.\n- **Tools that can start or change campaigns, autoresponders or automations as a side effect (assigning or removing a tag, subscribing or unsubscribing a contact) require an explicit `approval` field in the request**, so a calling client can prompt a human before those effects happen.\n\n---\n\n## Error Handling\n\nA failed tool call is handled by the client and returned as a clear, human-readable error — for example when authentication hasn't completed yet, or an unknown tool is called — rather than a raw HTTP response.\n\n---\n\n## Plugin & Further Use Cases\n\nFor Claude and Codex, KlickTipp also offers a combined **plugin package** that bundles the MCP server with matching **skills**. The skills train the assistant to use the tools documented here effectively, with a focus on the structure of the email editor, reporting, and messaging workflows (newsletters and split tests).\n\nFor setup instructions per platform (Claude Desktop, ChatGPT, and other agentic tools), see the [MCP server plugins guide](https://developers.klicktipp.com/guides/mcp-server-plugins).\n", "version": "1.0.0" }, "tags": [ { "name": "Contact Tagging", "description": "Use these tools to organize individual contacts with existing manual tags. Tags can represent interests, lifecycle stages, customer characteristics, or any other classification that supports segmentation and automation.\n\nFor example, you can add a tag when a contact reaches a particular stage or remove one when a classification is no longer valid. Because tag changes may influence campaigns and other automated processes, their wider impact should always be considered." }, { "name": "Contacts", "description": "Use these tools to work with the people stored in a KlickTipp account. They support the contact lifecycle, from finding and creating contacts to updating their information and managing their subscription state.\n\nFor example, you can search for contacts, update their field values, subscribe them through an opt-in process, or unsubscribe them when required. Further contact-related actions may be added as the MCP server develops." }, { "name": "Data Fields", "description": "Use these tools to shape the contact data model of a KlickTipp account. Custom fields make it possible to store information that goes beyond the standard contact details and reflects the individual needs of the business.\n\nFor example, you can create fields for dates, preferences, customer attributes, or other account-specific information and manage their definitions over time. The range of supported field operations may expand as the MCP server evolves." }, { "name": "Email Editor", "description": "Use these tools to create and shape the emails used in campaigns and notifications. They provide access to the content, design, personalization, and preparation of an email before it is delivered to recipients.\n\nFor example, you can add and arrange content blocks, apply styles and templates, insert images or placeholders, preview personalized content, run quality checks, send tests, and publish the finished email body. Sending the email or adding it to an automation remains a separate workflow, and further editing capabilities may be added over time." }, { "name": "Email Images", "description": "Use these tools to manage the visual assets available for email content. They help keep images organized and make them accessible when emails are created or updated through the Email Editor.\n\nFor example, you can upload an image, add one from an external URL, browse available stock images, create folders, or preview an existing asset. Additional ways to organize and use images may be introduced as the MCP server evolves." }, { "name": "Newsletter Splittest", "description": "Use these tools to create and manage the manual tags available in a KlickTipp account. Tags provide a flexible way to organize contacts, describe their interests or status, and connect customer information with targeting and automation.\n\nFor example, you can create a new classification, update its name or description, find existing tags, or remove definitions that are no longer needed. Assigning or removing tags on individual contacts belongs to the Contact Tagging group, while further tag-management actions may be added in the future." }, { "name": "Newsletters", "description": "Use these tools to manage the lifecycle of email newsletters in KlickTipp. They bring together the newsletter draft, its audience, delivery settings, readiness, and dispatch status.\n\nFor example, you can create and configure a newsletter, send a test, prepare or schedule its delivery, start the dispatch, or cancel what has not yet been sent. The email body itself is managed through the Email Editor, while further newsletter actions may be added over time." }, { "name": "Opt-In Processes", "description": "Use these tools to create and manage the processes through which people subscribe to communications. Opt-in processes connect consent, subscription behavior, and the confirmation email that supports the signup experience.\n\nFor example, you can configure a new subscription process, update its confirmation email, preview the result, or send a test. Additional consent and subscription workflows may become available as the MCP server evolves." }, { "name": "Tags", "description": "Use these tools to create and manage the manual tags available in a KlickTipp account. Tags provide a flexible way to organize contacts, describe their interests or status, and connect customer information with targeting and automation.\n\nFor example, you can create a new classification, update its name or description, find existing tags, or remove definitions that are no longer needed. Assigning or removing tags on individual contacts belongs to the Contact Tagging group, while further tag-management actions may be added in the future." } ], "paths": {}, "x-mcp": { "protocolVersion": "2025-11-25", "capabilities": { "tools": { "listChanged": false } }, "tools": [ { "name": "get-contact", "description": "Returns the permitted detail view of one contact in a KlickTipp account: email address and email subscription status, mobile number and SMS subscription status, contact fields for the requested reference, writable manual tag IDs and the edit link. A contact reachable on only one of the two channels is answered with the other one empty, and is found either way. Every field carries its data type, and the three that are stored as numbers are answered exactly as KlickTipp shows them on screen: a date as 16.09.2026, a moment as 16.09.2026 14:30, a time of day as 14:30, in the time zone the account is configured for. It does not expose complete channel or subscription-reference records.", "tags": [ "Contacts" ], "inputSchema": { "type": "object", "properties": { "contactId": { "type": "integer", "description": "Numeric contact ID returned by search-contacts", "minimum": 1 }, "referenceId": { "type": "integer", "description": "Reference whose multi-value fields and manual tags to read; 0 for contact-wide values", "default": 0, "minimum": 0 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "contactId" ], "additionalProperties": false }, "title": "Get Contact", "outputSchema": { "type": "object", "required": [ "accountId", "contactId", "email", "subscriptionStatus", "phoneNumber", "smsSubscriptionStatus", "referenceId", "fields", "manualTagIds", "editUrl" ], "properties": { "accountId": { "type": "integer" }, "contactId": { "type": "integer" }, "email": { "type": "string" }, "subscriptionStatus": { "type": "string" }, "phoneNumber": { "type": "string" }, "smsSubscriptionStatus": { "type": "string" }, "referenceId": { "type": "integer" }, "fields": { "type": "array", "items": { "type": "object", "required": [ "fieldId", "value", "type", "referenceId" ], "properties": { "fieldId": { "type": "string" }, "value": { "type": "string" }, "type": { "type": "string" }, "referenceId": { "type": "integer" } } } }, "manualTagIds": { "type": "array", "items": { "type": "integer" } }, "editUrl": { "type": "string" } } } }, { "name": "get-opt-in-process-redirect-url", "description": "Returns the URL one contact is redirected to by an opt-in process. The contact's email address is required and is what the answer is about: the URL carries that contact's own id, address and subscriber key, so an address nobody named produces a URL about the wrong person. Which page comes back follows the contact's state, reported as redirectPage: while the double opt-in confirmation is still open it is the pending page, and only a confirmed contact gets the thank-you page -- a pending answer means that contact has not confirmed yet, not that the process is misconfigured. The URL also carries the page's campaign tracking. Processes without a custom page fall back to the KlickTipp-hosted pending or thank-you page.", "tags": [ "Contacts" ], "inputSchema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the contact the URL is resolved for; required, and it identifies which contact the URL points at", "minLength": 3, "maxLength": 250 }, "optInProcessId": { "type": [ "null", "integer" ], "description": "Opt-in process to resolve for; omit for the one the subscriber signed up through", "default": null, "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "email" ], "additionalProperties": false }, "title": "Get Subscription Redirect URL", "outputSchema": { "type": "object", "required": [ "accountId", "subscriberId", "email", "subscriptionStatus", "optInProcessId", "optInProcessName", "redirectUrl", "redirectPage" ], "properties": { "accountId": { "type": "integer" }, "subscriberId": { "type": "integer" }, "email": { "type": "string" }, "subscriptionStatus": { "type": "string" }, "optInProcessId": { "type": "integer" }, "optInProcessName": { "type": "string" }, "redirectUrl": { "type": "string" }, "redirectPage": { "type": "string" } } } }, { "name": "search-contacts", "description": "Returns a cursor-paginated list of contact channels in one KlickTipp account, sorted by address. One row is one channel: a contact reachable by email and by SMS appears twice, each time with that channel's own address and subscription status, and channel says which it is. The lean results carry the contact ID, address, status and edit link, and intentionally omit contact fields and reference data. query takes an email fragment or a mobile number written with its country code (+49... or 0049...); a number in a form the account cannot read is refused by name rather than answered with nothing. Filter further by status, channel or a writable manual tag. The returned nextCursor, unchanged and with the same filters, is the next page. One contact in full is get-contact.", "tags": [ "Contacts" ], "inputSchema": { "type": "object", "properties": { "query": { "type": [ "null", "string" ], "description": "Case-insensitive fragment of an email address, or a mobile number with its country code; omit to match every contact", "default": null, "maxLength": 250 }, "status": { "type": [ "null", "string" ], "description": "Subscription status to filter by; omit for every status", "default": null, "enum": [ "pending", "optin", "subscribed", "unsubscribed" ] }, "manualTagId": { "type": [ "null", "integer" ], "description": "ID of an existing manual tag the returned contacts must have", "default": null, "minimum": 1 }, "channel": { "type": [ "null", "string" ], "description": "Restrict to one channel, email or sms; omit for both", "default": null, "enum": [ "email", "sms" ] }, "cursor": { "type": [ "null", "string" ], "description": "Opaque nextCursor value of the previous result page; omit for the first page", "default": null, "maxLength": 500 }, "pageSize": { "type": "integer", "description": "Maximum contacts on the page, from 1 through 100", "default": 25, "minimum": 1, "maximum": 100 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "additionalProperties": false }, "title": "Search Contacts", "outputSchema": { "type": "object", "required": [ "accountId", "pageSize", "count", "hasMore", "nextCursor", "contacts" ], "properties": { "accountId": { "type": "integer" }, "pageSize": { "type": "integer" }, "count": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "contacts": { "type": "array", "items": { "type": "object", "required": [ "contactId", "channel", "contactInfo", "email", "subscriptionStatus", "editUrl" ], "properties": { "contactId": { "type": "integer" }, "channel": { "type": "string", "enum": [ "email", "sms" ] }, "contactInfo": { "type": "string" }, "email": { "type": "string" }, "subscriptionStatus": { "type": "string" }, "editUrl": { "type": "string" } } } } } } }, { "name": "subscribe-contact-via-opt-in-process", "description": "Subscribes exactly one email or SMS channel of a KlickTipp contact through an opt-in process and creates or reuses the contact and requested reference. Its effects reach a real recipient: it may send a confirmation message and may start automations. It takes either an email address or a phone number, never both. Assigning the optional tag may start further automations or outbound events. Other channels and references are not changed.", "tags": [ "Contacts" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process to run", "minimum": 1 }, "approval": { "type": "string", "description": "Exactly \"subscribe-contact\": acknowledges a confirmation message, automations and a changed real recipient", "enum": [ "subscribe-contact" ] }, "email": { "type": [ "null", "string" ], "description": "Email channel to subscribe; mutually exclusive with phoneNumber", "default": null, "maxLength": 250 }, "phoneNumber": { "type": [ "null", "string" ], "description": "SMS channel to subscribe in E.164 format; mutually exclusive with email", "default": null, "maxLength": 50 }, "referenceId": { "type": "integer", "description": "Subscription reference context to create or reuse; a non-zero ID must exist in the account", "default": 0, "minimum": 0 }, "tagId": { "type": [ "null", "integer" ], "description": "Tag to additionally assign to the contact after a successful subscription", "default": null, "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId", "approval" ], "additionalProperties": false }, "title": "Subscribe Contact", "outputSchema": { "type": "object", "required": [ "accountId", "subscriberId", "channel", "contactInfo", "referenceId", "optInProcessId", "subscriptionStatus", "contactCreated", "referenceCreated" ], "properties": { "accountId": { "type": "integer" }, "subscriberId": { "type": "integer" }, "channel": { "type": "string" }, "contactInfo": { "type": "string" }, "referenceId": { "type": "integer" }, "optInProcessId": { "type": "integer" }, "subscriptionStatus": { "type": "string" }, "contactCreated": { "type": "boolean" }, "referenceCreated": { "type": "boolean" } } } }, { "name": "unsubscribe-contact", "description": "Unsubscribes exactly one email or SMS channel of a KlickTipp contact. Its effects reach a real recipient: future subscribed-audience messages on that channel stop, and automations may run. It takes either an email address or a phone number, never both. Other channels of the same contact and all subscription references remain untouched.", "tags": [ "Contacts" ], "inputSchema": { "type": "object", "properties": { "approval": { "type": "string", "description": "Exactly \"unsubscribe-contact\": acknowledges a changed real recipient and automations", "enum": [ "unsubscribe-contact" ] }, "email": { "type": [ "null", "string" ], "description": "Email channel to unsubscribe; mutually exclusive with phoneNumber", "default": null, "maxLength": 250 }, "phoneNumber": { "type": [ "null", "string" ], "description": "SMS channel to unsubscribe in E.164 format; mutually exclusive with email", "default": null, "maxLength": 50 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "approval" ], "additionalProperties": false }, "title": "Unsubscribe Contact", "outputSchema": { "type": "object", "required": [ "accountId", "subscriberId", "channel", "contactInfo", "subscriptionStatus" ], "properties": { "accountId": { "type": "integer" }, "subscriberId": { "type": "integer" }, "channel": { "type": "string" }, "contactInfo": { "type": "string" }, "subscriptionStatus": { "type": "string" } } } }, { "name": "update-contact-values", "description": "Updates explicitly listed contact-field values for one contact. It cannot change email or SMS addresses, opt-in state, subscriptions, lists or other channel data. Every custom-field ID and the contact itself must belong to the selected account; global contact fields remain available. Date, time and datetime fields take the forms get-contact answers with -- 16.09.2026, 16.09.2026 14:30, 14:30 -- and ISO 8601 as well, for a caller that computed a date rather than read one. Anything else is refused rather than stored as a date it was not meant to be, and the refusal names the form that works. An empty value clears the field.", "tags": [ "Contacts" ], "inputSchema": { "type": "object", "properties": { "contactId": { "type": "integer", "description": "Numeric contact ID returned by search-contacts", "minimum": 1 }, "fields": { "type": "array", "description": "Contact field updates; fieldId must be a global field key or an account-owned numeric custom-field ID, a date, time or datetime value takes the form get-contact answers with, and referenceId defaults to 0", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1, "maxLength": 15 }, "value": { "type": "string", "maxLength": 65535 }, "referenceId": { "type": "integer", "minimum": 0, "default": 0 } }, "required": [ "fieldId", "value" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "contactId", "fields" ], "additionalProperties": false }, "title": "Update Contact", "outputSchema": { "type": "object", "required": [ "updatedFieldIds", "contact" ], "properties": { "updatedFieldIds": { "type": "array", "items": { "type": "string" } }, "contact": { "type": "object", "required": [ "accountId", "contactId", "email", "subscriptionStatus", "referenceId", "fields", "manualTagIds", "editUrl" ], "properties": { "accountId": { "type": "integer" }, "contactId": { "type": "integer" }, "email": { "type": "string" }, "subscriptionStatus": { "type": "string" }, "referenceId": { "type": "integer" }, "fields": { "type": "array", "items": { "type": "object", "required": [ "fieldId", "value", "type", "referenceId" ], "properties": { "fieldId": { "type": "string" }, "value": { "type": "string" }, "type": { "type": "string" }, "referenceId": { "type": "integer" } } } }, "manualTagIds": { "type": "array", "items": { "type": "integer" } }, "editUrl": { "type": "string" } } } } } }, { "name": "upsert-subscribed-contact", "description": "Adds one contact to a KlickTipp account by hand, with its contact-field values in the same call -- the Add Contact screen of the app. Takes an email address, a mobile number, or both. The contact is subscribed at once, through no opt-in process and without a confirmation message, so it is reachable by the next mailing; automations may start. Only for addresses the account may write to by hand: an address that unsubscribed is refused, the account needs the add-contacts permission, and the call counts against its daily import limit. An address the account already has is updated rather than added twice, and the values given overwrite what it held; the answer says so in alreadyExisted. An unknown field ID or tag is refused, never skipped. Use subscribe-contact-via-opt-in-process to let an address opt in through a named process instead.", "tags": [ "Contacts" ], "inputSchema": { "type": "object", "properties": { "email": { "type": [ "null", "string" ], "description": "Email address of the contact; at least one of email and phoneNumber is required", "default": null, "maxLength": 250 }, "phoneNumber": { "type": [ "null", "string" ], "description": "Mobile number with country code, as +49170... or 0049170...; at least one of email and phoneNumber is required", "default": null, "maxLength": 50 }, "tagId": { "type": [ "null", "integer" ], "description": "Manual tag to assign to the contact; omit for none", "default": null, "minimum": 1 }, "fields": { "type": "array", "description": "Contact field values to write with the contact, each {fieldId, value} as get-contact and search-custom-fields name them", "default": null, "items": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1, "maxLength": 15 }, "value": { "type": "string", "maxLength": 65535 } }, "required": [ "fieldId", "value" ], "additionalProperties": false }, "maxItems": 50 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "additionalProperties": false }, "title": "Create Contact", "outputSchema": { "type": "object", "required": [ "accountId", "contactId", "email", "phoneNumber", "subscriptionStatus", "tagId", "fieldIds", "alreadyExisted", "editUrl" ], "properties": { "accountId": { "type": "integer" }, "contactId": { "type": "integer" }, "email": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ] }, "subscriptionStatus": { "type": "string" }, "tagId": { "type": [ "integer", "null" ] }, "fieldIds": { "type": "array", "items": { "type": "string" } }, "alreadyExisted": { "type": "boolean" }, "editUrl": { "type": "string" } } } }, { "name": "tag-contact", "description": "Assigns one existing writable manual tag to one contact. This may immediately start or alter campaigns, autoresponders, outbound events and automations. The caller must explicitly approve those effects. Unknown, foreign or non-manual tags are rejected and never created.", "tags": [ "Contact Tagging" ], "inputSchema": { "type": "object", "properties": { "contactId": { "type": "integer", "description": "Numeric contact ID returned by search-contacts", "minimum": 1 }, "manualTagId": { "type": "integer", "description": "Existing writable manual tag ID; unknown tags are rejected and never created", "minimum": 1 }, "approval": { "type": "string", "description": "Exactly I_ACCEPT_AUTOMATION_EFFECTS: tagging may start campaigns and automations", "enum": [ "I_ACCEPT_AUTOMATION_EFFECTS" ] }, "referenceId": { "type": "integer", "description": "Reference for a multi-value manual tag; use 0 for contact-wide tags", "default": 0, "minimum": 0 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "contactId", "manualTagId", "approval" ], "additionalProperties": false }, "title": "Assign Manual Tag", "outputSchema": { "type": "object", "required": [ "accountId", "contactId", "manualTagId", "referenceId", "action", "automationEffect", "editUrl" ], "properties": { "accountId": { "type": "integer" }, "contactId": { "type": "integer" }, "manualTagId": { "type": "integer" }, "referenceId": { "type": "integer" }, "action": { "type": "string" }, "automationEffect": { "type": "string" }, "editUrl": { "type": "string" } } } }, { "name": "untag-contact", "description": "Removes one existing writable manual tag from one contact. This may immediately alter campaigns, autoresponder queues and automations, so the caller must explicitly approve those effects. Removing a tag does not unsubscribe the contact and changes no subscription or channel state.", "tags": [ "Contact Tagging" ], "inputSchema": { "type": "object", "properties": { "contactId": { "type": "integer", "description": "Numeric contact ID returned by search-contacts", "minimum": 1 }, "manualTagId": { "type": "integer", "description": "Existing writable manual tag ID to remove", "minimum": 1 }, "approval": { "type": "string", "description": "Exactly I_ACCEPT_AUTOMATION_EFFECTS: removal may alter campaigns and automations", "enum": [ "I_ACCEPT_AUTOMATION_EFFECTS" ] }, "referenceId": { "type": "integer", "description": "Reference for a multi-value manual tag; use 0 for contact-wide tags", "default": 0, "minimum": 0 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "contactId", "manualTagId", "approval" ], "additionalProperties": false }, "title": "Remove Manual Tag", "outputSchema": { "type": "object", "required": [ "accountId", "contactId", "manualTagId", "referenceId", "action", "automationEffect", "editUrl" ], "properties": { "accountId": { "type": "integer" }, "contactId": { "type": "integer" }, "manualTagId": { "type": "integer" }, "referenceId": { "type": "integer" }, "action": { "type": "string" }, "automationEffect": { "type": "string" }, "editUrl": { "type": "string" } } } }, { "name": "create-custom-field", "description": "Creates a custom field definition in KlickTipp and returns its ID and the placeholder that renders it in newsletter content. Creating a field stores no value and changes no contact. Fields are never created as a side effect elsewhere, so a field a contact should have a value in has to be created here first. The data type is picked once and for good: it cannot be changed afterwards, so pick the one that matches what will be stored -- a date field for a date, a number field for an amount. multiValue decides whether a contact holds one value PER SUBSCRIPTION (true, the default when omitted) or one value overall (false); it is worth deciding here, because an existing field can only go from true to false and never back. The name has to be unique within the account. The description is what tells a later reader what belongs in the field.", "tags": [ "Data Fields" ], "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the field, which has to be unique within the account", "minLength": 1, "maxLength": 250 }, "type": { "type": "string", "description": "Data type of the field, which decides what can be stored in it and cannot be changed afterwards", "enum": [ "field-single", "field-paragraph", "field-email", "field-number", "field-url", "field-date", "field-time", "field-datetime", "field-html", "field-decimal" ] }, "description": { "type": [ "null", "string" ], "description": "What the field holds, so a person or a model reading it later knows what to write into it", "default": null, "maxLength": 2000 }, "multiValue": { "type": [ "null", "boolean" ], "description": "True: one value per subscription; false: one value overall; omit for true", "default": null }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "name", "type" ], "additionalProperties": false }, "title": "Create Custom Field", "outputSchema": { "type": "object", "required": [ "accountId", "id", "name", "type", "multiValue", "placeholder", "apiFieldId", "category", "description", "metaLabels", "editUrl", "usedBy" ], "properties": { "accountId": { "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "multiValue": { "type": "boolean" }, "placeholder": { "type": "string" }, "apiFieldId": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "metaLabels": { "type": "array", "items": { "type": "string" } }, "editUrl": { "type": "string" }, "usedBy": { "type": "array", "items": { "type": "string" } } } } }, { "name": "delete-custom-field", "description": "Deletes a custom field definition in KlickTipp and with it every value the contacts of the account hold in that field. This destroys contact data and cannot be undone, so only call it for a field the user has explicitly asked to delete. Only fields the account created itself can be deleted; the global fields every KlickTipp account has are refused. A field that opt-in forms, automations or other entities still use is refused as well, and the refusal names them, so nothing that reads the field breaks silently. The placeholder of a deleted field renders an empty value wherever content still carries it.", "tags": [ "Data Fields" ], "inputSchema": { "type": "object", "properties": { "customFieldId": { "type": "string", "description": "ID of the field to delete", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9_]+$" }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "customFieldId" ], "additionalProperties": false }, "title": "Delete Custom Field", "outputSchema": { "type": "object", "required": [ "accountId", "customFieldId", "name", "deleted", "placeholder" ], "properties": { "accountId": { "type": "integer" }, "customFieldId": { "type": "string" }, "name": { "type": "string" }, "deleted": { "type": "boolean" }, "placeholder": { "type": "string" } } } }, { "name": "get-custom-field", "description": "Returns one custom field definition of a KlickTipp account: its name and data type, the placeholder that renders the value of the receiving contact in newsletter content, the key the public API addresses it with, what the account wrote about what the field holds, its internal note, group and labels, the field its values are copied to, and whether a contact can hold more than one value in it. This returns the definition -- what a contact has stored in the field is read through the contact tools.", "tags": [ "Data Fields" ], "inputSchema": { "type": "object", "properties": { "customFieldId": { "type": "string", "description": "Field ID: a number for the account's own field, a name such as \"FirstName\" for a global one", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9_]+$" }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "customFieldId" ], "additionalProperties": false }, "title": "Get Custom Field", "outputSchema": { "type": "object", "required": [ "accountId", "id", "name", "type", "isGlobal", "multiValue", "placeholder", "apiFieldId", "category", "description", "notes", "metaLabels", "copyToFieldId", "requestName", "editUrl" ], "properties": { "accountId": { "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "isGlobal": { "type": "boolean" }, "multiValue": { "type": "boolean" }, "placeholder": { "type": "string" }, "apiFieldId": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "notes": { "type": "string" }, "metaLabels": { "type": "array", "items": { "type": "string" } }, "copyToFieldId": { "type": "string" }, "requestName": { "type": "string" }, "editUrl": { "type": "string" } } } }, { "name": "search-custom-fields", "description": "Lists the custom field definitions of a KlickTipp account with ID, name, data type, the placeholder that renders the value of the receiving contact in newsletter content, and the group the account sorted the field into. Fields the account created itself come first, newest first, followed by the global fields every KlickTipp account has, such as first name or city; the global ones are marked with isGlobal and cannot be changed or deleted. Can be narrowed by a text the name has to contain, by data type, and to the fields the write tools may touch. This lists definitions -- what a contact has stored in a field is read through the contact tools.", "tags": [ "Data Fields" ], "inputSchema": { "type": "object", "properties": { "query": { "type": [ "null", "string" ], "description": "Text the name of a field has to contain; omit to list them all", "default": null, "maxLength": 250 }, "types": { "type": [ "array", "null" ], "description": "Only fields of these data types, for example [\"field-date\", \"field-datetime\"]; omit for every type", "default": null, "items": { "type": "string", "enum": [ "field-single", "field-paragraph", "field-email", "field-number", "field-url", "field-date", "field-time", "field-datetime", "field-html", "field-decimal" ] }, "uniqueItems": true }, "onlyWritable": { "type": [ "null", "boolean" ], "description": "Only the account's own fields, the ones the write tools may touch; omit to include the global fields", "default": null }, "limit": { "type": [ "null", "integer" ], "description": "How many fields to return at most, 1 to 200, 50 by default", "default": null, "minimum": 1, "maximum": 200 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "additionalProperties": false }, "title": "Search Custom Fields", "outputSchema": { "type": "object", "required": [ "accountId", "count", "totalCount", "hasMore", "customFields" ], "properties": { "accountId": { "type": "integer" }, "count": { "type": "integer" }, "totalCount": { "type": "integer" }, "hasMore": { "type": "boolean" }, "customFields": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "isGlobal", "multiValue", "placeholder", "apiFieldId", "category", "editUrl" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "isGlobal": { "type": "boolean" }, "multiValue": { "type": "boolean" }, "placeholder": { "type": "string" }, "apiFieldId": { "type": "string" }, "category": { "type": "string" }, "editUrl": { "type": "string" } } } } } } }, { "name": "update-custom-field", "description": "Changes the name, description, group, labels, cardinality, subscription-email key, note or copy target of a custom field. Only what is passed is written; an empty string clears a text setting. The data type cannot be changed and is refused: an existing field keeps the type its stored values were written in. multiValue false collapses the field to ONE value per contact and DELETES the extra values contacts hold per subscription -- ask the person first, it cannot be undone and true is then refused for good. requestName is the key a contact writes as \"key = value\" in the body of a subscription email to fill this field; it addresses the field, so two fields sharing one means the first wins. copyToFieldId must name a field of a compatible type or the change is refused. Only fields the account created itself can be changed; the global ones are refused.", "tags": [ "Data Fields" ], "inputSchema": { "type": "object", "properties": { "customFieldId": { "type": "string", "description": "ID of the field to change", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9_]+$" }, "name": { "type": [ "null", "string" ], "description": "New name of the field, which has to stay unique within the account; omit to keep the current one", "default": null, "maxLength": 250 }, "description": { "type": [ "null", "string" ], "description": "New description of what the field holds; omit to keep the current one", "default": null, "maxLength": 2000 }, "category": { "type": [ "null", "string" ], "description": "Group in the app; empty string sorts into none; omit to keep", "default": null, "maxLength": 250 }, "metaLabels": { "type": [ "array", "null" ], "description": "New set of labels of the field, which replaces the current one; omit to keep the current labels", "default": null, "items": { "type": "string", "maxLength": 250 }, "maxItems": 50 }, "multiValue": { "type": [ "null", "boolean" ], "description": "False collapses the field to one value per contact and DELETES the others; true is refused on a field that is already false; omit to keep", "default": null }, "requestName": { "type": [ "null", "string" ], "description": "Key this field is addressed by in a subscription email body; empty string removes it; omit to keep", "default": null, "maxLength": 250 }, "notes": { "type": [ "null", "string" ], "description": "Internal note on the field, which nobody outside the account sees; empty string removes it; omit to keep", "default": null, "maxLength": 1000 }, "copyToFieldId": { "type": [ "null", "string" ], "description": "ID of the field every value written here is also copied into; empty string stops the copying; omit to keep", "default": null, "maxLength": 100, "pattern": "^[A-Za-z0-9_]*$" }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "customFieldId" ], "additionalProperties": false }, "title": "Update Custom Field", "outputSchema": { "type": "object", "required": [ "accountId", "id", "name", "type", "multiValue", "placeholder", "apiFieldId", "category", "description", "metaLabels", "editUrl", "usedBy" ], "properties": { "accountId": { "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "multiValue": { "type": "boolean" }, "placeholder": { "type": "string" }, "apiFieldId": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "metaLabels": { "type": "array", "items": { "type": "string" } }, "editUrl": { "type": "string" }, "usedBy": { "type": "array", "items": { "type": "string" } } } } }, { "name": "create-opt-in-process", "description": "Creates a KlickTipp opt-in process (also called subscription process or subscriber list) and the confirmation email that belongs to it, which the platform always creates with it. Takes the same settings as update-opt-in-process except the change-email role. copyFromOptInProcessId copies an existing process including the text of its confirmation email, and the arguments given here still win over the copy. The new process is empty and sends nothing until a form, an automation or an API call subscribes someone to it. Single opt-in subscribes contacts without confirming, which is not permitted everywhere - ask before setting it. The answer carries the new ID and confirmationEmailId; the confirmation email tools write that email.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the new process; must be free within the account", "minLength": 1, "maxLength": 250 }, "notes": { "type": [ "null", "string" ], "description": "Internal note, not visible to contacts", "default": null, "maxLength": 2000 }, "optInMode": { "type": [ "null", "string" ], "description": "\"double\" for a confirmation email, \"single\" without one; defaults to double", "default": null, "enum": [ "double", "single" ] }, "pendingRedirectUrl": { "type": [ "null", "string" ], "description": "URL a contact reaches after subscribing, before confirming; omit for the KlickTipp page", "default": null, "maxLength": 2000 }, "confirmedRedirectUrl": { "type": [ "null", "string" ], "description": "URL a contact reaches after confirming; omit for the KlickTipp page", "default": null, "maxLength": 2000 }, "resendConfirmationEmail": { "type": [ "null", "boolean" ], "description": "Whether an already pending contact receives the confirmation email again on a repeated subscription", "default": null }, "deletePendingSubscribersAfterDays": { "type": [ "null", "integer" ], "description": "Days after which unconfirmed contacts are deleted, one of 0, 1, 3, 7, 14; 0 keeps them", "default": null, "enum": [ 0, 1, 3, 7, 14 ] }, "metaLabels": { "type": "array", "description": "Labels of the new process", "default": null, "items": { "type": "string", "maxLength": 250 }, "maxItems": 50 }, "pendingPageParameters": { "type": "object", "description": "Query parameters appended to pendingRedirectUrl, by the name each is appended under; needs pendingRedirectUrl in the same call", "default": null, "properties": { "subscriberParameterName": { "type": "string", "maxLength": 100 }, "emailParameterName": { "type": "string", "maxLength": 100 }, "listParameterName": { "type": "string", "maxLength": 100 }, "subscriberKeyParameterName": { "type": "string", "maxLength": 100 } }, "additionalProperties": false }, "confirmedPageParameters": { "type": "object", "description": "Query parameters appended to confirmedRedirectUrl, by the name each is appended under; needs confirmedRedirectUrl in the same call", "default": null, "properties": { "subscriberParameterName": { "type": "string", "maxLength": 100 }, "emailParameterName": { "type": "string", "maxLength": 100 }, "listParameterName": { "type": "string", "maxLength": 100 }, "subscriberKeyParameterName": { "type": "string", "maxLength": 100 }, "referralLinkParameterName": { "type": "string", "maxLength": 100, "description": "Name the referral link is appended under; only together with referralLinkId" }, "referralLinkId": { "type": "integer", "minimum": 0, "description": "ID of the account's own referral-link tool, as get-opt-in-process reports it; 0 means no referral link, and then referralLinkParameterName has to be empty too" } }, "additionalProperties": false }, "pendingUtmParameters": { "type": "object", "description": "Campaign tracking values appended to pendingRedirectUrl, by query name; the value, not the name; needs pendingRedirectUrl in the same call", "default": null, "properties": { "utm_source": { "type": "string", "maxLength": 200 }, "utm_medium": { "type": "string", "maxLength": 200 }, "utm_campaign": { "type": "string", "maxLength": 200 }, "utm_term": { "type": "string", "maxLength": 200 }, "utm_content": { "type": "string", "maxLength": 200 } }, "additionalProperties": false }, "confirmedUtmParameters": { "type": "object", "description": "The same for confirmedRedirectUrl; needs confirmedRedirectUrl in the same call", "default": null, "properties": { "utm_source": { "type": "string", "maxLength": 200 }, "utm_medium": { "type": "string", "maxLength": 200 }, "utm_campaign": { "type": "string", "maxLength": 200 }, "utm_term": { "type": "string", "maxLength": 200 }, "utm_content": { "type": "string", "maxLength": 200 } }, "additionalProperties": false }, "copyFromOptInProcessId": { "type": [ "null", "integer" ], "description": "Existing process to copy settings and confirmation email from; the arguments above still win", "default": null, "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "name" ], "additionalProperties": false }, "title": "Create Opt-In Process", "outputSchema": { "type": "object", "required": [ "id", "accountId", "name", "isDefaultProcess", "optInMode", "createdAt", "confirmationEmailId", "resendConfirmationEmail", "useForChangeEmail", "deletePendingSubscribersAfterDays", "pendingRedirectUrl", "confirmedRedirectUrl", "metaLabels", "notes", "pendingPageParameters", "confirmedPageParameters", "pendingUtmParameters", "confirmedUtmParameters", "editUrl" ], "properties": { "id": { "type": "integer" }, "accountId": { "type": "integer" }, "name": { "type": "string" }, "isDefaultProcess": { "type": "boolean" }, "optInMode": { "type": "string" }, "createdAt": { "type": "string" }, "confirmationEmailId": { "type": "integer" }, "resendConfirmationEmail": { "type": "boolean" }, "useForChangeEmail": { "type": "boolean" }, "deletePendingSubscribersAfterDays": { "type": "integer" }, "pendingRedirectUrl": { "type": "string" }, "confirmedRedirectUrl": { "type": "string" }, "metaLabels": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "pendingPageParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "confirmedPageParameters": { "type": "object", "additionalProperties": { "type": [ "string", "integer" ] } }, "pendingUtmParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "confirmedUtmParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "editUrl": { "type": "string" } } } }, { "name": "delete-opt-in-process", "description": "Deletes one KlickTipp opt-in process (also called subscription process or subscriber list) together with its confirmation email. The contacts that subscribed through it keep their subscription and are not deleted. Refused for the default process of the account, and for a process that forms, campaigns or other entities still refer to -- the refusal names what refers to it, so those can be pointed elsewhere first. This cannot be undone, so only call it for a process the user has explicitly asked to delete, named by the ID that get-opt-in-process reports.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process to delete", "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId" ], "additionalProperties": false }, "title": "Delete Opt-In Process", "outputSchema": { "type": "object", "required": [ "accountId", "id", "name" ], "properties": { "accountId": { "type": "integer" }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, { "name": "get-opt-in-confirmation-email", "description": "Reads who the confirmation email of a double opt-in process comes from: its subject, the sender name and address, reply-to, CC and BCC, and the sender domain. It also names what may be chosen: senderEmailOptions are the addresses the account can send from, senderDomainOptions the domains it may pick between, empty when it has no choice. An empty stored sender or reply-to is reported as the account's own address; senderIdentity reports its current status and concrete choices. The body is not part of this answer -- it is get-opt-in-confirmation-email-content. A confirmation email is not a drag-and-drop document, so the block tools do not accept it; the answer carries bodyIsEditable false for that reason and an editUrl into the KlickTipp editor. Single opt-in processes still have this email stored; it is simply not sent. Change it with update-opt-in-confirmation-email.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process whose confirmation email is read", "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId" ], "additionalProperties": false }, "title": "Get Opt-In Confirmation Email", "outputSchema": { "type": "object", "required": [ "emailId", "optInProcessId", "subject", "senderName", "senderEmail", "replyToEmail", "ccEmail", "bccEmail", "senderDomain", "senderEmailOptions", "senderDomainOptions", "senderIdentity", "bodyIsEditable", "editUrl" ], "properties": { "emailId": { "type": "integer" }, "optInProcessId": { "type": "integer" }, "subject": { "type": "string" }, "senderName": { "type": "string" }, "senderEmail": { "type": "string" }, "replyToEmail": { "type": "string" }, "ccEmail": { "type": "string" }, "bccEmail": { "type": "string" }, "senderDomain": { "type": "string" }, "senderEmailOptions": { "type": "array", "items": { "type": "string" } }, "senderDomainOptions": { "type": "array", "items": { "type": "string" } }, "senderIdentity": { "type": "object", "required": [ "effectiveSenderEmail", "customerDomain", "normalizedSenderDomain", "status", "isUsable", "senderEmailOptions", "senderDomainOptions" ], "properties": { "effectiveSenderEmail": { "type": [ "string", "null" ] }, "customerDomain": { "type": [ "string", "null" ] }, "normalizedSenderDomain": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "ready", "address-not-configured", "address-not-confirmed", "address-not-usable", "address-blocked", "domain-not-configured", "domain-not-verified", "domain-not-yet-usable", "domain-mismatch", null ] }, "isUsable": { "type": [ "boolean", "null" ] }, "senderEmailOptions": { "type": "array", "items": { "type": "string" } }, "senderDomainOptions": { "type": "array", "items": { "type": "string" } } } }, "bodyIsEditable": { "type": "boolean" }, "editUrl": { "type": "string" } } } }, { "name": "get-opt-in-confirmation-email-content", "description": "Reads the body of the confirmation email a double opt-in process sends: its subject, its HTML body and its plain-text body, and which of the two it actually sends. Both bodies are always returned, because which one a recipient sees is their mail client's choice. This email is not a drag-and-drop document and the block tools do not work on it -- its text is rich text, written with update-opt-in-confirmation-email-content or by hand in the KlickTipp editor the answer links to. Sender, reply-to and the rest are get-opt-in-confirmation-email.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process whose confirmation email is read", "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId" ], "additionalProperties": false }, "title": "Get Opt-In Confirmation Email Content", "outputSchema": { "type": "object", "required": [ "emailId", "optInProcessId", "subject", "contentType", "html", "plain", "validationMessages", "stored", "editUrl" ], "properties": { "emailId": { "type": "integer" }, "optInProcessId": { "type": "integer" }, "subject": { "type": "string" }, "contentType": { "type": "string" }, "html": { "type": "string" }, "plain": { "type": "string" }, "validationMessages": { "type": "array", "items": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "stored": { "type": "boolean" }, "editUrl": { "type": "string" } } } }, { "name": "get-opt-in-process", "description": "Returns the configuration of a single KlickTipp opt-in process (also called subscription process or subscriber list), looked up by its numeric ID: name, opt-in mode, confirmation email ID, redirect URLs with their query and UTM parameters, pending subscriber deletion, labels and notes. Reads from the account the access token belongs to, or from one of its subaccounts when an account ID is given.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process, as shown in the KlickTipp app URL", "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId" ], "additionalProperties": false }, "title": "Get Opt-In Process", "outputSchema": { "type": "object", "required": [ "id", "accountId", "name", "isDefaultProcess", "optInMode", "createdAt", "confirmationEmailId", "resendConfirmationEmail", "useForChangeEmail", "deletePendingSubscribersAfterDays", "pendingRedirectUrl", "confirmedRedirectUrl", "metaLabels", "notes", "pendingPageParameters", "confirmedPageParameters", "pendingUtmParameters", "confirmedUtmParameters", "editUrl" ], "properties": { "id": { "type": "integer" }, "accountId": { "type": "integer" }, "name": { "type": "string" }, "isDefaultProcess": { "type": "boolean" }, "optInMode": { "type": "string" }, "createdAt": { "type": "string" }, "confirmationEmailId": { "type": "integer" }, "resendConfirmationEmail": { "type": "boolean" }, "useForChangeEmail": { "type": "boolean" }, "deletePendingSubscribersAfterDays": { "type": "integer" }, "pendingRedirectUrl": { "type": "string" }, "confirmedRedirectUrl": { "type": "string" }, "metaLabels": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "pendingPageParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "confirmedPageParameters": { "type": "object", "additionalProperties": { "type": [ "string", "integer" ] } }, "pendingUtmParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "confirmedUtmParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "editUrl": { "type": "string" } } } }, { "name": "preview-opt-in-confirmation-email", "description": "Displays the confirmation email of an opt-in process in an MCP App, so it can be looked at before a contact gets it. Shows the body as STORED: the signature, the confirmation link and the recipient's own data behind the placeholders are added per recipient when it is sent, so they are not in this picture and their absence is not a fault. A plain-text-only email is shown as its text. Changes nothing and creates no contact -- unlike the preview screen of the app, which makes a preview contact. The result carries contentHtml for hosts without MCP Apps support; to receive a real one, use send-opt-in-confirmation-email-test.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process whose confirmation email is shown", "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId" ], "additionalProperties": false }, "title": "Preview Opt-In Confirmation Email", "outputSchema": { "type": "object", "required": [ "accountId", "optInProcessId", "emailId", "subject", "contentType", "contentHtml", "editUrl" ], "properties": { "accountId": { "type": "integer" }, "optInProcessId": { "type": "integer" }, "emailId": { "type": "integer" }, "subject": { "type": "string" }, "contentType": { "type": "string" }, "contentHtml": { "type": "string" }, "editUrl": { "type": "string" } } } }, { "name": "search-opt-in-processes", "description": "Searches the active KlickTipp opt-in processes (also called subscription processes or subscriber lists) of an account, sorted by name, with ID, name, opt-in mode and the flags that tell them apart. Deleted processes are left out. Lists the account the access token belongs to, or one of its subaccounts when an account ID is given. The full configuration of a single entry is get-opt-in-process.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "query": { "type": [ "null", "string" ], "description": "Case-insensitive name fragment to search for; omit to return every active process", "default": null, "maxLength": 250 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "additionalProperties": false }, "title": "Search Opt-In Processes", "outputSchema": { "type": "object", "required": [ "accountId", "count", "optInProcesses" ], "properties": { "accountId": { "type": "integer" }, "count": { "type": "integer" }, "optInProcesses": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "isDefaultProcess", "optInMode", "resendConfirmationEmail", "useForChangeEmail", "createdAt", "confirmationEmailId", "editUrl" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "isDefaultProcess": { "type": "boolean" }, "optInMode": { "type": "string" }, "resendConfirmationEmail": { "type": "boolean" }, "useForChangeEmail": { "type": "boolean" }, "createdAt": { "type": "string" }, "confirmationEmailId": { "type": "integer" }, "editUrl": { "type": "string" } } } } } } }, { "name": "send-opt-in-confirmation-email-test", "description": "Sends the confirmation email of an opt-in process as a test to a single address, so its text can be read before a contact gets it -- the same send the test dialog of KlickTipp performs. Any address may receive one, and an address that is not a contact of the account yet becomes one and is tagged as a test recipient, which can start automations; name the address and say what it will become before calling this. The confirmation link in a test does not confirm anybody. Nothing about the opt-in process changes, and no contact of it is a recipient. Read the body first with get-opt-in-confirmation-email-content.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process whose confirmation email is sent", "minimum": 1 }, "recipientEmail": { "type": "string", "description": "Address the test goes to; becomes a contact of the account if it is not one yet", "minLength": 3, "maxLength": 250 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId", "recipientEmail" ], "additionalProperties": false }, "title": "Send Opt-In Confirmation Email Test", "outputSchema": { "type": "object", "required": [ "accountId", "optInProcessId", "emailId", "subject", "recipientEmail", "messages", "warnings" ], "properties": { "accountId": { "type": "integer" }, "optInProcessId": { "type": "integer" }, "emailId": { "type": "integer" }, "subject": { "type": "string" }, "recipientEmail": { "type": "string" }, "messages": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } } } }, { "name": "update-opt-in-confirmation-email", "description": "Changes the settings of the confirmation email a double opt-in process sends: subject, sender name and address, reply-to, CC, BCC and sender domain. Only the arguments that are given are written, except that senderDomain may be normalized when account domain state changed. A sender address has to be configured and covered by a live verified domain. For an ordinary sender address, senderDomain is checked and derived when omitted; a dispatch profile keeps deciding both values itself. The body is not written here: that is update-opt-in-confirmation-email-content, and the block tools do not accept this email at all. This email is the legal record of a contact's consent in many countries: change its sender or subject only when the user asked for it, and say what was changed.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process whose confirmation email is changed", "minimum": 1 }, "subject": { "type": [ "null", "string" ], "description": "Subject line of the confirmation email", "default": null, "minLength": 1, "maxLength": 250 }, "senderName": { "type": [ "null", "string" ], "description": "Name the email comes from", "default": null, "minLength": 1, "maxLength": 250 }, "senderEmail": { "type": [ "null", "string" ], "description": "Configured address the email comes from, or empty for the account's own address", "default": null, "maxLength": 250 }, "replyToEmail": { "type": [ "null", "string" ], "description": "Address a reply goes to; empty string returns it to the account's own address", "default": null, "maxLength": 250 }, "ccEmail": { "type": [ "null", "string" ], "description": "Address that receives a copy; empty string removes it", "default": null, "maxLength": 250 }, "bccEmail": { "type": [ "null", "string" ], "description": "Address that receives a blind copy; empty string removes it", "default": null, "maxLength": 250 }, "senderDomain": { "type": [ "null", "string" ], "description": "Domain the email is sent through; omit to derive it from the resulting sender address", "default": null, "maxLength": 250 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId" ], "additionalProperties": false }, "title": "Update Opt-In Confirmation Email", "outputSchema": { "type": "object", "required": [ "emailId", "optInProcessId", "subject", "senderName", "senderEmail", "replyToEmail", "ccEmail", "bccEmail", "senderDomain", "senderEmailOptions", "senderDomainOptions", "senderIdentity", "bodyIsEditable", "editUrl" ], "properties": { "emailId": { "type": "integer" }, "optInProcessId": { "type": "integer" }, "subject": { "type": "string" }, "senderName": { "type": "string" }, "senderEmail": { "type": "string" }, "replyToEmail": { "type": "string" }, "ccEmail": { "type": "string" }, "bccEmail": { "type": "string" }, "senderDomain": { "type": "string" }, "senderEmailOptions": { "type": "array", "items": { "type": "string" } }, "senderDomainOptions": { "type": "array", "items": { "type": "string" } }, "senderIdentity": { "type": "object", "required": [ "effectiveSenderEmail", "customerDomain", "normalizedSenderDomain", "status", "isUsable", "senderEmailOptions", "senderDomainOptions" ], "properties": { "effectiveSenderEmail": { "type": [ "string", "null" ] }, "customerDomain": { "type": [ "string", "null" ] }, "normalizedSenderDomain": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "ready", "address-not-configured", "address-not-confirmed", "address-not-usable", "address-blocked", "domain-not-configured", "domain-not-verified", "domain-not-yet-usable", "domain-mismatch", null ] }, "isUsable": { "type": [ "boolean", "null" ] }, "senderEmailOptions": { "type": "array", "items": { "type": "string" } }, "senderDomainOptions": { "type": "array", "items": { "type": "string" } } } }, "bodyIsEditable": { "type": "boolean" }, "editUrl": { "type": "string" } } } }, { "name": "update-opt-in-confirmation-email-content", "description": "Replaces the body of the confirmation email a double opt-in process sends. html and plain are each written whole, not patched, and a part that is not given keeps its text -- so writing only one leaves the email saying two different things to two recipients. Write both. The platform checks the result the way the editor does: errors, such as a missing unsubscribe link or an empty subject, stop the write and are returned in validationMessages with stored false; warnings do not. This email is the legal record of a contact's consent in many countries -- it must still say who is subscribing them to what. Change it only when the user asked for it, and say what changed.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process whose confirmation email is written", "minimum": 1 }, "html": { "type": [ "null", "string" ], "description": "Complete HTML body; replaces the current one, empty string makes the email plain-text only", "default": null, "maxLength": 500000 }, "plain": { "type": [ "null", "string" ], "description": "Complete plain-text body; replaces the current one", "default": null, "maxLength": 500000 }, "subject": { "type": [ "null", "string" ], "description": "Subject line", "default": null, "minLength": 1, "maxLength": 150 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId" ], "additionalProperties": false }, "title": "Update Opt-In Confirmation Email Content", "outputSchema": { "type": "object", "required": [ "emailId", "optInProcessId", "subject", "contentType", "html", "plain", "validationMessages", "stored", "editUrl" ], "properties": { "emailId": { "type": "integer" }, "optInProcessId": { "type": "integer" }, "subject": { "type": "string" }, "contentType": { "type": "string", "enum": [ "plain", "html-and-plain" ] }, "html": { "type": "string" }, "plain": { "type": "string" }, "validationMessages": { "type": "array", "items": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "error", "warning" ] }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "stored": { "type": "boolean" }, "editUrl": { "type": "string" } } } }, { "name": "update-opt-in-process", "description": "Changes the settings of one KlickTipp opt-in process (also called subscription process or subscriber list): name, opt-in mode, redirect URLs with their query and UTM parameters, confirmation resend, change-email role, deletion of unconfirmed contacts, labels and notes. Only the arguments that are given are written, the rest keeps its current value. Settings take effect for contacts subscribing from now on; contacts already in the process are not touched and nothing is sent. Single opt-in subscribes later contacts without confirming, which is not permitted everywhere - ask before setting it. The confirmation email is written with the opt-in confirmation email tools. A page parameter is a NAME the platform fills with contact data; a UTM parameter is a VALUE under a fixed name. Both reach a page only together with that page's URL in the same call. get-opt-in-process reads them.", "tags": [ "Opt-In Processes" ], "inputSchema": { "type": "object", "properties": { "optInProcessId": { "type": "integer", "description": "ID of the opt-in process to change", "minimum": 1 }, "name": { "type": [ "null", "string" ], "description": "New name; omit to keep the current one", "default": null, "minLength": 1, "maxLength": 250 }, "notes": { "type": [ "null", "string" ], "description": "Internal note, not visible to contacts; empty string clears it", "default": null, "maxLength": 2000 }, "optInMode": { "type": [ "null", "string" ], "description": "\"double\" for a confirmation email, \"single\" without one", "default": null, "enum": [ "double", "single" ] }, "pendingRedirectUrl": { "type": [ "null", "string" ], "description": "URL a contact reaches after subscribing, before confirming; empty string restores the KlickTipp page", "default": null, "maxLength": 2000 }, "confirmedRedirectUrl": { "type": [ "null", "string" ], "description": "URL a contact reaches after confirming; empty string restores the KlickTipp page", "default": null, "maxLength": 2000 }, "resendConfirmationEmail": { "type": [ "null", "boolean" ], "description": "Whether an already pending contact receives the confirmation email again on a repeated subscription", "default": null }, "useForChangeEmail": { "type": [ "null", "boolean" ], "description": "Whether this process handles email address changes; true takes that role away from the process that holds it", "default": null }, "deletePendingSubscribersAfterDays": { "type": [ "null", "integer" ], "description": "Days after which unconfirmed contacts are deleted, one of 0, 1, 3, 7, 14; 0 keeps them", "default": null, "enum": [ 0, 1, 3, 7, 14 ] }, "metaLabels": { "type": "array", "description": "Complete list of labels; replaces the existing labels, empty array removes them all", "default": null, "items": { "type": "string", "maxLength": 250 }, "maxItems": 50 }, "pendingPageParameters": { "type": "object", "description": "Query parameters appended to pendingRedirectUrl, by the name each is appended under; needs pendingRedirectUrl in the same call", "default": null, "properties": { "subscriberParameterName": { "type": "string", "maxLength": 100 }, "emailParameterName": { "type": "string", "maxLength": 100 }, "listParameterName": { "type": "string", "maxLength": 100 }, "subscriberKeyParameterName": { "type": "string", "maxLength": 100 } }, "additionalProperties": false }, "confirmedPageParameters": { "type": "object", "description": "Query parameters appended to confirmedRedirectUrl, by the name each is appended under; needs confirmedRedirectUrl in the same call", "default": null, "properties": { "subscriberParameterName": { "type": "string", "maxLength": 100 }, "emailParameterName": { "type": "string", "maxLength": 100 }, "listParameterName": { "type": "string", "maxLength": 100 }, "subscriberKeyParameterName": { "type": "string", "maxLength": 100 }, "referralLinkParameterName": { "type": "string", "maxLength": 100, "description": "Name the referral link is appended under; only together with referralLinkId" }, "referralLinkId": { "type": "integer", "minimum": 0, "description": "ID of the account's own referral-link tool, as get-opt-in-process reports it; 0 means no referral link, and then referralLinkParameterName has to be empty too" } }, "additionalProperties": false }, "pendingUtmParameters": { "type": "object", "description": "Campaign tracking values appended to pendingRedirectUrl, by query name; the value, not the name; needs pendingRedirectUrl in the same call", "default": null, "properties": { "utm_source": { "type": "string", "maxLength": 200 }, "utm_medium": { "type": "string", "maxLength": 200 }, "utm_campaign": { "type": "string", "maxLength": 200 }, "utm_term": { "type": "string", "maxLength": 200 }, "utm_content": { "type": "string", "maxLength": 200 } }, "additionalProperties": false }, "confirmedUtmParameters": { "type": "object", "description": "The same for confirmedRedirectUrl; needs confirmedRedirectUrl in the same call", "default": null, "properties": { "utm_source": { "type": "string", "maxLength": 200 }, "utm_medium": { "type": "string", "maxLength": 200 }, "utm_campaign": { "type": "string", "maxLength": 200 }, "utm_term": { "type": "string", "maxLength": 200 }, "utm_content": { "type": "string", "maxLength": 200 } }, "additionalProperties": false }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "optInProcessId" ], "additionalProperties": false }, "title": "Update Opt-In Process", "outputSchema": { "type": "object", "required": [ "id", "accountId", "name", "isDefaultProcess", "optInMode", "createdAt", "confirmationEmailId", "resendConfirmationEmail", "useForChangeEmail", "deletePendingSubscribersAfterDays", "pendingRedirectUrl", "confirmedRedirectUrl", "metaLabels", "notes", "pendingPageParameters", "confirmedPageParameters", "pendingUtmParameters", "confirmedUtmParameters", "editUrl" ], "properties": { "id": { "type": "integer" }, "accountId": { "type": "integer" }, "name": { "type": "string" }, "isDefaultProcess": { "type": "boolean" }, "optInMode": { "type": "string" }, "createdAt": { "type": "string" }, "confirmationEmailId": { "type": "integer" }, "resendConfirmationEmail": { "type": "boolean" }, "useForChangeEmail": { "type": "boolean" }, "deletePendingSubscribersAfterDays": { "type": "integer" }, "pendingRedirectUrl": { "type": "string" }, "confirmedRedirectUrl": { "type": "string" }, "metaLabels": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "pendingPageParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "confirmedPageParameters": { "type": "object", "additionalProperties": { "type": [ "string", "integer" ] } }, "pendingUtmParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "confirmedUtmParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "editUrl": { "type": "string" } } } }, { "name": "create-manual-tag", "description": "Creates a manual tag in KlickTipp, one that is assigned deliberately rather than by KlickTipp itself. Creating a tag assigns it to nobody and changes no contact. Tags are never created as a side effect elsewhere, so a tag a contact should carry has to be created here first. The name has to be unique within the account. The description is what tells a later reader what the tag means.", "tags": [ "Tags" ], "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the tag, which has to be unique within the account and cannot be a number alone", "minLength": 1, "maxLength": 250 }, "description": { "type": [ "null", "string" ], "description": "What the tag stands for, so a person or a model reading it later knows when to assign it", "default": null, "maxLength": 2000 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "name" ], "additionalProperties": false }, "title": "Create Manual Tag", "outputSchema": { "type": "object", "required": [ "accountId", "id", "name", "description", "type", "isWritable", "multiValue", "editUrl", "usedBy" ], "properties": { "accountId": { "type": "integer" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "isWritable": { "type": "boolean" }, "multiValue": { "type": "boolean" }, "editUrl": { "type": "string" }, "usedBy": { "type": "array", "items": { "type": "string" } } } } }, { "name": "delete-manual-tag", "description": "Deletes a manual tag in KlickTipp and takes it off every contact that carries it. Only manual tags can be deleted; a tag KlickTipp puts on contacts itself is refused. A tag that campaigns, automations or other entities still use is refused as well, and the refusal names them, so nothing that depends on the tag breaks silently. This cannot be undone, so only call it for a tag the user has explicitly asked to delete.", "tags": [ "Tags" ], "inputSchema": { "type": "object", "properties": { "tagId": { "type": "integer", "description": "ID of the manual tag to delete", "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "tagId" ], "additionalProperties": false }, "title": "Delete Manual Tag", "outputSchema": { "type": "object", "required": [ "accountId", "tagId", "name", "deleted", "removedFromContacts" ], "properties": { "accountId": { "type": "integer" }, "tagId": { "type": "integer" }, "name": { "type": "string" }, "deleted": { "type": "boolean" }, "removedFromContacts": { "type": "integer" } } } }, { "name": "get-tag", "description": "Returns one tag of a KlickTipp account with the context needed to tell what it means: its type, whether it can be written, what it stands for, the entity behind it for tags KlickTipp puts on contacts itself, the internal note and labels of the account, how many contacts carry it, and which tags a contact is subscribed to or unsubscribed from when this tag is assigned. Also says whether this is the tag the app marks test contacts with.", "tags": [ "Tags" ], "inputSchema": { "type": "object", "properties": { "tagId": { "type": "integer", "description": "ID of the tag, as shown in the KlickTipp app URL", "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "tagId" ], "additionalProperties": false }, "title": "Get Tag", "outputSchema": { "type": "object", "required": [ "accountId", "id", "name", "type", "isWritable", "isTestContactTag", "multiValue", "description", "notes", "originName", "originId", "metaLabels", "contactCount", "subscribesToTagIds", "unsubscribesFromTagIds", "editUrl" ], "properties": { "accountId": { "type": "integer" }, "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "isWritable": { "type": "boolean" }, "isTestContactTag": { "type": "boolean" }, "multiValue": { "type": "boolean" }, "description": { "type": "string" }, "notes": { "type": "string" }, "originName": { "type": [ "string", "null" ] }, "originId": { "type": [ "integer", "null" ] }, "metaLabels": { "type": "array", "items": { "type": "string" } }, "contactCount": { "type": "integer" }, "subscribesToTagIds": { "type": "array", "items": { "type": "integer" } }, "unsubscribesFromTagIds": { "type": "array", "items": { "type": "integer" } }, "editUrl": { "type": "string" } } } }, { "name": "search-tags", "description": "Lists the tags of a KlickTipp account with ID, name, type, whether they can be written and whether a contact can carry them more than once. Tags are either manual -- created and assigned deliberately -- or put on contacts by KlickTipp itself when something happens, for example a newsletter being sent, opened or clicked; the type says which. Can be narrowed by a text the name has to contain, by type, to the writable ones, by whether a contact can carry a tag once per subscription or only once overall, and to tags with a system role such as the test contact marker. The description of a tag is not part of the list -- use get-tag for that.", "tags": [ "Tags" ], "inputSchema": { "type": "object", "properties": { "query": { "type": [ "null", "string" ], "description": "Text the name of a tag has to contain; omit to list them all", "default": null, "maxLength": 250 }, "type": { "type": [ "null", "string" ], "description": "Only tags of this type, \"tag\" being the manual ones; omit for every type", "default": null, "enum": [ "apikey-subscribed", "automation-finished", "automation-started", "businesscard-subscribed", "campaign-clicked", "campaign-converted", "campaign-opened", "campaign-sent", "campaign-viewed", "digistore-affiliation", "email-clicked", "email-opened", "email-sent", "email-viewed", "event-subscribed", "facebook-audience", "form-subscribed", "kajabi-activated", "kajabi-deactivated", "landing-page-subscribed", "outbound-activated", "payment-chargeback", "payment-completed", "payment-deferred", "payment-expired", "payment-received", "payment-refunded", "payment-subsequent", "plugin-inbound-finished", "plugin-inbound-inprogress", "plugin-inbound-ready", "plugin-inbound-started", "rebill-canceled", "rebill-canceled-lastday", "rebill-resumed", "request-email-subscribed", "request-sms-subscribed", "smartlink", "sms-clicked", "sms-sent", "tag", "taggingpixel-triggered", "unknown" ] }, "onlyWritable": { "type": [ "null", "boolean" ], "description": "Only manual tags the write tools may touch; omit to include the ones KlickTipp sets itself", "default": null }, "multiValue": { "type": [ "null", "boolean" ], "description": "true: tags a contact can carry once per subscription; false: once overall; omit for both", "default": null }, "systemRole": { "type": [ "null", "string" ], "description": "Only tags with this system role; \"test-contact\" marks contacts that receive test emails", "default": null, "enum": [ "test-contact" ] }, "limit": { "type": [ "null", "integer" ], "description": "How many tags to return at most, 1 to 200, 50 by default", "default": null, "minimum": 1, "maximum": 200 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "additionalProperties": false }, "title": "Search Tags", "outputSchema": { "type": "object", "required": [ "accountId", "count", "totalCount", "hasMore", "tags" ], "properties": { "accountId": { "type": "integer" }, "count": { "type": "integer" }, "totalCount": { "type": "integer" }, "hasMore": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "isWritable", "isTestContactTag", "multiValue", "editUrl" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "isWritable": { "type": "boolean" }, "isTestContactTag": { "type": "boolean" }, "multiValue": { "type": "boolean" }, "editUrl": { "type": "string" } } } } } } }, { "name": "update-manual-tag", "description": "Changes the name or the description of a manual tag in KlickTipp. Only manual tags can be changed: a tag KlickTipp puts on contacts itself takes its name from the newsletter, automation or form behind it and is refused. Renaming a tag does not change who carries it and does not break the campaigns and automations that use it, since those refer to its ID -- but the result lists them, because a rename shows up wherever the name is read. Everything else about the tag, including its auto-subscribe configuration and whether it is single value, stays as it is.", "tags": [ "Tags" ], "inputSchema": { "type": "object", "properties": { "tagId": { "type": "integer", "description": "ID of the manual tag to change", "minimum": 1 }, "name": { "type": [ "null", "string" ], "description": "New name of the tag, which has to stay unique within the account; omit to keep the current one", "default": null, "maxLength": 250 }, "description": { "type": [ "null", "string" ], "description": "New description of what the tag stands for; omit to keep the current one", "default": null, "maxLength": 2000 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "tagId" ], "additionalProperties": false }, "title": "Update Manual Tag", "outputSchema": { "type": "object", "required": [ "accountId", "id", "name", "description", "type", "isWritable", "multiValue", "editUrl", "usedBy" ], "properties": { "accountId": { "type": "integer" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "isWritable": { "type": "boolean" }, "multiValue": { "type": "boolean" }, "editUrl": { "type": "string" }, "usedBy": { "type": "array", "items": { "type": "string" } } } } }, { "name": "cancel-newsletter-dispatch", "description": "Takes back the dispatch of an email newsletter, so it becomes a draft again and reaches nobody further. THIS IS THE ANSWER TO \"stop it\", \"cancel the send\" AND \"undo the schedule\" -- it covers both a dispatch that is under way and one that is still waiting for a future moment, which the platform treats as two different things and a caller does not have to. Only while the delivery status says canBeCancelled: once a dispatch is far enough along it cannot be called off, and the refusal says so rather than pretending. What already went out stays out -- this stops what has not been sent yet, it does not recall mail. The newsletter itself, its content and its audience are untouched; only the dispatch is undone, and activating it again is prepare-newsletter-dispatch. Ask first: a dispatch someone set up deliberately is not yours to stop on your own reading of a situation.", "tags": [ "Newsletters" ], "inputSchema": { "type": "object", "properties": { "newsletterId": { "type": "integer", "description": "ID of the newsletter whose dispatch is to be called off", "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "newsletterId" ], "additionalProperties": false }, "title": "Cancel A Newsletter Dispatch", "outputSchema": { "type": "object", "required": [ "newsletterId", "newsletterStatus", "dispatchConfigured", "note" ], "properties": { "newsletterId": { "type": "integer" }, "newsletterStatus": { "type": "string" }, "dispatchConfigured": { "type": "boolean" }, "note": { "type": "string" } } } }, { "name": "configure-newsletter-delivery", "description": "Writes the delivery configuration of an email newsletter in KlickTipp: sender name, sender address, reply address, sending domain and signature. Reports back what is still missing before the newsletter could be sent, together with the sender addresses, sending domains and signatures the account may use. Concrete sender addresses are checked against their live verified domains; changing the address also derives and stores its matching domain. The sender and domain dispatch-profile sources are selected together. This tool neither schedules nor activates anything and reaches no recipient -- activation is a separate tool. Arguments that are left out keep their current value. Only a newsletter that was never scheduled can be configured: any other lifecycle state is refused before anything is written.", "tags": [ "Newsletters" ], "inputSchema": { "type": "object", "properties": { "newsletterId": { "type": "integer", "description": "ID of the newsletter to configure", "minimum": 1 }, "senderNameMode": { "type": [ "null", "string" ], "description": "\"explicit\" (pass senderName), \"account_default\" or \"signature_dispatch_profile\"; omit to keep", "default": null, "enum": [ "explicit", "account_default", "signature_dispatch_profile" ] }, "senderName": { "type": [ "null", "string" ], "description": "Name the recipients see as the sender, for mode \"explicit\" only; omit to keep the current one", "default": null, "maxLength": 250 }, "senderEmailMode": { "type": [ "null", "string" ], "description": "\"explicit\" (pass senderEmail), \"account_default\" or \"signature_dispatch_profile\"; omit to keep", "default": null, "enum": [ "explicit", "account_default", "signature_dispatch_profile" ] }, "senderEmail": { "type": [ "null", "string" ], "description": "Sender address configured for the account; for mode \"explicit\"; omit to keep", "default": null, "maxLength": 250 }, "replyToEmailMode": { "type": [ "null", "string" ], "description": "\"explicit\" (pass replyToEmail), \"account_default\" or \"signature_dispatch_profile\"; omit to keep", "default": null, "enum": [ "explicit", "account_default", "signature_dispatch_profile" ] }, "replyToEmail": { "type": [ "null", "string" ], "description": "Address answers go to, for mode \"explicit\" only; omit to keep the current one", "default": null, "maxLength": 250 }, "senderDomainMode": { "type": [ "null", "string" ], "description": "\"explicit\" (pass senderDomain), \"account_default\" for automatic resolution or \"signature_dispatch_profile\"; omit to keep", "default": null, "enum": [ "explicit", "account_default", "signature_dispatch_profile" ] }, "senderDomain": { "type": [ "null", "string" ], "description": "Matching verified domain; for mode \"explicit\"; omit to derive it when changing the sender address", "default": null, "maxLength": 250 }, "signatureId": { "type": [ "null", "integer" ], "description": "ID of the signature under the newsletter; 0 lets KlickTipp pick one by tagging; omit to keep", "default": null, "minimum": 0 }, "linkTracking": { "type": [ "null", "boolean" ], "description": "Whether KlickTipp rewrites the links so clicks are counted; true is the normal case, omit to keep", "default": null }, "headerLinks": { "type": [ "null", "boolean" ], "description": "Whether KlickTipp puts its own line above the body with browser view, unsubscribe and report-spam links; omit to keep", "default": null }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "newsletterId" ], "additionalProperties": false }, "title": "Configure Newsletter Delivery", "outputSchema": { "type": "object", "required": [ "accountId", "newsletterId", "emailId", "name", "newsletterStatus", "sender", "tracking", "missingRequirements", "readyToSend", "availableSenderAddresses", "availableSenderDomains", "availableSignatures", "contentUrl", "scheduleUrl" ], "properties": { "accountId": { "type": "integer" }, "newsletterId": { "type": "integer" }, "emailId": { "type": "integer" }, "name": { "type": "string" }, "newsletterStatus": { "type": "string" }, "sender": { "type": "object", "required": [ "senderNameMode", "senderName", "senderEmailMode", "senderEmail", "replyToEmailMode", "replyToEmail", "senderDomainMode", "senderDomain", "signature" ], "properties": { "senderNameMode": { "type": "string" }, "senderName": { "type": [ "string", "null" ] }, "senderEmailMode": { "type": "string" }, "senderEmail": { "type": [ "string", "null" ] }, "replyToEmailMode": { "type": "string" }, "replyToEmail": { "type": [ "string", "null" ] }, "senderDomainMode": { "type": "string" }, "senderDomain": { "type": [ "string", "null" ] }, "signature": { "type": "object", "required": [ "mode", "id", "name" ], "properties": { "mode": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } } }, "tracking": { "type": "object", "required": [ "linkTracking", "headerLinks", "linkTrackingCanBeTurnedOff" ], "properties": { "linkTracking": { "type": "boolean" }, "headerLinks": { "type": "boolean" }, "linkTrackingCanBeTurnedOff": { "type": "boolean" } } }, "missingRequirements": { "type": "array", "items": { "type": "string" } }, "readyToSend": { "type": "boolean" }, "availableSenderAddresses": { "type": "array", "items": { "type": "string" } }, "availableSenderDomains": { "type": "array", "items": { "type": "string" } }, "availableSignatures": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "contentUrl": { "type": "string" }, "scheduleUrl": { "type": "string" } } } }, { "name": "create-newsletter-draft", "description": "Creates an email newsletter draft in KlickTipp -- name, subject, optional preheader -- and returns newsletter ID, email ID and deep links. Nothing is sent. A draft has no audience filter yet: an unfiltered audience means every active contact of the account (mode \"all_contacts\"). The subject is the line every recipient sees; changing it later through update-newsletter-draft invalidates the content revisions read before. Body: block tools (update-email-editor-text and siblings). Audience: update-newsletter-draft. Sender: configure-newsletter-delivery. \"splitTest\" makes it a split test, irreversibly, with one variant -- more via add-newsletter-split-test-variant, settings via configure-newsletter-split-test; needs a premium account, \"conversions\"/\"revenue\" the conversion pixel, refused before creation. \"emailEditor\" is fixed at creation; omit it unless the account uses the previous editor.", "tags": [ "Newsletters" ], "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the newsletter, unique within the account", "minLength": 1, "maxLength": 250 }, "subject": { "type": "string", "description": "Subject line, without HTML. It is the line every recipient sees, and no part of it is derived from anything else in this call. Correcting it later is update-newsletter-draft, which invalidates the content revisions read before", "minLength": 1, "maxLength": 998 }, "notes": { "type": [ "null", "string" ], "description": "Internal note about the purpose of this newsletter, never part of the email", "default": null, "maxLength": 1000 }, "preheader": { "type": [ "null", "string" ], "description": "Inbox preview line, at most 120 characters, without HTML; omit to leave it empty. Not part of the content document: an HTML import cannot set it", "default": null, "maxLength": 120 }, "splitTest": { "type": [ "object", "null" ], "description": "Makes the newsletter a split test, irreversibly: \"testSizePercent\" (2-98), \"testDurationHours\" (1-27777), \"winnerBy\" (\"opens\", \"clicks\", \"conversions\", \"revenue\"; the last two need the conversion pixel). All three are required and KlickTipp has no default for any of them, so any value here is a choice somebody made; together they settle what share of real recipients gets a test version and for how long. Needs a premium account; omit for a normal newsletter", "default": null, "properties": { "testSizePercent": { "type": "integer", "minimum": 2, "maximum": 98 }, "testDurationHours": { "type": "integer", "minimum": 1, "maximum": 27777 }, "winnerBy": { "type": "string", "enum": [ "opens", "clicks", "conversions", "revenue" ] } }, "required": [ "testSizePercent", "testDurationHours", "winnerBy" ], "additionalProperties": false }, "emailEditor": { "type": [ "null", "string" ], "description": "Editor the email is created for. Omit it, which means \"drag-and-drop\": that is the editor KlickTipp builds on and the one every content and design tool works with. Pass \"rich-text\" only when the account authors in the previous HTML editor and asked for it. The choice cannot be changed afterwards", "default": null, "enum": [ "drag-and-drop", "rich-text" ] }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "name", "subject" ], "additionalProperties": false }, "title": "Create Newsletter Draft", "outputSchema": { "type": "object", "required": [ "accountId", "newsletterId", "emailId", "name", "newsletterStatus", "emailEditor", "subject", "preheader", "contentRevisionInvalidated", "notes", "hasContent", "contentPublished", "audience", "sender", "editUrl", "contentUrl" ], "properties": { "accountId": { "type": "integer" }, "newsletterId": { "type": "integer" }, "emailId": { "type": "integer" }, "name": { "type": "string" }, "newsletterStatus": { "type": "string" }, "emailEditor": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "contentRevisionInvalidated": { "type": "boolean" }, "notes": { "type": "string" }, "hasContent": { "type": "boolean" }, "contentPublished": { "type": "boolean" }, "audience": { "type": "object", "required": [ "includeTags", "includeTagsMatch", "excludeTags", "excludeTagsMatch", "savedAudience", "mode" ], "properties": { "includeTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } }, "includeTagsMatch": { "type": "string" }, "excludeTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } }, "excludeTagsMatch": { "type": "string" }, "savedAudience": { "type": [ "object", "null" ], "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "mode": { "type": "string" } } }, "sender": { "type": "object", "required": [ "senderNameMode", "senderName", "senderEmailMode", "senderEmail", "replyToEmailMode", "replyToEmail", "senderDomainMode", "senderDomain", "signature" ], "properties": { "senderNameMode": { "type": "string" }, "senderName": { "type": [ "string", "null" ] }, "senderEmailMode": { "type": "string" }, "senderEmail": { "type": [ "string", "null" ] }, "replyToEmailMode": { "type": "string" }, "replyToEmail": { "type": [ "string", "null" ] }, "senderDomainMode": { "type": "string" }, "senderDomain": { "type": [ "string", "null" ] }, "signature": { "type": "object", "required": [ "mode", "id", "name" ], "properties": { "mode": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } } }, "editUrl": { "type": "string" }, "contentUrl": { "type": "string" } } } }, { "name": "delete-newsletter-draft", "description": "Deletes an email newsletter draft in KlickTipp, along with its email, its audience conditions and its system tags. Only drafts can be deleted: a newsletter that is scheduled, on its way out or already sent is refused, and so is one that other entities still refer to -- the refusal names them. This cannot be undone, so only call it for a newsletter the user has explicitly asked to delete.", "tags": [ "Newsletters" ], "inputSchema": { "type": "object", "properties": { "newsletterId": { "type": "integer", "description": "ID of the newsletter to delete", "minimum": 1 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "newsletterId" ], "additionalProperties": false }, "title": "Delete Newsletter Draft", "outputSchema": { "type": "object", "required": [ "accountId", "newsletterId", "name", "deleted", "deletedEmailId" ], "properties": { "accountId": { "type": "integer" }, "newsletterId": { "type": "integer" }, "name": { "type": "string" }, "deleted": { "type": "boolean" }, "deletedEmailId": { "type": "integer" } } } }, { "name": "get-newsletter", "description": "Returns one email newsletter of a KlickTipp account: identity, lifecycle state, editor type, split-test flag and deep links. Everything else is a projection requested through \"include\": \"metadata\" (name, note, labels, subject), \"audience\", \"deliveryConfiguration\" (sender, reply address, signature), \"deliveryStatus\" (send date, recipients, counters, what is missing), \"audienceReach\" (contacts it would reach now) and \"conversionPixel\" (tracking snippets for a thank-you page, one per sender domain; hand one to the user verbatim). The body is not here -- read it with get-email-editor-content. Reads only; requested projections are answered whole or the call fails. A split test has one email per variant and no single email: emailId, contentUrl and metadata.subject are null, splitTestVariants lists the variants, and deliveryConfiguration needs one of their editorUrl.", "tags": [ "Newsletters" ], "inputSchema": { "type": "object", "properties": { "newsletterId": { "type": "integer", "description": "ID of the newsletter, as shown in the KlickTipp app URL", "minimum": 1 }, "include": { "type": "array", "description": "Projections to add: \"metadata\", \"audience\", \"deliveryConfiguration\", \"deliveryStatus\", \"audienceReach\", \"conversionPixel\"; omit for identity and lifecycle only. The body is get-email-editor-content", "default": null, "items": { "type": "string", "enum": [ "metadata", "audience", "deliveryConfiguration", "deliveryStatus", "audienceReach", "conversionPixel" ] }, "maxItems": 6, "uniqueItems": true }, "editorUrl": { "type": [ "null", "string" ], "description": "Editor URL naming one variant of a split test, from splitTestVariants; omit for a newsletter with a single email", "default": null, "minLength": 12, "maxLength": 500 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "newsletterId" ], "additionalProperties": false }, "title": "Get Newsletter", "outputSchema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "accountId", "newsletterId", "emailId", "createdAt", "newsletterStatus", "usageType", "emailEditor", "isSplitTest", "editUrl", "contentUrl", "scheduleUrl", "statisticsUrl" ], "properties": { "accountId": { "type": "integer" }, "newsletterId": { "type": "integer" }, "emailId": { "type": [ "integer", "null" ], "description": "Null for a split test: each variant has its own email." }, "createdAt": { "type": "string" }, "newsletterStatus": { "type": "string", "enum": [ "draft", "scheduled", "outgoing", "sent" ] }, "usageType": { "type": "string", "enum": [ "newsletter", "newsletter-split-test" ] }, "emailEditor": { "type": [ "string", "null" ], "enum": [ "drag-and-drop", "rich-text", null ] }, "isSplitTest": { "type": "boolean" }, "splitTestVariants": { "type": [ "array", "null" ], "description": "The variants of a split test, each with the editorUrl that reads it; null for a standard newsletter.", "items": { "type": "object", "required": [ "emailId", "label", "name", "subject", "editorUrl" ], "properties": { "emailId": { "type": "integer" }, "label": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "editorUrl": { "type": "string" } } } }, "editUrl": { "type": "string" }, "contentUrl": { "type": [ "string", "null" ] }, "scheduleUrl": { "type": "string" }, "statisticsUrl": { "type": "string" }, "metadata": { "type": "object" }, "audience": { "type": "object" }, "deliveryConfiguration": { "type": "object", "properties": { "senderIdentity": { "type": "object", "required": [ "effectiveSenderEmail", "customerDomain", "normalizedSenderDomain", "status", "isUsable", "senderEmailOptions", "senderDomainOptions" ], "properties": { "effectiveSenderEmail": { "type": [ "string", "null" ] }, "customerDomain": { "type": [ "string", "null" ] }, "normalizedSenderDomain": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "ready", "address-not-configured", "address-not-confirmed", "address-not-usable", "address-blocked", "domain-not-configured", "domain-not-verified", "domain-not-yet-usable", "domain-mismatch", null ] }, "isUsable": { "type": [ "boolean", "null" ] }, "senderEmailOptions": { "type": "array", "items": { "type": "string" } }, "senderDomainOptions": { "type": "array", "items": { "type": "string" } } } } } }, "deliveryStatus": { "type": "object", "required": [ "accountId", "observedAt", "newsletterId", "name", "newsletterStatus", "dispatchConfigured", "mode", "sendDate", "sendProcessFinishedAt", "estimatedRecipients", "sentCount", "failedCount", "totalOpenCount", "uniqueOpenCount", "totalClickCount", "uniqueClickCount", "hardBounceCount", "softBounceCount", "spamBounceCount", "spamComplaintCount", "unsubscriptionCount", "canBeCancelled", "missingRequirements", "readyToSend", "scheduleUrl", "statisticsUrl" ], "properties": { "accountId": { "type": "integer" }, "observedAt": { "type": "string", "description": "When these counters were read; bounces and complaints arrive later." }, "newsletterId": { "type": "integer" }, "name": { "type": "string" }, "newsletterStatus": { "type": "string", "enum": [ "draft", "scheduled", "outgoing", "sent" ] }, "dispatchConfigured": { "type": "boolean" }, "mode": { "type": [ "string", "null" ], "enum": [ "immediate", "scheduled", null ], "description": "Null while no dispatch is set up; never an empty string." }, "sendDate": { "type": [ "string", "null" ], "description": "Null for a draft, even one whose schedule was set and called off." }, "sendProcessFinishedAt": { "type": [ "string", "null" ] }, "estimatedRecipients": { "type": "integer", "minimum": 0 }, "sentCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "totalOpenCount": { "type": "integer", "minimum": 0, "description": "Opens as events: one person opening twice counts twice." }, "uniqueOpenCount": { "type": "integer", "minimum": 0, "description": "Opens counted once per contact." }, "totalClickCount": { "type": "integer", "minimum": 0 }, "uniqueClickCount": { "type": "integer", "minimum": 0 }, "hardBounceCount": { "type": "integer", "minimum": 0 }, "softBounceCount": { "type": "integer", "minimum": 0 }, "spamBounceCount": { "type": "integer", "minimum": 0 }, "spamComplaintCount": { "type": "integer", "minimum": 0, "description": "Also counted in unsubscriptionCount, because a complaint unsubscribes; not summable." }, "unsubscriptionCount": { "type": "integer", "minimum": 0 }, "canBeCancelled": { "type": "boolean" }, "missingRequirements": { "type": "array", "items": { "type": "string" } }, "readyToSend": { "type": "boolean" }, "scheduleUrl": { "type": "string" }, "statisticsUrl": { "type": "string" } } }, "audienceReach": { "type": "object", "required": [ "accountId", "newsletterId", "minRecipients", "maxRecipients", "observedAt" ], "properties": { "accountId": { "type": "integer" }, "newsletterId": { "type": "integer" }, "minRecipients": { "type": "integer", "description": "How many contacts the dispatch would certainly reach." }, "maxRecipients": { "type": "integer", "description": "How many it would reach at most." }, "observedAt": { "type": "string", "description": "When the audience was measured, ISO 8601 with offset; a snapshot." } } } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "remediation", "details" ], "properties": { "code": { "type": "string", "description": "The machine-readable KlickTipp error code." }, "message": { "type": "string" }, "remediation": { "type": "string", "description": "Who has to act: for example get_again, use_klicktipp_editor, change_document, change_html, retry_later or ask_user_before_retry." }, "details": { "type": "object" } } } } }, { "type": "object", "required": [ "code", "isSplitTest", "appUrl" ], "properties": { "code": { "type": "string", "const": "split_test_not_supported" }, "isSplitTest": { "type": "boolean" }, "appUrl": { "type": "string", "description": "Where the variants of this split test can be worked on in KlickTipp." }, "newsletterId": { "type": "integer" }, "message": { "type": "string" } } } ] } }, { "name": "prepare-newsletter-dispatch", "description": "Prepares the dispatch of an email newsletter, immediately or at a given moment, and sends, schedules and publishes nothing itself. It checks permission, published content, audience and sender, estimates the recipients and returns a short-lived single-use confirmation URL bound to that exact summary. Only the logged-in user, by opening the URL in KlickTipp and confirming there, hands the newsletter over -- that reaches real recipients and cannot be taken back. Content that was changed but not published is refused; publish it first with publish-newsletter-email-content. The mode has to be given explicitly; a scheduled moment carries its own UTC offset. If a bound value changes or the URL expires, a new preparation is needed. The dispatch state is read through get-newsletter with deliveryStatus.", "tags": [ "Newsletters" ], "inputSchema": { "type": "object", "properties": { "newsletterId": { "type": "integer", "description": "ID of the newsletter to send", "minimum": 1 }, "mode": { "type": "string", "description": "\"immediate\" or \"scheduled\"; no default", "enum": [ "immediate", "scheduled" ] }, "scheduledAt": { "type": [ "null", "string" ], "description": "Moment to send at, ISO 8601 with UTC offset; required for \"scheduled\", forbidden for \"immediate\"", "default": null, "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2})?([Zz]|[+-]\\d{2}:?\\d{2})$" }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "newsletterId", "mode" ], "additionalProperties": false }, "title": "Activate Newsletter", "outputSchema": { "type": "object", "required": [ "outcome", "confirmationUrl", "expiresAt", "summary", "publishesContent", "recoveryRead" ], "properties": { "outcome": { "type": "string" }, "confirmationUrl": { "type": "string" }, "expiresAt": { "type": "string" }, "summary": { "type": "object", "required": [ "accountId", "newsletterId", "name", "newsletterStatus", "audience", "estimatedRecipientsMin", "estimatedRecipientsMax", "sender", "signatureSelectionExplanation", "mode", "sendAt", "emails", "requiresPublish" ], "properties": { "accountId": { "type": "integer" }, "newsletterId": { "type": "integer" }, "name": { "type": "string" }, "newsletterStatus": { "type": "string" }, "audience": { "type": "object", "required": [ "mode" ], "properties": { "includeTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } }, "includeTagsMatch": { "type": "string" }, "excludeTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } }, "excludeTagsMatch": { "type": "string" }, "savedAudience": { "type": [ "object", "null" ], "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "mode": { "type": "string" } } }, "estimatedRecipientsMin": { "type": "integer" }, "estimatedRecipientsMax": { "type": "integer" }, "sender": { "type": "object", "required": [ "senderNameMode", "senderName", "senderEmailMode", "senderEmail", "replyToEmailMode", "replyToEmail", "senderDomainMode", "senderDomain", "signature" ], "properties": { "senderNameMode": { "type": "string" }, "senderName": { "type": [ "string", "null" ] }, "senderEmailMode": { "type": "string" }, "senderEmail": { "type": [ "string", "null" ] }, "replyToEmailMode": { "type": "string" }, "replyToEmail": { "type": [ "string", "null" ] }, "senderDomainMode": { "type": "string" }, "senderDomain": { "type": [ "string", "null" ] }, "signature": { "type": "object", "required": [ "mode", "id", "name" ], "properties": { "mode": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "senderIdentity": { "type": "object", "required": [ "effectiveSenderEmail", "customerDomain", "normalizedSenderDomain", "status", "isUsable", "senderEmailOptions", "senderDomainOptions" ], "properties": { "effectiveSenderEmail": { "type": [ "string", "null" ] }, "customerDomain": { "type": [ "string", "null" ] }, "normalizedSenderDomain": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "ready", "address-not-configured", "address-not-confirmed", "address-not-usable", "address-blocked", "domain-not-configured", "domain-not-verified", "domain-not-yet-usable", "domain-mismatch", null ] }, "isUsable": { "type": [ "boolean", "null" ] }, "senderEmailOptions": { "type": "array", "items": { "type": "string" } }, "senderDomainOptions": { "type": "array", "items": { "type": "string" } } } } } }, "signatureSelectionExplanation": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "sendAt": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "type": "object", "required": [ "emailId", "subject", "editorUrl", "requiresPublish" ], "properties": { "emailId": { "type": "integer" }, "subject": { "type": "string" }, "editorUrl": { "type": "string" }, "requiresPublish": { "type": "boolean" } } } }, "requiresPublish": { "type": "boolean" } } }, "publishesContent": { "type": "boolean" }, "recoveryRead": { "type": "string" } } } }, { "name": "search-newsletters", "description": "Lists the email newsletters of a KlickTipp account, newest first: newsletter ID, email ID, name, delivery state, creation and dispatch moment, split-test flag and deep links. Narrow by a name fragment, by status (draft, scheduled, outgoing, sent) and by two half-open time windows on creation (createdFrom/createdBefore) and dispatch (sendDateFrom/sendDateBefore), ISO 8601 with UTC offset. Paged by cursor: hand nextCursor back unchanged with the same filters. A draft has no dispatch moment and never matches a sendDate window; a split test has no single email, its emailId is null. Subject, content, audience and statistics are read per newsletter through get-newsletter. SMS newsletters, autoresponders and automations are not included.", "tags": [ "Newsletters" ], "inputSchema": { "type": "object", "properties": { "query": { "type": [ "null", "string" ], "description": "Text the name of a newsletter has to contain; omit to list them all", "default": null, "maxLength": 250 }, "status": { "type": [ "null", "string" ], "description": "Only newsletters in this delivery state: \"draft\", \"scheduled\", \"outgoing\" or \"sent\"", "default": null, "enum": [ "draft", "scheduled", "outgoing", "sent" ] }, "createdFrom": { "type": [ "null", "string" ], "description": "Created at or after this moment, ISO 8601 with UTC offset (\"2026-09-01T10:00:00+02:00\")", "default": null, "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2})?([Zz]|[+-]\\d{2}:?\\d{2})$" }, "createdBefore": { "type": [ "null", "string" ], "description": "Only newsletters created before this moment, exclusive, same format", "default": null, "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2})?([Zz]|[+-]\\d{2}:?\\d{2})$" }, "sendDateFrom": { "type": [ "null", "string" ], "description": "Dispatch moment at or after this one, same format; a draft has none and never matches", "default": null, "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2})?([Zz]|[+-]\\d{2}:?\\d{2})$" }, "sendDateBefore": { "type": [ "null", "string" ], "description": "Only newsletters whose dispatch moment lies before this one, exclusive, same format", "default": null, "pattern": "^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2})?([Zz]|[+-]\\d{2}:?\\d{2})$" }, "limit": { "type": [ "null", "integer" ], "description": "How many newsletters to return at most, 1 to 100, 25 by default", "default": null, "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "null", "string" ], "description": "nextCursor of the previous page, with the same filters; omit for the first page", "default": null, "minLength": 8, "maxLength": 200 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "additionalProperties": false }, "title": "Search Newsletters", "outputSchema": { "type": "object", "required": [ "accountId", "count", "hasNextPage", "nextCursor", "newsletters" ], "properties": { "accountId": { "type": "integer" }, "count": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "newsletters": { "type": "array", "items": { "type": "object", "required": [ "newsletterId", "emailId", "name", "newsletterStatus", "createdAt", "sendDate", "isSplitTest", "sent", "opensTotal", "clicksTotal", "editUrl", "statisticsUrl", "contentUrl" ], "properties": { "newsletterId": { "type": "integer" }, "emailId": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "newsletterStatus": { "type": "string" }, "createdAt": { "type": "string" }, "sendDate": { "type": [ "string", "null" ] }, "isSplitTest": { "type": "boolean" }, "sent": { "type": "integer" }, "opensTotal": { "type": "integer" }, "clicksTotal": { "type": "integer" }, "editUrl": { "type": "string" }, "statisticsUrl": { "type": "string" }, "contentUrl": { "type": [ "string", "null" ] } } } } } } }, { "name": "send-newsletter-test", "description": "Sends one email newsletter as a test to a single address, so its content can be checked before it goes out -- the same send the test dialog of KlickTipp performs, with the same rules. Any address may receive one, and an address that is not a contact of the account yet becomes one and is tagged as a test recipient, which can start automations; name the address and say what it will become before calling this. A test carries the PUBLISHED content of the email: a body that was never published is refused -- publish it with publish-newsletter-email-content -- and one changed after publication is sent with a warning that the test shows the older content. The audience of the newsletter is never a recipient, and its delivery state does not change.", "tags": [ "Newsletters" ], "inputSchema": { "type": "object", "properties": { "newsletterId": { "type": "integer", "description": "ID of the newsletter to send a test of", "minimum": 1 }, "recipientEmail": { "type": "string", "description": "Address to send the test to; any address, and one that is not a contact yet becomes one", "minLength": 3, "maxLength": 250 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "newsletterId", "recipientEmail" ], "additionalProperties": false }, "title": "Send Newsletter Test", "outputSchema": { "type": "object", "required": [ "accountId", "newsletterId", "emailId", "recipient", "audienceReached", "newsletterStatus", "messages", "warnings" ], "properties": { "accountId": { "type": "integer" }, "newsletterId": { "type": "integer" }, "emailId": { "type": "integer" }, "recipient": { "type": "string" }, "audienceReached": { "type": "boolean" }, "newsletterStatus": { "type": "string" }, "messages": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } } } }, { "name": "update-newsletter-draft", "description": "Writes name, internal note, subject, preheader, audience and UTM campaign name of an email newsletter draft. Nothing is sent and no send date is set. Only drafts can be written; omitted arguments keep their value, a call without any change is refused. Writing subject or preheader invalidates every contentRevision read before, so read the content again before changing it. The audience replaces the previous one entirely and is given with an explicit mode -- \"all_contacts\" addresses every active contact of the account. The body is changed by the block tools, delivery configuration and scheduling by their own tools. Refuses a split test: its subject lives on the variants, see update-newsletter-split-test-variant.", "tags": [ "Newsletters" ], "inputSchema": { "type": "object", "properties": { "newsletterId": { "type": "integer", "description": "ID of the newsletter to write, as returned by create-newsletter-draft", "minimum": 1 }, "name": { "type": [ "null", "string" ], "description": "New name, unique within the account, at most 250 characters, without HTML; omit to keep", "default": null, "maxLength": 250 }, "note": { "type": [ "null", "string" ], "description": "Internal note, at most 1000 characters, without HTML; omit to keep", "default": null, "maxLength": 1000 }, "subject": { "type": [ "null", "string" ], "description": "New subject line, without HTML. Invalidates every contentRevision read before", "default": null, "maxLength": 998 }, "audience": { "type": "object", "description": "Replaces the audience: \"mode\" is \"all_contacts\", \"saved_audience\" (with \"audienceId\") or \"tag_conditions\" (with the tag fields, at most 50 tags together); omit to keep", "default": null, "properties": { "mode": { "type": "string", "enum": [ "all_contacts", "saved_audience", "tag_conditions" ], "description": "\"all_contacts\" (every active contact, no further field), \"saved_audience\" or \"tag_conditions\"." }, "audienceId": { "type": "integer", "minimum": 1, "description": "ID of the saved audience, for mode \"saved_audience\" only." }, "includeTagIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 50, "description": "Tags a contact must carry, for \"tag_conditions\"; include and exclude together at most 50." }, "includeTagsMatch": { "type": "string", "enum": [ "any", "all" ], "description": "Whether \"any\" required tag is enough or \"all\" are needed." }, "excludeTagIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 50, "description": "Tags that keep a contact out, for \"tag_conditions\"; include and exclude together at most 50." }, "excludeTagsMatch": { "type": "string", "enum": [ "any", "all" ], "description": "Whether \"any\" excluded tag already excludes or only \"all\" together do." } }, "required": [ "mode" ], "additionalProperties": false }, "preheader": { "type": [ "null", "string" ], "description": "New inbox preview line, at most 120 characters, without HTML; empty string removes it, omit keeps it. Invalidates every contentRevision read before", "default": null, "maxLength": 120 }, "utmCampaignName": { "type": [ "null", "string" ], "description": "Campaign name appended to tracked links as utm_campaign, at most 120 characters, without HTML; empty string restores the account default, omit keeps it", "default": null, "maxLength": 120 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "newsletterId" ], "additionalProperties": false }, "title": "Update Newsletter Draft", "outputSchema": { "type": "object", "required": [ "accountId", "newsletterId", "emailId", "name", "newsletterStatus", "emailEditor", "subject", "preheader", "contentRevisionInvalidated", "notes", "hasContent", "contentPublished", "audience", "sender", "editUrl", "contentUrl" ], "properties": { "accountId": { "type": "integer" }, "newsletterId": { "type": "integer" }, "emailId": { "type": "integer" }, "name": { "type": "string" }, "newsletterStatus": { "type": "string" }, "emailEditor": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "contentRevisionInvalidated": { "type": "boolean" }, "notes": { "type": "string" }, "hasContent": { "type": "boolean" }, "contentPublished": { "type": "boolean" }, "audience": { "type": "object", "required": [ "includeTags", "includeTagsMatch", "excludeTags", "excludeTagsMatch", "savedAudience", "mode" ], "properties": { "includeTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } }, "includeTagsMatch": { "type": "string" }, "excludeTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } }, "excludeTagsMatch": { "type": "string" }, "savedAudience": { "type": [ "object", "null" ], "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "mode": { "type": "string" } } }, "sender": { "type": "object", "required": [ "senderNameMode", "senderName", "senderEmailMode", "senderEmail", "replyToEmailMode", "replyToEmail", "senderDomainMode", "senderDomain", "signature" ], "properties": { "senderNameMode": { "type": "string" }, "senderName": { "type": [ "string", "null" ] }, "senderEmailMode": { "type": "string" }, "senderEmail": { "type": [ "string", "null" ] }, "replyToEmailMode": { "type": "string" }, "replyToEmail": { "type": [ "string", "null" ] }, "senderDomainMode": { "type": "string" }, "senderDomain": { "type": [ "string", "null" ] }, "signature": { "type": "object", "required": [ "mode", "id", "name" ], "properties": { "mode": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } } }, "editUrl": { "type": "string" }, "contentUrl": { "type": "string" } } } }, { "name": "add-email-editor-button", "description": "Puts a button into the column whose uuid it names and answers with the uuid of the new block. It takes label, href straight away, so a filled block is one call and one revision rather than two. The block copies the look of the nearest button block of this email; its markup does not come with it, so start from a neighbour's. Bound to the contentRevision of the read and refused whole if anything in it fails, so nothing half-written is stored. Drafts only. Saves the draft; publishing is publish-newsletter-email-content.", "tags": [ "Email Editor" ], "inputSchema": { "type": "object", "properties": { "editorUrl": { "type": "string", "description": "Editor URL of the email, as the read returned it", "minLength": 12, "maxLength": 500 }, "contentRevision": { "type": "string", "description": "The contentRevision of the read this change is based on", "minLength": 7, "maxLength": 100 }, "columnUuid": { "type": "string", "description": "The uuid of the column the block goes into" }, "label": { "type": [ "null", "string" ], "description": "The visible text of the button, as markup", "default": null, "maxLength": 2000 }, "href": { "type": [ "null", "string" ], "description": "Where the button leads", "default": null, "maxLength": 2000 }, "position": { "type": [ "null", "integer" ], "description": "Where it goes inside the column, counted from zero; omit to append", "default": null, "minimum": 0 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "editorUrl", "contentRevision", "columnUuid" ], "additionalProperties": false }, "title": "Add Email Button", "outputSchema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "operation", "previousContentStatus", "contentStatus", "emailId", "contentRevision", "warnings", "editorUrl", "nextAction", "created" ], "properties": { "operation": { "type": "string", "enum": [ "replaced", "unchanged" ], "description": "\"replaced\": the stored document is a new one; \"unchanged\": nothing was persisted." }, "previousContentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "contentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "emailId": { "type": "integer" }, "contentRevision": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "editorUrl": { "type": "string" }, "created": { "type": "array", "description": "What this write created, with uuids: after \"addRow\" the row and its columns, after \"addModule\" the block, plus the contentRevision the next write needs. Empty when nothing was created.", "items": { "type": "object", "required": [ "operation", "type", "uuid" ], "properties": { "operation": { "type": "integer", "description": "Position of the creating operation in the request, counted from one." }, "type": { "type": "string", "enum": [ "row", "module" ] }, "uuid": { "type": "string" }, "kind": { "type": [ "string", "null" ], "description": "The block kind, for a module." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Uuids of the columns of a new row, in order; an \"addModule\" addresses one of these." } } } }, "nextAction": { "type": "string", "enum": [ "review_and_publish_content", "none" ], "description": "The content action still open: \"review_and_publish_content\" while the stored draft is not the dispatch content." } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "remediation", "details" ], "properties": { "code": { "type": "string", "description": "The machine-readable KlickTipp error code." }, "message": { "type": "string" }, "remediation": { "type": "string", "description": "Who has to act: for example get_again, use_klicktipp_editor, change_document, change_html, retry_later or ask_user_before_retry." }, "details": { "type": "object" } } } } } ] } }, { "name": "add-email-editor-divider", "description": "Puts a divider into the column whose uuid it names and answers with the uuid of the new block. It has nothing to write: it is finished the moment it exists. What it looks like -- its thickness, its colour, the space around it -- is the style level, update-email-editor-block-style and the row above it. Bound to the contentRevision of the read and refused whole if anything in it fails, so nothing half-written is stored. Drafts only. Saves the draft; publishing is publish-newsletter-email-content.", "tags": [ "Email Editor" ], "inputSchema": { "type": "object", "properties": { "editorUrl": { "type": "string", "description": "Editor URL of the email, as the read returned it", "minLength": 12, "maxLength": 500 }, "contentRevision": { "type": "string", "description": "The contentRevision of the read this change is based on", "minLength": 7, "maxLength": 100 }, "columnUuid": { "type": "string", "description": "The uuid of the column the block goes into" }, "position": { "type": [ "null", "integer" ], "description": "Where it goes inside the column, counted from zero; omit to append", "default": null, "minimum": 0 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "editorUrl", "contentRevision", "columnUuid" ], "additionalProperties": false }, "title": "Add Email Divider", "outputSchema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "operation", "previousContentStatus", "contentStatus", "emailId", "contentRevision", "warnings", "editorUrl", "nextAction", "created" ], "properties": { "operation": { "type": "string", "enum": [ "replaced", "unchanged" ], "description": "\"replaced\": the stored document is a new one; \"unchanged\": nothing was persisted." }, "previousContentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "contentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "emailId": { "type": "integer" }, "contentRevision": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "editorUrl": { "type": "string" }, "created": { "type": "array", "description": "What this write created, with uuids: after \"addRow\" the row and its columns, after \"addModule\" the block, plus the contentRevision the next write needs. Empty when nothing was created.", "items": { "type": "object", "required": [ "operation", "type", "uuid" ], "properties": { "operation": { "type": "integer", "description": "Position of the creating operation in the request, counted from one." }, "type": { "type": "string", "enum": [ "row", "module" ] }, "uuid": { "type": "string" }, "kind": { "type": [ "string", "null" ], "description": "The block kind, for a module." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Uuids of the columns of a new row, in order; an \"addModule\" addresses one of these." } } } }, "nextAction": { "type": "string", "enum": [ "review_and_publish_content", "none" ], "description": "The content action still open: \"review_and_publish_content\" while the stored draft is not the dispatch content." } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "remediation", "details" ], "properties": { "code": { "type": "string", "description": "The machine-readable KlickTipp error code." }, "message": { "type": "string" }, "remediation": { "type": "string", "description": "Who has to act: for example get_again, use_klicktipp_editor, change_document, change_html, retry_later or ask_user_before_retry." }, "details": { "type": "object" } } } } } ] } }, { "name": "add-email-editor-heading", "description": "Puts a heading into the column whose uuid it names and answers with the uuid of the new block. It takes text and level straight away, so a filled block is one call and one revision rather than two. The block copies the look of the nearest heading block of this email; its markup does not come with it, so start from a neighbour's, and with none to copy its text colour is the email's own default, set with update-email-editor-page-style. The level is part of the structure, not of the look: h1 is the one headline of the mail, h2 a section, h3 a subsection. A newsletter with several sections wants h2 -- that is what real ones use most. Size and colour are the markup, not the level. Bound to the contentRevision of the read and refused whole if anything in it fails, so nothing half-written is stored. Drafts only. Saves the draft; publishing is publish-newsletter-email-content.", "tags": [ "Email Editor" ], "inputSchema": { "type": "object", "properties": { "editorUrl": { "type": "string", "description": "Editor URL of the email, as the read returned it", "minLength": 12, "maxLength": 500 }, "contentRevision": { "type": "string", "description": "The contentRevision of the read this change is based on", "minLength": 7, "maxLength": 100 }, "columnUuid": { "type": "string", "description": "The uuid of the column the block goes into" }, "text": { "type": [ "null", "string" ], "description": "The words of the heading, as markup", "default": null, "maxLength": 100000 }, "level": { "type": [ "null", "string" ], "description": "The heading level: \"h1\", \"h2\" or \"h3\"; omit for h1", "default": null, "enum": [ "h1", "h2", "h3" ] }, "position": { "type": [ "null", "integer" ], "description": "Where it goes inside the column, counted from zero; omit to append", "default": null, "minimum": 0 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "editorUrl", "contentRevision", "columnUuid" ], "additionalProperties": false }, "title": "Add Email Heading", "outputSchema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "operation", "previousContentStatus", "contentStatus", "emailId", "contentRevision", "warnings", "editorUrl", "nextAction", "created" ], "properties": { "operation": { "type": "string", "enum": [ "replaced", "unchanged" ], "description": "\"replaced\": the stored document is a new one; \"unchanged\": nothing was persisted." }, "previousContentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "contentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "emailId": { "type": "integer" }, "contentRevision": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "editorUrl": { "type": "string" }, "created": { "type": "array", "description": "What this write created, with uuids: after \"addRow\" the row and its columns, after \"addModule\" the block, plus the contentRevision the next write needs. Empty when nothing was created.", "items": { "type": "object", "required": [ "operation", "type", "uuid" ], "properties": { "operation": { "type": "integer", "description": "Position of the creating operation in the request, counted from one." }, "type": { "type": "string", "enum": [ "row", "module" ] }, "uuid": { "type": "string" }, "kind": { "type": [ "string", "null" ], "description": "The block kind, for a module." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Uuids of the columns of a new row, in order; an \"addModule\" addresses one of these." } } } }, "nextAction": { "type": "string", "enum": [ "review_and_publish_content", "none" ], "description": "The content action still open: \"review_and_publish_content\" while the stored draft is not the dispatch content." } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "remediation", "details" ], "properties": { "code": { "type": "string", "description": "The machine-readable KlickTipp error code." }, "message": { "type": "string" }, "remediation": { "type": "string", "description": "Who has to act: for example get_again, use_klicktipp_editor, change_document, change_html, retry_later or ask_user_before_retry." }, "details": { "type": "object" } } } } } ] } }, { "name": "add-email-editor-html", "description": "Puts a custom HTML block into the column whose uuid it names and answers with the uuid of the new block. It takes html straight away, so a filled block is one call and one revision rather than two. The block copies the look of the nearest html block of this email; its markup does not come with it, so start from a neighbour's. Bound to the contentRevision of the read and refused whole if anything in it fails, so nothing half-written is stored. Drafts only. Saves the draft; publishing is publish-newsletter-email-content.", "tags": [ "Email Editor" ], "inputSchema": { "type": "object", "properties": { "editorUrl": { "type": "string", "description": "Editor URL of the email, as the read returned it", "minLength": 12, "maxLength": 500 }, "contentRevision": { "type": "string", "description": "The contentRevision of the read this change is based on", "minLength": 7, "maxLength": 100 }, "columnUuid": { "type": "string", "description": "The uuid of the column the block goes into" }, "html": { "type": [ "null", "string" ], "description": "The markup of the block", "default": null, "maxLength": 100000 }, "position": { "type": [ "null", "integer" ], "description": "Where it goes inside the column, counted from zero; omit to append", "default": null, "minimum": 0 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "editorUrl", "contentRevision", "columnUuid" ], "additionalProperties": false }, "title": "Add Email Custom HTML", "outputSchema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "operation", "previousContentStatus", "contentStatus", "emailId", "contentRevision", "warnings", "editorUrl", "nextAction", "created" ], "properties": { "operation": { "type": "string", "enum": [ "replaced", "unchanged" ], "description": "\"replaced\": the stored document is a new one; \"unchanged\": nothing was persisted." }, "previousContentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "contentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "emailId": { "type": "integer" }, "contentRevision": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "editorUrl": { "type": "string" }, "created": { "type": "array", "description": "What this write created, with uuids: after \"addRow\" the row and its columns, after \"addModule\" the block, plus the contentRevision the next write needs. Empty when nothing was created.", "items": { "type": "object", "required": [ "operation", "type", "uuid" ], "properties": { "operation": { "type": "integer", "description": "Position of the creating operation in the request, counted from one." }, "type": { "type": "string", "enum": [ "row", "module" ] }, "uuid": { "type": "string" }, "kind": { "type": [ "string", "null" ], "description": "The block kind, for a module." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Uuids of the columns of a new row, in order; an \"addModule\" addresses one of these." } } } }, "nextAction": { "type": "string", "enum": [ "review_and_publish_content", "none" ], "description": "The content action still open: \"review_and_publish_content\" while the stored draft is not the dispatch content." } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "remediation", "details" ], "properties": { "code": { "type": "string", "description": "The machine-readable KlickTipp error code." }, "message": { "type": "string" }, "remediation": { "type": "string", "description": "Who has to act: for example get_again, use_klicktipp_editor, change_document, change_html, retry_later or ask_user_before_retry." }, "details": { "type": "object" } } } } } ] } }, { "name": "add-email-editor-icons", "description": "Puts an icon block into the column whose uuid it names, with its icons, and answers with the uuid of the new block. The size of an icon and where its words sit come from the block this email already has -- they are required by the format, so they are copied rather than asked for. Bound to the contentRevision of the read and refused whole if anything in it fails, so nothing half-written is stored. Drafts only. Saves the draft; publishing is publish-newsletter-email-content.", "tags": [ "Email Editor" ], "inputSchema": { "type": "object", "properties": { "editorUrl": { "type": "string", "description": "Editor URL of the email, as the read returned it", "minLength": 12, "maxLength": 500 }, "contentRevision": { "type": "string", "description": "The contentRevision of the read this change is based on", "minLength": 7, "maxLength": 100 }, "columnUuid": { "type": "string", "description": "The uuid of the column the block goes into" }, "icons": { "type": "array", "description": "The icons, left to right", "items": { "type": "object", "required": [ "src" ], "additionalProperties": false, "properties": { "src": { "type": "string", "description": "URL of the picture, from list-email-editor-images or open-email-editor-image-upload." }, "href": { "type": "string", "description": "Where it leads." }, "text": { "type": "string", "description": "The words beside the icon." } } }, "minItems": 1, "maxItems": 20 }, "position": { "type": [ "null", "integer" ], "description": "Where it goes inside the column, counted from zero; omit to append", "default": null, "minimum": 0 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "editorUrl", "contentRevision", "columnUuid", "icons" ], "additionalProperties": false }, "title": "Add Email Icons", "outputSchema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "operation", "previousContentStatus", "contentStatus", "emailId", "contentRevision", "warnings", "editorUrl", "nextAction", "created" ], "properties": { "operation": { "type": "string", "enum": [ "replaced", "unchanged" ], "description": "\"replaced\": the stored document is a new one; \"unchanged\": nothing was persisted." }, "previousContentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "contentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "emailId": { "type": "integer" }, "contentRevision": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "editorUrl": { "type": "string" }, "created": { "type": "array", "description": "What this write created, with uuids: after \"addRow\" the row and its columns, after \"addModule\" the block, plus the contentRevision the next write needs. Empty when nothing was created.", "items": { "type": "object", "required": [ "operation", "type", "uuid" ], "properties": { "operation": { "type": "integer", "description": "Position of the creating operation in the request, counted from one." }, "type": { "type": "string", "enum": [ "row", "module" ] }, "uuid": { "type": "string" }, "kind": { "type": [ "string", "null" ], "description": "The block kind, for a module." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Uuids of the columns of a new row, in order; an \"addModule\" addresses one of these." } } } }, "nextAction": { "type": "string", "enum": [ "review_and_publish_content", "none" ], "description": "The content action still open: \"review_and_publish_content\" while the stored draft is not the dispatch content." } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "remediation", "details" ], "properties": { "code": { "type": "string", "description": "The machine-readable KlickTipp error code." }, "message": { "type": "string" }, "remediation": { "type": "string", "description": "Who has to act: for example get_again, use_klicktipp_editor, change_document, change_html, retry_later or ask_user_before_retry." }, "details": { "type": "object" } } } } } ] } }, { "name": "add-email-editor-image-block", "description": "Puts an image into the column whose uuid it names and answers with the uuid of the new block. It takes src, alt, href straight away, so a filled block is one call and one revision rather than two. The block copies the look of the nearest image block of this email; its markup does not come with it, so start from a neighbour's. Bound to the contentRevision of the read and refused whole if anything in it fails, so nothing half-written is stored. Drafts only. Saves the draft; publishing is publish-newsletter-email-content.", "tags": [ "Email Editor" ], "inputSchema": { "type": "object", "properties": { "editorUrl": { "type": "string", "description": "Editor URL of the email, as the read returned it", "minLength": 12, "maxLength": 500 }, "contentRevision": { "type": "string", "description": "The contentRevision of the read this change is based on", "minLength": 7, "maxLength": 100 }, "columnUuid": { "type": "string", "description": "The uuid of the column the block goes into" }, "src": { "type": [ "null", "string" ], "description": "URL of the image, from list-email-editor-images or open-email-editor-image-upload", "default": null, "maxLength": 2000 }, "alt": { "type": [ "null", "string" ], "description": "Alternative text of the image", "default": null, "maxLength": 1000 }, "href": { "type": [ "null", "string" ], "description": "Link target of the image", "default": null, "maxLength": 2000 }, "position": { "type": [ "null", "integer" ], "description": "Where it goes inside the column, counted from zero; omit to append", "default": null, "minimum": 0 }, "accountId": { "type": [ "null", "integer" ], "description": "User ID of the account; omit for the account the access token works in", "default": null, "minimum": 1 } }, "required": [ "editorUrl", "contentRevision", "columnUuid" ], "additionalProperties": false }, "title": "Add Email Image", "outputSchema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "operation", "previousContentStatus", "contentStatus", "emailId", "contentRevision", "warnings", "editorUrl", "nextAction", "created" ], "properties": { "operation": { "type": "string", "enum": [ "replaced", "unchanged" ], "description": "\"replaced\": the stored document is a new one; \"unchanged\": nothing was persisted." }, "previousContentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "contentStatus": { "type": "string", "enum": [ "draft", "published", "unpublished_changes" ] }, "emailId": { "type": "integer" }, "contentRevision": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "editorUrl": { "type": "string" }, "created": { "type": "array", "description": "What this write created, with uuids: after \"addRow\" the row and its columns, after \"addModule\" the block, plus the contentRevision the next write needs. Empty when nothing was created.", "items": { "type": "object", "required": [ "operation", "type", "uuid" ], "properties": { "operation": { "type": "integer", "description": "Position of the creating operation in the request, counted from one." }, "type": { "type": "string", "enum": [ "row", "module" ] }, "uuid": { "type": "string" }, "kind": { "type": [ "string", "null" ], "description": "The block kind, for a module." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Uuids of the columns of a new row, in order; an \"addModule\" addresses one of these." } } } }, "nextAction": { "type": "string", "enum": [ "review_and_publish_content", "none" ], "description": "The content action still open: \"review_and_publish_content\" while the stored draft is not the dispatch content." } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "remediation", "details" ], "properties": { "code": { "type": "string", "description": "The machine-readable KlickTipp error code." }, "message": { "type": "string" }, "remediation": { "type": "string", "description": "Who has to act: for example get_again, use_klicktipp_editor, change_document, change_html, retry_later or ask_user_before_retry." }, "details": { "type": "object" } } } } } ] } }, { "name": "add-email-editor-list", "description": "Puts a list into the column whose uuid it names and answers with the uuid of the new block. It takes html straight away, so a filled block is one call and one revision rather than two. The block copies the look of the nearest list block of this email; its markup does not come with it, so start from a neighbour's. With no block of its kind to copy, its text and link colour are the email's own defaults, set with update-email-editor-page-style -- so set those first and add the blocks after. Bound to the contentRevision of the read and refused whole if anything in it fails, so nothing half-written is stored. Drafts only. Saves the draft; publishing is publish-newsletter-email-content.", "tags": [ "Email Editor" ], "inputSchema": { "type": "object", "properties": { "editorUrl": { "type": "string", "description": "Editor URL of the email, as the read returned it", "minLength": 12, "maxLength": 500 }, "contentRevision": { "type": "string", "description": "The contentRevision of the read this change is based on", "minLength": 7, "maxLength": 100 }, "columnUuid": { "type": "string", "description": "The uuid of the column the block goes into" }, "html": { "type": [ "null", "string" ], "description": "The list, as complete