# KlickTipp API Documentation – Authentication & Integration

> Official KlickTipp API documentation. Learn how to authenticate, integrate external systems, and build reliable automations using the KlickTipp API.

## Table of contents

 - [account.md](https://developers.klicktipp.com/docs_mcp/tags/account.md)
 - [MCP Server](https://developers.klicktipp.com/docs_mcp/info/info.md)
 - [Manage large sets of Tags](https://developers.klicktipp.com/guides/tag-management-templates.md)
 - [Connect the KlickTipp Docs MCP](https://developers.klicktipp.com/guides/docs-mcp-server.md): Connect AI assistants to KlickTipp guides and API references through the public KlickTipp Docs MCP. No sign-in or account access.
 - [autoresponders.md](https://developers.klicktipp.com/docs_mcp/tags/autoresponders.md)
 - [Connect the KlickTipp App MCP](https://developers.klicktipp.com/guides/mcp-server.md): Connect AI assistants to your KlickTipp account through the App MCP using OAuth. Work with newsletters, contacts, tags, and automations.
 - [Integration Options](https://developers.klicktipp.com/guides/integration-models.md)
 - [Install the KlickTipp App plugin for Claude and Codex](https://developers.klicktipp.com/guides/mcp-server-plugins.md)
 - [Webhooks & Event Subscriptions](https://developers.klicktipp.com/guides/webhooks-and-events.md)
 - [Choosing Between the Listbuilding API and the Management API](https://developers.klicktipp.com/guides/api-selection-rules.md)
 - [CRM Integration](https://developers.klicktipp.com/guides/crm-integration.md)
 - [Error Handling and Validation](https://developers.klicktipp.com/guides/error-handling.md)
 - [Form Integration](https://developers.klicktipp.com/guides/form-integration.md)
 - [Data Field Types and Input Formats](https://developers.klicktipp.com/guides/data-field-types.md)
 - [Overview](https://developers.klicktipp.com/guides.md)
 - [Secure & Easy Integration with the Listbuilding API](https://developers.klicktipp.com/guides/listbuilding-api.md)
 - [How to authenticate and access the Management API](https://developers.klicktipp.com/guides/management-api-authentication.md)
 - [Building Robust Integrations with the Management API](https://developers.klicktipp.com/guides/management-api.md)
 - [Secure Tracking and Page Personalization via Subscriber Key](https://developers.klicktipp.com/guides/subscriber-key.md)
 - [Webinar Integration](https://developers.klicktipp.com/guides/webinar-integration.md)
 - [calenders.md](https://developers.klicktipp.com/docs_mcp/tags/calenders.md)
 - [campaign_editor.md](https://developers.klicktipp.com/docs_mcp/tags/campaign_editor.md)
 - [campaigns.md](https://developers.klicktipp.com/docs_mcp/tags/campaigns.md)
 - [contact_tagging.md](https://developers.klicktipp.com/docs_mcp/tags/contact_tagging.md)
 - [contacts.md](https://developers.klicktipp.com/docs_mcp/tags/contacts.md)
 - [countdowns.md](https://developers.klicktipp.com/docs_mcp/tags/countdowns.md)
 - [data_fields.md](https://developers.klicktipp.com/docs_mcp/tags/data_fields.md)
 - [email_editor.md](https://developers.klicktipp.com/docs_mcp/tags/email_editor.md)
 - [email_images.md](https://developers.klicktipp.com/docs_mcp/tags/email_images.md)
 - [email_signatures.md](https://developers.klicktipp.com/docs_mcp/tags/email_signatures.md)
 - [emails.md](https://developers.klicktipp.com/docs_mcp/tags/emails.md)
 - [feedbacks.md](https://developers.klicktipp.com/docs_mcp/tags/feedbacks.md)
 - [listbuildings.md](https://developers.klicktipp.com/docs_mcp/tags/listbuildings.md)
 - [marketing_tools.md](https://developers.klicktipp.com/docs_mcp/tags/marketing_tools.md)
 - [newsletter_split-tests.md](https://developers.klicktipp.com/docs_mcp/tags/newsletter_split-tests.md)
 - [newsletters.md](https://developers.klicktipp.com/docs_mcp/tags/newsletters.md)
 - [opt-in_processes.md](https://developers.klicktipp.com/docs_mcp/tags/opt-in_processes.md)
 - [sender_adresses.md](https://developers.klicktipp.com/docs_mcp/tags/sender_adresses.md)
 - [sender_domains.md](https://developers.klicktipp.com/docs_mcp/tags/sender_domains.md)
 - [smart_links.md](https://developers.klicktipp.com/docs_mcp/tags/smart_links.md)
 - [sms.md](https://developers.klicktipp.com/docs_mcp/tags/sms.md)
 - [statistics.md](https://developers.klicktipp.com/docs_mcp/tags/statistics.md)
 - [tagging_pixel.md](https://developers.klicktipp.com/docs_mcp/tags/tagging_pixel.md)
 - [tags.md](https://developers.klicktipp.com/docs_mcp/tags/tags.md)
 - [webhooks.md](https://developers.klicktipp.com/docs_mcp/tags/webhooks.md)
 - [KlickTipp Listbuilding API](https://developers.klicktipp.com/listbuilding-api.md): This specification describes the **KlickTipp Listbuilding API**. It is intended for external tools, websites, and automation platforms that integrate KlickTipp list-building functionality using **API Key authentication**. Typical use cases include newsletter sign-up forms, lead magnets, landing pages, and no-code or iPaaS-based automations. The Listbuilding API provides a restricted and purpose-built interface for managing contacts **without requiring full account authentication**. Using an API key, external systems can add or update contacts, assign or remove a tag, trigger opt-in processes, or unsubscribe contacts from further communication. --- ## Authentication Model All endpoints in this specification use **API Key authentication**. The API key is generated in KlickTipp under: Listbuilding → New Listbuilding → Entry via API key Each API key is permanently linked to a specific opt-in process and tag. This defines the scope and behavior of the integration. Authentication is performed by sending the API key **directly in the request body**. No session handling or cookies are required. Documentation: [How to Create an API Key](https://developers.klicktipp.com/guides/listbuilding-api) --- ## Intended Usage This API is optimized for: - External signup and opt-in forms - Embedded integrations in websites such as WordPress or landing page builders - Automated lead processing via third-party platforms It is **not intended** for administrative workflows or full account management. --- ## Core Endpoints The Listbuilding API focuses on a small, stable set of endpoints designed for external systems: - **Signin** Creates or updates a contact and associates the tag linked to the API key - **Signout** Removes the tag of a contact associated with the API key - **Signoff** Unsubscribes a contact via the API key and prevents further communication --- ## Base URL The base URL for the KlickTipp API production environment is: ``` https://api.klicktipp.com ``` All endpoints defined in this specification are relative to this base URL. --- ## Response Format The KlickTipp Listbuilding API uses **JSON** as its response format. All endpoints return JSON responses containing structured payloads and error information. Integrations are expected to consume and validate JSON responses exclusively. --- ## Data Formats and Validation Date and time values must always be provided as **Unix timestamps (seconds)**. For the data field type **Time** only timestamps representing the **first day of the Unix epoch date (00:00:00 UTC)** are accepted. Any time-of-day information beyond the day boundary is rejected. Formatted date strings, locale-specific formats, and timezone annotations are not supported. Incorrect field formats are one of the most common causes of errors when using the Listbuilding API. Always ensure that submitted values match the expected field type definitions. Documentation: [Data field types and Inputs](https://developers.klicktipp.com/guides/data-field-types) --- ## Error Handling Errors are returned as JSON responses and typically use HTTP status code **403** or **406**, depending on the failure type. Each error includes a numeric error code that should be handled explicitly by the integrating system. Documentation: [Error Handling](https://developers.klicktipp.com/guides/error-handling) --- This specification is designed to support **simple, secure, and predictable** list-building integrations with KlickTipp.
 - [KlickTipp API](https://developers.klicktipp.com/management-api.md): This specification describes the **KlickTipp Management API**. It is intended for developers and integrators who want to interact directly with KlickTipp to manage contacts, tags, custom fields, opt-in processes, and automation workflows. The API can be used standalone or through third-party platforms. The specification focuses on correct request formats, authentication mechanisms, response structures, and error handling to ensure reliable and predictable integrations. **Good to know:** This API uses session-based cookie authentication. Interactive Try-It requests do not fully support this login flow. For production testing click on the button to open our Collection in Postman. (function (p,o,s,t,m,a,n) { !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); }); !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild(( (n = o.createElement("script")), (n.id = s+t), (n.async = 1), (n.src = m), n )); }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js")); --- ## Base URL The base URL for the KlickTipp API production environment is: ``` https://api.klicktipp.com ``` All endpoints defined in this specification are relative to this base URL. --- ## Getting Started To access the API, you must authenticate and maintain a valid session. 1. **Authentication** Most endpoints require cookie-based authentication. Use the login endpoint with your KlickTipp username and password to obtain a **session cookie**, which must be sent with all subsequent requests. 2. **Request Preparation** Replace all placeholder values such as email addresses, IDs, or timestamps with valid test data. Invalid formats are a common source of errors. 3. **Response Handling** The API returns structured payloads and numeric error codes. Always validate HTTP status codes and response bodies programmatically. --- ## Authentication Overview The KlickTipp Management API supports **multiple authentication models**, depending on the integration scenario. - **Username and password authentication via session cookie** Typically used for internal tools and administrative workflows. - **Developer key and customer key authentication** Intended for long-running, production-grade, or multi-tenant integrations. This model does not rely on session handling. Documentation: [How to authenticate and access the Management API](https://developers.klicktipp.com/guides/management-api-authentication) --- ## Response Format The KlickTipp Management API uses JSON as its response format. All endpoints return **JSON responses**, including structured data, timestamps, and error details. Integrations are expected to consume and validate JSON exclusively. --- ## Data Formats and Validation Date and time values must always be provided as **Unix timestamps (seconds)**. Formatted date strings, locale-specific formats, and timezone annotations are **not supported**. Incorrect field formats are a frequent cause of validation errors. Always ensure that submitted values match the expected field type definitions. Documentation: [Data field types and Inputs](https://developers.klicktipp.com/guides/data-field-types) --- ## Error Handling Errors are typically returned with **HTTP status code 406** and include a numeric error code in the response body. Integrations should handle errors explicitly and provide meaningful diagnostics for debugging and monitoring. Documentation: [Error Handling](https://developers.klicktipp.com/guides/error-handling) --- This specification is designed to support stable, predictable, and maintainable integrations with the KlickTipp platform.
 - [KlickTipp MCP Tools](https://developers.klicktipp.com/mcp-tools.md): This specification describes the **KlickTipp MCP Server**. It 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. **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. > **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. --- ## MCP Server The 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: | | | | --- | --- | | **URL** | `https://mcp.klicktipp.com/mcp` | | **Authentication** | Managed OAuth 2.0 (no API key, no local server, no `.env` file needed) | | **Requirement** | A KlickTipp **Premium**, **Deluxe** or **Enterprise** subscription with permission to log in to the account in question | > **Good to know:** this MCP Server uses a KlickTipp managed OAuth 2.0, not the Management API's session cookie or key-based authentication. --- ## Getting Started A rough guide to connecting any MCP-capable client: 1. **Add the server** In your MCP client's connector/integration settings, add a new remote MCP server pointing to this URL: ``` https://mcp.klicktipp.com/mcp ``` 2. **Complete the OAuth sign-in** 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. 3. **Call tools** Once connected, call the tools listed in this document by name. The 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). > 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. --- ## Tool Catalog The 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. --- ## Security Behaviour The MCP server is deliberately designed so an AI assistant can search and read broadly, while critical and irreversible actions stay with a human: - **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. - **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. - **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. --- ## Error Handling A 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. --- ## Plugin & Further Use Cases For 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). For 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).