{ "openapi": "3.0.3", "x-mint": { "mcp": { "enabled": true } }, "info": { "title": "Kit API", "version": "4.0" }, "servers": [ { "url": "https://api.kit.com" } ], "paths": { "/v4/account": { "get": { "summary": "Get current account", "tags": [ "Accounts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Returns current account and user info", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "integer" } }, "required": [ "email" ] }, "account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "plan_type": { "type": "string" }, "primary_email_address": { "type": "string" }, "created_at": { "type": "string" }, "timezone": { "type": "object", "properties": { "name": { "type": "string", "description": "Product name" }, "friendly_name": { "type": "string" }, "utc_offset": { "type": "string" } }, "required": [ "name", "friendly_name", "utc_offset" ] }, "sending_addresses": { "type": "array", "items": { "type": "object", "properties": { "email_address": { "type": "string" }, "from_name": { "type": "string" }, "status": { "type": "string" }, "is_default": { "type": "boolean" }, "is_verified": { "type": "boolean" }, "is_dmarc_configured": { "type": "boolean" } }, "required": [ "email_address", "from_name", "status", "is_default", "is_verified", "is_dmarc_configured" ] } } }, "required": [ "id", "name", "plan_type", "primary_email_address", "created_at", "timezone" ] } }, "required": [ "user", "account" ] }, "example": { "user": { "email": "test@kit.dev", "id": 27 }, "account": { "id": 27, "name": "Kit Greetings", "plan_type": "creator", "primary_email_address": "test@kit.dev", "created_at": "2023-02-17T11:43:55Z", "timezone": { "name": "America/New_York", "friendly_name": "Eastern Time (US & Canada)", "utc_offset": "-05:00" }, "sending_addresses": [ { "email_address": "joe27@ck.lol", "from_name": "Joe", "status": "pending", "is_default": true, "is_verified": false, "is_dmarc_configured": false } ] } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/account/colors": { "get": { "summary": "List colors", "tags": [ "Accounts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Returns list of colors for the current account", "content": { "application/json": { "schema": { "type": "object", "properties": { "colors": { "type": "array", "items": { "type": "string" } } }, "required": [ "colors" ] }, "example": { "colors": [ "#008000", "#FF0000" ] } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } }, "put": { "summary": "Update colors", "tags": [ "Accounts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Updates and returns list of colors for the current account", "content": { "application/json": { "schema": { "type": "object", "properties": { "colors": { "type": "array", "items": { "type": "string" } } }, "required": [ "colors" ] }, "example": { "colors": [ "#000000", "#ffffff" ] } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "422": { "description": "Returns a 422 with an error message when invalid color code is provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Colors #123_not_a_code is not a valid hex color code." ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "colors": { "type": "array", "description": "An array of up to 10 color hex codes", "items": { "type": "string" } } }, "required": [ "colors" ] }, "example": { "colors": [ "#000000", "#ffffff" ] } } } }, "x-mcp": { "enabled": true } } }, "/v4/account/creator_profile": { "get": { "summary": "Get Creator Profile", "tags": [ "Accounts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Returns Creator Profile details", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "name": { "type": "string" }, "byline": { "type": "string" }, "bio": { "type": "string" }, "image_url": { "type": "string" }, "profile_url": { "type": "string" } }, "required": [ "name", "byline", "bio", "image_url", "profile_url" ] } }, "required": [ "profile" ] }, "example": { "profile": { "name": "A Creator's Journey", "byline": "A Creator", "bio": "Follow my Journey as a Creator", "image_url": "https://convertkit.dev/image.jpg?fit=crop&h=320&w=320", "profile_url": "https://kit-greetings.kit.com/profile" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 if the creator profile doesn't exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/account/email_stats": { "get": { "summary": "Get email stats", "tags": [ "Accounts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Returns your email stats for the last 90 days", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "sent": { "type": "integer" }, "clicked": { "type": "integer" }, "opened": { "type": "integer" }, "email_stats_mode": { "type": "string" }, "open_tracking_enabled": { "type": "boolean" }, "click_tracking_enabled": { "type": "boolean" }, "starting": { "type": "string" }, "ending": { "type": "string" }, "open_rate": { "type": "number", "format": "float" }, "click_rate": { "type": "number", "format": "float" }, "unsubscribe_rate": { "type": "number", "format": "float" }, "bounce_rate": { "type": "number", "format": "float" } }, "required": [ "sent", "clicked", "opened", "email_stats_mode", "open_tracking_enabled", "click_tracking_enabled", "starting", "ending" ] } }, "required": [ "stats" ] }, "example": { "stats": { "sent": 6, "clicked": 3, "opened": 6, "email_stats_mode": "last_90", "open_tracking_enabled": true, "click_tracking_enabled": true, "starting": "2022-11-19T11:43:55Z", "ending": "2023-02-17T11:43:55Z", "open_rate": 100.0, "click_rate": 50.0, "unsubscribe_rate": 16.67, "bounce_rate": 16.67 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/account/growth_stats": { "get": { "summary": "Get growth stats", "description": "Get growth stats for a specific time period. Defaults to last 90 days.

NOTE: We return your stats in your sending time zone. This endpoint does not return timestamps in UTC.", "tags": [ "Accounts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "ending", "in": "query", "description": "Get stats for time period ending on this date (format yyyy-mm-dd). Defaults to today.", "required": false, "schema": { "type": "string" }, "example": "02/09/2023" }, { "name": "starting", "in": "query", "description": "Get stats for time period beginning on this date (format yyyy-mm-dd). Defaults to 90 days ago.", "required": false, "schema": { "type": "string" }, "example": "02/10/2023" } ], "responses": { "200": { "description": "Returns your growth stats for the provided starting and ending dates", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "cancellations": { "type": "integer" }, "net_new_subscribers": { "type": "integer" }, "new_subscribers": { "type": "integer" }, "subscribers": { "type": "integer" }, "starting": { "type": "string" }, "ending": { "type": "string" } }, "required": [ "cancellations", "net_new_subscribers", "new_subscribers", "subscribers", "starting", "ending" ] } }, "required": [ "stats" ] }, "example": { "stats": { "cancellations": 0, "net_new_subscribers": 3, "new_subscribers": 3, "subscribers": 3, "starting": "2023-02-10T00:00:00-05:00", "ending": "2023-02-24T23:59:59-05:00" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "422": { "description": "Returns a 422 with an error message if the starting or ending params are misformatted or the range is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Starting date is incorrectly formatted. Use YYYY-MM-DD.", "Ending date is incorrectly formatted. Use YYYY-MM-DD.", "Starting date must be before the ending date." ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/broadcasts": { "get": { "summary": "List broadcasts", "tags": [ "Broadcasts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "sent_after", "description": "Get broadcasts sent after this date (format yyyy-mm-dd).", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "sent_before", "description": "Get broadcasts sent before this date (format yyyy-mm-dd).", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "slim", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false, "description": "When `true`, omits expensive optional fields from the response. Produces a faster, smaller response — useful when extra fields are not needed." } ], "responses": { "200": { "description": "Returns a paginated list of all broadcasts for your account (including draft, scheduled, and already sent)", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcasts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "publication_id": { "type": "integer", "description": "Identifier of the underlying publication. Broadcasts that are also published as posts share the same `publication_id` — use it to match a broadcast to its post via `GET /v4/posts`." }, "created_at": { "type": "string" }, "subject": { "type": "string" }, "preview_text": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "public": { "type": "boolean" }, "published_at": { "type": "string", "nullable": true }, "send_at": { "type": "string", "nullable": true }, "thumbnail_alt": { "type": "string", "nullable": true }, "thumbnail_url": { "type": "string", "nullable": true }, "public_url": { "type": "string", "nullable": true }, "email_address": { "type": "string", "nullable": true }, "email_template": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "subscriber_filter": { "type": "array", "items": { "type": "object", "properties": { "all": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ] } } }, "required": [ "all" ] } }, "status": { "type": "string" } }, "required": [ "id", "publication_id", "created_at", "subject", "preview_text", "description", "public", "published_at", "send_at", "thumbnail_alt", "thumbnail_url", "content", "public_url", "email_address", "email_template", "subscriber_filter" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "broadcasts", "pagination" ] }, "example": { "broadcasts": [ { "id": 3, "publication_id": 3, "created_at": "2023-02-17T11:43:55Z", "subject": "Campaign subject 3", "preview_text": null, "description": null, "public": false, "published_at": null, "send_at": null, "status": "draft", "thumbnail_alt": null, "thumbnail_url": null, "content": null, "public_url": null, "email_address": "greetings@kit.dev", "email_template": { "id": 6, "name": "Text Only" }, "subscriber_filter": [ { "all": [ { "type": "all_subscribers" } ] } ] }, { "id": 2, "publication_id": 2, "created_at": "2023-02-17T11:43:55Z", "subject": "Campaign subject 2", "preview_text": null, "description": null, "public": false, "published_at": null, "send_at": null, "status": "draft", "thumbnail_alt": null, "thumbnail_url": null, "content": null, "public_url": null, "email_address": "greetings@kit.dev", "email_template": { "id": 6, "name": "Text Only" }, "subscriber_filter": [ { "all": [ { "type": "all_subscribers" } ] } ] }, { "id": 1, "publication_id": 1, "created_at": "2023-02-17T11:43:55Z", "subject": "Campaign subject 1", "preview_text": null, "description": null, "public": false, "published_at": null, "send_at": null, "status": "draft", "thumbnail_alt": null, "thumbnail_url": null, "content": null, "public_url": null, "email_address": "greetings@kit.dev", "email_template": { "id": 6, "name": "Text Only" }, "subscriber_filter": [ { "all": [ { "type": "all_subscribers" } ] } ] } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzNd", "end_cursor": "WzFd", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Create a broadcast", "description": "Draft or schedule to send a broadcast to all or a subset of your subscribers.

To save a draft, set `send_at` to `null`.

To publish to the web, set `public` to `true`.

To schedule the broadcast for sending, provide a `send_at` timestamp. Scheduled broadcasts should contain a subject and your content, at a minimum.

We currently support targeting your subscribers based on segment or tag ids.", "tags": [ "Broadcasts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "201": { "description": "Creates a new broadcast", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcast": { "type": "object", "properties": { "id": { "type": "integer" }, "publication_id": { "type": "integer" }, "created_at": { "type": "string" }, "subject": { "type": "string" }, "preview_text": { "type": "string" }, "description": { "type": "string" }, "content": { "type": "string" }, "public": { "type": "boolean" }, "published_at": { "type": "string" }, "send_at": { "type": "string", "nullable": true }, "thumbnail_alt": { "type": "string", "nullable": true }, "thumbnail_url": { "type": "string", "nullable": true }, "public_url": { "type": "string" }, "email_address": { "type": "string" }, "email_template": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "subscriber_filter": { "type": "array", "items": { "type": "object", "properties": { "all": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "segment", "tag" ] }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] } } }, "required": [ "all" ] } }, "status": { "type": "string" } }, "required": [ "id", "publication_id", "created_at", "subject", "preview_text", "description", "public", "published_at", "send_at", "thumbnail_alt", "thumbnail_url", "content", "public_url", "email_address", "email_template", "subscriber_filter" ] } }, "required": [ "broadcast" ] }, "example": { "broadcast": { "id": 64, "publication_id": 55, "created_at": "2023-02-17T11:43:55Z", "subject": "Hello!", "preview_text": "Pleased to meet you!", "description": "Intro email", "content": "

Let me introduce myself

", "public": true, "published_at": "2023-02-17T11:43:55Z", "send_at": null, "thumbnail_alt": null, "thumbnail_url": null, "public_url": "https://kit-greetings.kit.com/posts/", "email_address": "greetings@kit.dev", "email_template": { "id": 2, "name": "Classic" }, "subscriber_filter": [ { "all": [ { "type": "segment", "ids": [ 18 ] } ] } ], "status": "draft" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "403": { "description": "Returns a 403 with an error message if the current account is unauthorized to create a broadcast", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "You do not have sufficient permissions to access this resource. Please contact support." ] } } } }, "422": { "description": "Returns a 422 with an error message when one or more of the parameters were invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Email template not found", "Only a single filter group is supported. Use one of `all`, `any`, or `none`." ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email_template_id": { "type": "integer", "description": "Id of the email template to use. Uses the account's default template if not provided. 'Starting point' template is not supported." }, "email_address": { "type": "string", "nullable": true, "description": "The sending email address to use. Uses the account's sending email address if not provided." }, "content": { "type": "string", "description": "The HTML content of the email." }, "description": { "type": "string" }, "public": { "type": "boolean", "description": "`true` to publish this broadcast to the web. The broadcast will appear in a newsletter feed on your Creator Profile and Landing Pages." }, "published_at": { "type": "string", "description": "The published timestamp to display in ISO8601 format. If no timezone is provided, UTC is assumed." }, "send_at": { "type": "string", "nullable": true, "description": "The scheduled send time for this broadcast in ISO8601 format. If no timezone is provided, UTC is assumed." }, "thumbnail_alt": { "type": "string", "nullable": true }, "thumbnail_url": { "type": "string", "nullable": true }, "preview_text": { "type": "string" }, "subject": { "type": "string" }, "subscriber_filter": { "type": "array", "description": "Filters your subscribers. At this time, we only support using only one filter group type via the API (e.g. `all`, `any`, or `none` but no combinations). If nothing is provided, will default to all of your subscribers.", "items": { "type": "object", "properties": { "all": { "type": "array", "description": "Filters your subscribers using a logical AND of all provided segment and tag ids, i.e. a subscriber would have to be part of all segments and tags provided", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "segment", "tag" ], "description": "`segment` or `tag`" }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] } }, "any": { "type": "array", "description": "Filters your subscribers using a logical OR of all provided segment and tag ids, i.e. a subscriber would have to be part of at least one of the segments or tags provided", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "segment", "tag" ], "description": "`segment` or `tag`" }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] }, "nullable": true }, "none": { "type": "array", "description": "Filters your subscribers using a logical NOT of all provided segment and tag ids, i.e. a subscriber would have to be in none of the segments or tags provided", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "segment", "tag" ], "description": "`segment` or `tag`" }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] }, "nullable": true } }, "minProperties": 1, "required": [ "all", "any", "none" ] } } }, "required": [ "content", "description", "public", "published_at", "preview_text", "subject", "subscriber_filter" ] }, "example": { "email_template_id": 2, "email_address": null, "content": "

Let me introduce myself

", "description": "Intro email", "public": true, "published_at": "2023-02-17T11:43:55+00:00", "send_at": null, "thumbnail_alt": null, "thumbnail_url": null, "preview_text": "Pleased to meet you!", "subject": "Hello!", "subscriber_filter": [ { "all": [ { "type": "segment", "ids": [ 18 ] } ], "any": null, "none": null } ] } } } }, "x-mcp": { "enabled": true } } }, "/v4/broadcasts/stats": { "get": { "summary": "Get stats for a list of broadcasts", "tags": [ "Broadcasts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "nullable": true }, "description": "To fetch next page of results, use `?after=`" }, { "name": "before", "in": "query", "required": false, "schema": { "nullable": true }, "description": "To fetch previous page of results, use `?before=`" }, { "name": "include_total_count", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false, "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages." }, { "name": "per_page", "in": "query", "required": false, "schema": { "nullable": true }, "description": "Number of results per page. Default 500, maximum 1000." }, { "name": "sent_after", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "sent_before", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns stats for all broadcasts on the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcasts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "open_rate": { "type": "number", "format": "float" }, "emails_opened": { "type": "integer" }, "click_rate": { "type": "number", "format": "float" }, "unsubscribe_rate": { "type": "number", "format": "float" }, "unsubscribes": { "type": "integer" }, "total_clicks": { "type": "integer" }, "show_total_clicks": { "type": "boolean" }, "status": { "type": "string" }, "progress": { "type": "number", "format": "float" }, "open_tracking_disabled": { "type": "boolean" }, "click_tracking_disabled": { "type": "boolean" } }, "required": [ "recipients", "open_rate", "emails_opened", "click_rate", "unsubscribe_rate", "unsubscribes", "total_clicks", "show_total_clicks", "status", "progress", "open_tracking_disabled", "click_tracking_disabled" ] }, "subject": { "type": "string" }, "send_at": { "nullable": true } }, "required": [ "id", "stats" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "broadcasts", "pagination" ] }, "example": { "broadcasts": [ { "id": 208, "subject": "... or will you", "send_at": null, "stats": { "recipients": 0, "open_rate": 0.0, "emails_opened": 0, "click_rate": 0.0, "unsubscribe_rate": 0.0, "unsubscribes": 0, "total_clicks": 0, "show_total_clicks": false, "status": "draft", "progress": 0.0, "open_tracking_disabled": false, "click_tracking_disabled": false } }, { "id": 207, "subject": "You'll never guess...", "send_at": null, "stats": { "recipients": 0, "open_rate": 0.0, "emails_opened": 0, "click_rate": 0.0, "unsubscribe_rate": 0.0, "unsubscribes": 0, "total_clicks": 0, "show_total_clicks": false, "status": "draft", "progress": 0.0, "open_tracking_disabled": false, "click_tracking_disabled": false } } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzIwOF0=", "end_cursor": "WzIwN10=", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "403": { "description": "Returns 403 if the account is not on a pro plan and has the feature flag disabled", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [ "errors" ] }, "example": {} } } } }, "x-mcp": { "enabled": true } } }, "/v4/broadcasts/{broadcast_id}/clicks": { "get": { "summary": "Get link clicks for a broadcast", "description": "NOTE: Pagination parameters control the list of clicks for the top level broadcast.", "tags": [ "Broadcasts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 169 } ], "responses": { "200": { "description": "Returns clicks for a broadcast", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcast": { "type": "object", "properties": { "id": { "type": "integer" }, "clicks": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "unique_clicks": { "type": "integer" }, "click_to_delivery_rate": { "type": "number", "format": "float" }, "click_to_open_rate": { "type": "number", "format": "float" } }, "required": [ "url", "unique_clicks", "click_to_delivery_rate", "click_to_open_rate" ] } } }, "required": [ "id", "clicks" ] }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "broadcast", "pagination" ] }, "example": { "broadcast": { "id": 166, "clicks": [ { "url": "https://example.com/52", "unique_clicks": 3, "click_to_delivery_rate": 0.006, "click_to_open_rate": 0.03 }, { "url": "https://example.com/53", "unique_clicks": 3, "click_to_delivery_rate": 0.006, "click_to_open_rate": 0.03 }, { "url": "https://example.com/54", "unique_clicks": 3, "click_to_delivery_rate": 0.006, "click_to_open_rate": 0.03 } ] }, "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzE4XQ==", "end_cursor": "WzE4XQ==", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/broadcasts/{broadcast_id}/stats": { "get": { "summary": "Get stats for a broadcast", "tags": [ "Broadcasts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 279 } ], "responses": { "200": { "description": "Returns stats for a broadcast", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcast": { "type": "object", "properties": { "id": { "type": "integer" }, "stats": { "type": "object", "properties": { "recipients": { "type": "integer" }, "open_rate": { "type": "number", "format": "float" }, "emails_opened": { "type": "integer" }, "click_rate": { "type": "number", "format": "float" }, "unsubscribe_rate": { "type": "number", "format": "float" }, "unsubscribes": { "type": "integer" }, "total_clicks": { "type": "integer" }, "show_total_clicks": { "type": "boolean" }, "status": { "type": "string" }, "progress": { "type": "number", "format": "float" }, "open_tracking_disabled": { "type": "boolean" }, "click_tracking_disabled": { "type": "boolean" } }, "required": [ "recipients", "open_rate", "emails_opened", "click_rate", "unsubscribe_rate", "unsubscribes", "total_clicks", "show_total_clicks", "status", "progress", "open_tracking_disabled", "click_tracking_disabled" ] } }, "required": [ "id", "stats" ] } }, "required": [ "broadcast" ] }, "example": { "broadcast": { "id": 276, "stats": { "recipients": 0, "open_rate": 0.0, "emails_opened": 0, "click_rate": 0.0, "unsubscribe_rate": 0.0, "unsubscribes": 0, "total_clicks": 0, "show_total_clicks": false, "status": "draft", "progress": 0.0, "open_tracking_disabled": false, "click_tracking_disabled": false } } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/broadcasts/{id}": { "delete": { "summary": "Delete a broadcast", "tags": [ "Broadcasts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 133 } ], "responses": { "204": { "description": "Deletes the broadcast" }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "403": { "description": "Returns a 403 with an error message if the current account is unauthorized to update a broadcast", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "You do not have sufficient permissions to access this resource. Please contact support." ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message if the broadcast has already started sending or already sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Broadcast is already sending." ] } } } } }, "x-mcp": { "enabled": true } }, "get": { "summary": "Get a broadcast", "tags": [ "Broadcasts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "[]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 59 } ], "responses": { "200": { "description": "Returns the broadcast details", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcast": { "type": "object", "properties": { "id": { "type": "integer" }, "publication_id": { "type": "integer", "description": "Identifier of the underlying publication. Broadcasts that are also published as posts share the same `publication_id` — use it to match a broadcast to its post via `GET /v4/posts`." }, "created_at": { "type": "string" }, "subject": { "type": "string" }, "preview_text": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "public": { "type": "boolean" }, "published_at": { "type": "string", "nullable": true }, "send_at": { "type": "string", "nullable": true }, "thumbnail_alt": { "type": "string", "nullable": true }, "thumbnail_url": { "type": "string", "nullable": true }, "public_url": { "type": "string", "nullable": true }, "email_address": { "type": "string", "nullable": true }, "email_template": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "subscriber_filter": { "type": "array", "items": { "type": "object", "properties": { "all": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ] } } }, "required": [ "all" ] } }, "status": { "type": "string" } }, "required": [ "id", "publication_id", "created_at", "subject", "preview_text", "description", "public", "published_at", "send_at", "thumbnail_alt", "thumbnail_url", "content", "public_url", "email_address", "email_template", "subscriber_filter" ] } }, "required": [ "broadcast" ] }, "example": { "broadcast": { "id": 57, "publication_id": 48, "created_at": "2023-02-17T11:43:55Z", "subject": "You'll never guess...", "preview_text": null, "description": null, "content": null, "public": false, "published_at": null, "send_at": null, "thumbnail_alt": null, "thumbnail_url": null, "public_url": null, "email_address": "greetings@kit.dev", "email_template": { "id": 6, "name": "Text Only" }, "subscriber_filter": [ { "all": [ { "type": "all_subscribers" } ] } ], "status": "draft" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "put": { "summary": "Update a broadcast", "description": "Update an existing broadcast. Continue to draft or schedule to send a broadcast to all or a subset of your subscribers.

To save a draft, set `public` to false.

To schedule the broadcast for sending, set `public` to true and provide `send_at`. Scheduled broadcasts should contain a subject and your content, at a minimum.

We currently support targeting your subscribers based on segment or tag ids.", "tags": [ "Broadcasts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 106 } ], "responses": { "200": { "description": "Updates the broadcast and returns its details", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcast": { "type": "object", "properties": { "id": { "type": "integer" }, "publication_id": { "type": "integer" }, "created_at": { "type": "string" }, "subject": { "type": "string" }, "preview_text": { "type": "string" }, "description": { "type": "string" }, "content": { "type": "string" }, "public": { "type": "boolean" }, "published_at": { "type": "string" }, "send_at": { "type": "string" }, "thumbnail_alt": { "nullable": true }, "thumbnail_url": { "nullable": true }, "public_url": { "type": "string" }, "email_address": { "type": "string" }, "email_template": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "subscriber_filter": { "type": "array", "items": { "type": "object", "properties": { "all": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] } } }, "required": [ "all" ] } }, "status": { "type": "string" } }, "required": [ "id", "publication_id", "created_at", "subject", "preview_text", "description", "public", "published_at", "send_at", "thumbnail_alt", "thumbnail_url", "content", "public_url", "email_address", "email_template", "subscriber_filter" ] } }, "required": [ "broadcast" ] }, "example": { "broadcast": { "id": 92, "publication_id": 83, "created_at": "2023-02-17T11:43:55Z", "subject": "Hello!", "preview_text": "Pleased to meet you!", "description": "Intro email", "content": "

Let me introduce myself

", "public": true, "published_at": "2023-02-17T11:43:55Z", "send_at": "2023-02-17T11:43:55Z", "thumbnail_alt": null, "thumbnail_url": null, "public_url": "https://kit-greetings.kit.com/posts/hello", "email_address": "greetings@kit.dev", "email_template": { "id": 2, "name": "Classic" }, "subscriber_filter": [ { "all": [ { "type": "segment", "ids": [ 54 ] } ] } ], "status": "sending" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "403": { "description": "Returns a 403 with an error message if the current account is unauthorized to create a broadcast", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "You do not have sufficient permissions to access this resource. Please contact support." ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when one or more of the parameters are invalid or the campaign has already started sending", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Email template not found", "Only a single filter group is supported. Use one of `all`, `any`, or `none`." ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email_template_id": { "type": "integer", "description": "Id of the email template to use. Uses the account's default template if not provided. 'Starting point' template is not supported." }, "email_address": { "type": "string", "nullable": true, "description": "The sending email address to use. Uses the account's sending email address if not provided." }, "content": { "type": "string", "description": "The HTML content of the email." }, "description": { "type": "string" }, "public": { "type": "boolean", "description": "`true` to publish this broadcast to the web. The broadcast will appear in a newsletter feed on your Creator Profile and Landing Pages." }, "published_at": { "type": "string", "description": "The published timestamp to display in ISO8601 format. If no timezone is provided, UTC is assumed." }, "send_at": { "type": "string", "description": "The scheduled send time for this broadcast in ISO8601 format. If no timezone is provided, UTC is assumed." }, "thumbnail_alt": { "nullable": true }, "thumbnail_url": { "nullable": true }, "preview_text": { "type": "string" }, "subject": { "type": "string" }, "subscriber_filter": { "type": "array", "description": "Filters your subscribers. At this time, we only support using only one filter group type via the API (e.g. `all`, `any`, or `none` but no combinations). If nothing is provided, will default to all of your subscribers.", "items": { "type": "object", "properties": { "all": { "type": "array", "description": "Filters your subscribers using a logical AND of all provided segment and tag ids, i.e. a subscriber would have to be part of all segments and tags provided", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "`segment` or `tag`" }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] } }, "any": { "type": "array", "description": "Filters your subscribers using a logical OR of all provided segment and tag ids, i.e. a subscriber would have to be part of at least one of the segments or tags provided", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "`segment` or `tag`" }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] }, "nullable": true }, "none": { "type": "array", "description": "Filters your subscribers using a logical NOT of all provided segment and tag ids, i.e. a subscriber would have to be in none of the segments or tags provided", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "`segment` or `tag`" }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] }, "nullable": true } }, "minProperties": 1, "required": [ "all", "any", "none" ] } } }, "required": [ "email_template_id", "email_address", "content", "description", "public", "published_at", "send_at", "thumbnail_alt", "thumbnail_url", "preview_text", "subject", "subscriber_filter" ] }, "example": { "email_template_id": 2, "email_address": null, "content": "

Let me introduce myself

", "description": "Intro email", "public": true, "published_at": "2023-02-17T11:43:55+00:00", "send_at": "2023-02-17T11:43:55+00:00", "thumbnail_alt": null, "thumbnail_url": null, "preview_text": "Pleased to meet you!", "subject": "Hello!", "subscriber_filter": [ { "all": [ { "type": "segment", "ids": [ 54 ] } ], "any": null, "none": null } ] } } } }, "x-mcp": { "enabled": true } } }, "/v4/bulk/custom_fields": { "post": { "summary": "Bulk create custom fields", "description": "See \"[Bulk & async processing](#bulk-amp-async-processing)\" for more information.", "tags": [ "Custom Fields" ], "security": [ { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Creates the custom_fields synchronously when 100 or less custom fields are requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "key", "label", "name", "created_at" ] } }, "failures": { "type": "array", "items": {} } }, "required": [ "custom_fields", "failures" ] }, "example": { "custom_fields": [ { "id": 143, "key": "existing_custom_field", "label": "Existing Custom Field", "name": "ck_field_143_existing_custom_field", "created_at": "2023-02-17T11:43:55Z" }, { "id": 145, "key": "interests", "label": "Interests", "name": "ck_field_145_interests", "created_at": "2023-02-17T11:43:55Z" }, { "id": 144, "key": "last_name", "label": "Last name", "name": "ck_field_144_last_name", "created_at": "2023-02-17T11:43:55Z" } ], "failures": [] } } } }, "202": { "description": "Creates or updates custom_fields asynchronously when more than 100 custom fields are requested", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "413": { "description": "Returns a 413 when the size of the request would exceed the account's data limit for enqueued bulk requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "This request exceeds your queued bulk requests limit. Please wait while we process your existing requests and try again later." ] } } } }, "422": { "description": "Returns a 422 when `custom_fields` is empty or not an array", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "No custom fields included for processing" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" } }, "required": [ "label" ] } }, "callback_url": { "type": "string", "nullable": true } }, "required": [ "custom_fields" ] }, "example": { "custom_fields": [ { "label": "Test Custom Field 0" }, { "label": "Test Custom Field 1" }, { "label": "Test Custom Field 2" }, { "label": "Test Custom Field 3" } ], "callback_url": null } } } } } }, "/v4/bulk/custom_fields/subscribers": { "post": { "summary": "Bulk update subscriber custom field values", "tags": [ "Custom Fields" ], "security": [ { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Creates or updates custom field values synchronously when 100 or less values are requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "subscriber_id": { "type": "integer" }, "subscriber_custom_field_id": { "type": "integer" }, "value": { "type": "string" } }, "required": [ "subscriber_id", "subscriber_custom_field_id", "value" ] } }, "failures": { "type": "array", "items": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "custom_field_value": { "type": "object", "properties": { "subscriber_id": { "type": "integer", "nullable": true }, "subscriber_custom_field_id": { "type": "integer" }, "value": { "type": "string" } }, "required": [ "subscriber_id", "subscriber_custom_field_id", "value" ] } }, "required": [ "errors", "custom_field_value" ] } } }, "required": [ "custom_field_values", "failures" ] }, "example": { "custom_field_values": [ { "subscriber_id": 615, "subscriber_custom_field_id": 156, "value": "Smith" }, { "subscriber_id": 615, "subscriber_custom_field_id": 157, "value": "Acme Inc" } ], "failures": [ { "errors": [ "Subscriber does not exist" ], "custom_field_value": { "subscriber_id": null, "subscriber_custom_field_id": 156, "value": "Jones" } }, { "errors": [ "Custom field does not exist" ], "custom_field_value": { "subscriber_id": 615, "subscriber_custom_field_id": 999999, "value": "Test" } } ] } } } }, "202": { "description": "Creates or updates custom field values asynchronously when more than 100 values are requested", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "413": { "description": "Returns a 413 when the size of the request would exceed the account's data limit for enqueued bulk requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "This request exceeds your queued bulk requests limit. Please wait while we process your existing requests and try again later." ] } } } }, "422": { "description": "Returns a 422 when `custom_field_values` is empty or not an array", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "No custom field values included for processing" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "subscriber_id": { "type": "integer", "nullable": true }, "subscriber_custom_field_id": { "type": "integer" }, "value": { "type": "string" } }, "required": [ "subscriber_id", "subscriber_custom_field_id", "value" ] } }, "callback_url": { "nullable": true } }, "required": [ "custom_field_values", "callback_url" ] }, "example": { "custom_field_values": [ { "subscriber_id": 0, "subscriber_custom_field_id": 0, "value": "value_0" }, { "subscriber_id": 1, "subscriber_custom_field_id": 1, "value": "value_1" }, { "subscriber_id": 2, "subscriber_custom_field_id": 2, "value": "value_2" }, { "subscriber_id": 3, "subscriber_custom_field_id": 3, "value": "value_3" } ], "callback_url": null } } } } } }, "/v4/bulk/forms/subscribers": { "post": { "summary": "Bulk add subscribers to forms", "description": "Adding subscribers to double opt-in forms will trigger sending an Incentive Email. Subscribers already added to the specified form will not receive the Incentive Email again. For more information about double opt-in see \"[Double opt-in](#double-opt-in)\".

The subscribers being added to the form must already exist. Subscribers can be created in bulk using the \"[Bulk create subscriber](#bulk-create-subscribers)\" endpoint.

See \"[Bulk & async processing](#bulk-amp-async-processing)\" for more information.", "tags": [ "Forms" ], "security": [ { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Adds subscribers to forms synchronously when 100 or less form/subscribers are requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "email_address": { "type": "string" }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "referrer": { "type": "string" }, "referrer_utm_parameters": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" } }, "required": [ "source", "medium", "campaign", "term", "content" ] } }, "required": [ "id", "first_name", "email_address", "created_at", "added_at", "referrer", "referrer_utm_parameters" ] } }, "failures": { "type": "array", "items": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "subscription": { "type": "object", "properties": { "form_id": { "type": "integer", "nullable": true }, "subscriber_id": { "nullable": true, "type": "integer" }, "referrer": { "type": "string" } }, "required": [ "form_id", "subscriber_id", "referrer" ] } }, "required": [ "errors", "subscription" ] } } }, "required": [ "subscribers", "failures" ] }, "example": { "subscribers": [ { "id": 633, "first_name": "Sub", "email_address": "sub@example.com", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off", "referrer_utm_parameters": { "source": "facebook", "medium": "cpc", "campaign": "black_friday", "term": "car_owners", "content": "get_10_off" } }, { "id": 633, "first_name": "Sub", "email_address": "sub@example.com", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off", "referrer_utm_parameters": { "source": "facebook", "medium": "cpc", "campaign": "black_friday", "term": "car_owners", "content": "get_10_off" } } ], "failures": [ { "errors": [ "Subscriber does not exist" ], "subscription": { "form_id": 136, "subscriber_id": null, "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off" } }, { "errors": [ "Form does not exist" ], "subscription": { "form_id": null, "subscriber_id": 633, "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off" } } ] } } } }, "202": { "description": "Adds subscribers to forms asynchronously when more than 100 form/subscribers are requested", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "413": { "description": "Returns a 413 when the size of the request would exceed the account's data limit for enqueued bulk requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "This request exceeds your queued bulk requests limit. Please wait while we process your existing requests and try again later." ] } } } }, "422": { "description": "Returns a 422 when `additions` is empty or not an array", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "No additions included for processing" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "additions": { "type": "array", "items": { "type": "object", "properties": { "form_id": { "type": "integer", "nullable": true }, "subscriber_id": { "type": "integer", "nullable": true }, "referrer": { "type": "string" } }, "required": [ "form_id", "subscriber_id" ] } }, "callback_url": { "type": "string", "nullable": true } }, "required": [ "additions" ] }, "example": { "additions": [ { "form_id": 0, "subscriber_id": 0 }, { "form_id": 1, "subscriber_id": 1 }, { "form_id": 2, "subscriber_id": 2 }, { "form_id": 3, "subscriber_id": 3 } ], "callback_url": null } } } } } }, "/v4/bulk/subscribers": { "post": { "summary": "Bulk create subscribers", "description": "See \"[Bulk & async processing](#bulk-amp-async-processing)\" for more information.", "tags": [ "Subscribers" ], "security": [ { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Creates or updates the subscribers synchronously when 100 or less subscribers are requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" } }, "required": [ "id", "first_name", "email_address", "state", "created_at" ] } }, "failures": { "type": "array", "items": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "first_name": { "type": "string" }, "email_address": { "type": "string", "nullable": true }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string", "nullable": true } }, "required": [ "first_name", "email_address", "state", "created_at" ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "subscriber", "errors" ] } } }, "required": [ "subscribers", "failures" ] }, "example": { "subscribers": [ { "id": 596, "first_name": null, "email_address": "brooke@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z" }, { "id": 597, "first_name": "Camille", "email_address": "camille@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z" }, { "id": 595, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z" } ], "failures": [ { "subscriber": { "first_name": "Benito", "email_address": null, "state": "active", "created_at": null }, "errors": [ "Email address is invalid" ] } ] } } } }, "202": { "description": "Creates or updates subscribers asynchronously when more than 100 subscribers are requested", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "403": { "description": "Returns a 403 when the number of subscribers in the request would exceed the account's subscriber limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "This request would exceed your subscriber limit" ] } } } }, "413": { "description": "Returns a 413 when the size of the request would exceed the account's data limit for enqueued bulk requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "This request exceeds your queued bulk requests limit. Please wait while we process your existing requests and try again later." ] } } } }, "422": { "description": "Returns a 422 when `subscribers` is empty or not an array", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "No subscribers included for processing" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": { "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true, "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] } } } }, "callback_url": { "type": "string", "nullable": true } }, "required": [ "subscribers" ] }, "example": { "subscribers": [ { "first_name": "Test Subscriber 0", "email_address": "subscriber_0@convertkit.dev" }, { "first_name": "Test Subscriber 1", "email_address": "subscriber_1@convertkit.dev" }, { "first_name": "Test Subscriber 2", "email_address": "subscriber_2@convertkit.dev" }, { "first_name": "Test Subscriber 3", "email_address": "subscriber_3@convertkit.dev" } ], "callback_url": null } } } } } }, "/v4/bulk/tags": { "post": { "summary": "Bulk create tags", "description": "See \"[Bulk & async processing](#bulk-amp-async-processing)\" for more information.", "tags": [ "Tags" ], "security": [ { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Creates or returns existing tags synchronously when 100 or less tags are requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "created_at" ] } }, "failures": { "type": "array", "items": {} } }, "required": [ "tags", "failures" ] }, "example": { "tags": [ { "id": 68, "name": "Existing Tag", "created_at": "2023-02-17T11:43:55Z" }, { "id": 69, "name": "Attended Event", "created_at": "2023-02-17T11:43:55Z" }, { "id": 70, "name": "Newsletter", "created_at": "2023-02-17T11:43:55Z" }, { "id": 71, "name": "Re-engage", "created_at": "2023-02-17T11:43:55Z" } ], "failures": [] } } } }, "202": { "description": "Creates or returns existing tags asynchronously when more than 100 tags are requested", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "413": { "description": "Returns a 413 when the size of the request would exceed the account's data limit for enqueued bulk requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "This request exceeds your queued bulk requests limit. Please wait while we process your existing requests and try again later." ] } } } }, "422": { "description": "Returns a 422 when `tags` is empty or not an array", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "No tags included for processing" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "callback_url": { "type": "string", "nullable": true } }, "required": [ "tags" ] }, "example": { "tags": [ { "name": "Test Tag 0" }, { "name": "Test Tag 1" }, { "name": "Test Tag 2" }, { "name": "Test Tag 3" } ], "callback_url": null } } } } } }, "/v4/bulk/tags/subscribers": { "delete": { "summary": "Bulk remove tags from subscribers", "description": "See \"[Bulk & async processing](#bulk-amp-async-processing)\" for more information.", "tags": [ "Tags" ], "security": [ { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Deletes the taggings synchronously when 100 or less tags/subscribers are provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "failures": { "type": "array", "items": {} } }, "required": [ "failures" ] }, "example": { "failures": [] } } } }, "202": { "description": "Destroys taggings asynchronously when more than 100 tags/subscribers are provided", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "413": { "description": "Returns a 413 when the size of the request would exceed the account's data limit for enqueued bulk requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "This request exceeds your queued bulk requests limit. Please wait while we process your existing requests and try again later." ] } } } }, "422": { "description": "Returns a 422 when `taggings` is empty or not an array", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "No taggings included for processing" ] } } } } } }, "post": { "summary": "Bulk tag subscribers", "description": "The subscribers being tagged must already exist. Subscribers can be created in bulk using the \"[Bulk create subscriber](#bulk-create-subscribers)\" endpoint.

See \"[Bulk & async processing](#bulk-amp-async-processing)\" for more information.", "tags": [ "Tags" ], "security": [ { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Creates the taggings synchronously when 100 or less tags/subscribers are requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "email_address": { "type": "string" }, "created_at": { "type": "string" }, "tagged_at": { "type": "string" } }, "required": [ "id", "first_name", "email_address", "created_at", "tagged_at" ] } }, "failures": { "type": "array", "items": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "tagging": { "type": "object", "properties": { "tag_id": { "type": "integer", "nullable": true }, "subscriber_id": { "nullable": true, "type": "integer" } }, "required": [ "tag_id", "subscriber_id" ] } }, "required": [ "errors", "tagging" ] } } }, "required": [ "subscribers", "failures" ] }, "example": { "subscribers": [ { "id": 649, "first_name": "Sub", "email_address": "sub@example.com", "created_at": "2023-02-17T11:43:55Z", "tagged_at": "2023-02-17T11:43:55Z" }, { "id": 649, "first_name": "Sub", "email_address": "sub@example.com", "created_at": "2023-02-17T11:43:55Z", "tagged_at": "2023-02-17T11:43:55Z" } ], "failures": [ { "errors": [ "Subscriber does not exist" ], "tagging": { "tag_id": 83, "subscriber_id": null } }, { "errors": [ "Tag does not exist" ], "tagging": { "tag_id": null, "subscriber_id": 649 } } ] } } } }, "202": { "description": "Creates or updates taggings asynchronously when more than 100 tags/subscribers are requested", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "413": { "description": "Returns a 413 when the size of the request would exceed the account's data limit for enqueued bulk requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "This request exceeds your queued bulk requests limit. Please wait while we process your existing requests and try again later." ] } } } }, "422": { "description": "Returns a 422 when `taggings` is empty or not an array", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "No taggings included for processing" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "taggings": { "type": "array", "items": { "type": "object", "properties": { "tag_id": { "type": "integer", "nullable": true }, "subscriber_id": { "type": "integer", "nullable": true } }, "required": [ "tag_id", "subscriber_id" ] } }, "callback_url": { "type": "string", "nullable": true } }, "required": [ "taggings" ] }, "example": { "taggings": [ { "tag_id": 0, "subscriber_id": 0 }, { "tag_id": 1, "subscriber_id": 1 }, { "tag_id": 2, "subscriber_id": 2 }, { "tag_id": 3, "subscriber_id": 3 } ], "callback_url": null } } } } } }, "/v4/custom_fields": { "get": { "summary": "List custom fields", "description": "A custom field allows you to collect subscriber information beyond the standard fields of first name and email address. An example would be a custom field called last name so you can get the full names of your subscribers.

You create a custom field, and then you're able to use that in your forms or emails.", "tags": [ "Custom Fields" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of all custom fields for your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "name", "key", "label" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "custom_fields", "pagination" ] }, "example": { "custom_fields": [ { "id": 1, "name": "ck_field_1_last_name", "key": "last_name", "label": "Last name" } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzFd", "end_cursor": "WzFd", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Create a custom field", "description": "Create a custom field for your account. The label field must be unique to your account. Whitespace will be removed from the beginning and the end of your label.

Additionally, a key field and a name field will be generated for you. The key is an ASCII-only, lowercased, underscored representation of your label. This key must be unique to your account. Keys are used in personalization tags in sequences and broadcasts. Names are unique identifiers for use in the HTML of custom forms. They are made up of a combination of ID and the key of the custom field prefixed with \"ck_field\".", "tags": [ "Custom Fields" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Returns a 200 and the custom field if it already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_field": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "name", "key", "label" ] } }, "required": [ "custom_field" ] }, "example": { "custom_field": { "id": 8, "name": "ck_field_8_interests", "key": "interests", "label": "Interests" } } } } }, "201": { "description": "Creates a new custom field and returns its details", "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_field": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "name", "key", "label" ] } }, "required": [ "custom_field" ] }, "example": { "custom_field": { "id": 6, "name": "ck_field_6_interests", "key": "interests", "label": "Interests" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "422": { "description": "Returns a 422 with an error message when the label is missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Label can't be blank" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" } }, "required": [ "label" ] }, "example": { "label": "Interests" } } } }, "x-mcp": { "enabled": true } } }, "/v4/custom_fields/{id}": { "delete": { "summary": "Delete custom field", "description": "This will remove all data in this field from your subscribers.", "tags": [ "Custom Fields" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 50 } ], "responses": { "204": { "description": "Deletes the custom field" }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 when the custom field cannot be deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Unable to destroy the custom field." ] } } } } }, "x-mcp": { "enabled": true } }, "put": { "summary": "Update a custom field", "description": "Updates a custom field label (see [Create a custom field](/api-reference/custom-fields/create-a-custom-field) for more information on labels). Note that the key will change but the name remains the same when the label is updated.

Warning: An update to a custom field will break all of the liquid personalization tags in emails that reference it - e.g. if you update a `Zip_Code` custom field to `Post_Code`, all liquid tags referencing `{{ subscriber.Zip_Code }}` would no longer work and need to be replaced with `{{ subscriber.Post_Code }}`.", "tags": [ "Custom Fields" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 29 } ], "responses": { "200": { "description": "Updates the custom field and returns its details", "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_field": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "name", "key", "label" ] } }, "required": [ "custom_field" ] }, "example": { "custom_field": { "id": 27, "name": "ck_field_27_last_name", "key": "lastname", "label": "Last name" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error mesage when one or more of the parameters are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Label can't be blank" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" } }, "required": [ "label" ] }, "example": { "label": "Last name" } } } }, "x-mcp": { "enabled": true } } }, "/v4/email_templates": { "get": { "summary": "List email templates", "tags": [ "Email Templates" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of all email templates for your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "email_templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_default": { "type": "boolean" }, "category": { "type": "string" } }, "required": [ "id", "name", "is_default", "category" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "email_templates", "pagination" ] }, "example": { "email_templates": [ { "id": 36, "name": "Custom HTML Template", "is_default": false, "category": "HTML" }, { "id": 35, "name": "Story", "is_default": false, "category": "Starting point" }, { "id": 6, "name": "Text Only", "is_default": true, "category": "HTML" }, { "id": 4, "name": "Modern", "is_default": false, "category": "HTML" }, { "id": 2, "name": "Classic", "is_default": false, "category": "HTML" }, { "id": 1, "name": "Card", "is_default": false, "category": "HTML" } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzM2XQ==", "end_cursor": "WzFd", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/forms": { "get": { "summary": "List forms", "tags": [ "Forms" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "status", "description": "Filter forms that have this status (`active`, `archived`, `trashed`, or `all`). Defaults to `active`.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "archived", "trashed", "all" ], "nullable": true } }, { "name": "type", "description": "Filter forms and landing pages by type. Use `embed` for embedded forms. Use `hosted` for landing pages.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of all forms and landing pages (embedded and hosted) for your account (including active and archived)", "content": { "application/json": { "schema": { "type": "object", "properties": { "forms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "string" }, "type": { "type": "string" }, "format": { "nullable": true }, "embed_js": { "type": "string" }, "embed_url": { "type": "string" }, "archived": { "type": "boolean" }, "uid": { "type": "string" }, "subscriber_count": { "type": "integer" } }, "required": [ "id", "name", "created_at", "type", "format", "embed_js", "embed_url", "archived", "uid" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "forms", "pagination" ] }, "example": { "forms": [ { "id": 53, "name": "Sign up", "created_at": "2023-02-17T11:43:55Z", "type": "embed", "format": null, "embed_js": "https://kit-greetings.kit.com/f049e3d9ab/index.js", "embed_url": "https://kit-greetings.kit.com/f049e3d9ab", "archived": false, "uid": "f049e3d9ab", "subscriber_count": 0 }, { "id": 52, "name": "Lead gen", "created_at": "2023-02-17T11:43:55Z", "type": "hosted", "format": null, "embed_js": "https://kit-greetings.kit.com/ae7c1adaa1/index.js", "embed_url": "https://kit-greetings.kit.com/ae7c1adaa1", "archived": false, "uid": "ae7c1adaa1", "subscriber_count": 0 } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzUzXQ==", "end_cursor": "WzUyXQ==", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/forms/{form_id}/subscribers": { "get": { "summary": "List subscribers for a form", "tags": [ "Forms" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "added_after", "description": "Filter subscribers who have been added to the form after this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-02-14T11:43:55Z" }, { "name": "added_before", "description": "Filter subscribers who have been added to the form before this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-02-18T11:43:55Z" }, { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "created_after", "description": "Filter subscribers who have been created after this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-01-17T11:43:55Z" }, { "name": "created_before", "description": "Filter subscribers who have been created before this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-02-18T11:43:55Z" }, { "name": "form_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 169 }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "slim", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false, "description": "When `true`, omits expensive optional fields from the response. Produces a faster, smaller response — useful when extra fields are not needed." }, { "name": "status", "description": "Filter subscribers who have this status (`active`, `inactive`, `bounced`, `complained`, `cancelled` or `all`). Defaults to `active`.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "bounced", "complained", "cancelled", "all" ] }, "example": "all" } ], "responses": { "200": { "description": "Returns a paginated list of subscribers for the specified form", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": { "category": { "type": "string", "nullable": true } }, "required": [ "category" ] }, "referrer": { "type": "string" }, "referrer_utm_parameters": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" } }, "required": [ "source", "medium", "campaign", "term", "content" ] } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "referrer", "referrer_utm_parameters", "fields" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "subscribers", "pagination" ] }, "example": { "subscribers": [ { "id": 673, "first_name": null, "email_address": "subscriber357@kit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off", "referrer_utm_parameters": { "source": "facebook", "medium": "cpc", "campaign": "black_friday", "term": "car_owners", "content": "get_10_off" }, "fields": { "category": "One" } }, { "id": 672, "first_name": null, "email_address": "subscriber356@kit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off", "referrer_utm_parameters": { "source": "facebook", "medium": "cpc", "campaign": "black_friday", "term": "car_owners", "content": "get_10_off" }, "fields": { "category": null } }, { "id": 671, "first_name": null, "email_address": "subscriber355@kit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off", "referrer_utm_parameters": { "source": "facebook", "medium": "cpc", "campaign": "black_friday", "term": "car_owners", "content": "get_10_off" }, "fields": { "category": null } } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzY3M10=", "end_cursor": "WzY3MV0=", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Add subscriber to form by email address", "description": "The subscriber being added to the form must already exist. Subscribers can be created using the \"[Create a subscriber](#create-a-subscriber)\" endpoint.", "tags": [ "Forms" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "form_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 234 } ], "responses": { "200": { "description": "Returns a 200 when the subscriber has already been added to the form", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": {} }, "referrer": { "type": "string" }, "referrer_utm_parameters": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" } }, "required": [ "source", "medium", "campaign", "term", "content" ] } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "referrer", "referrer_utm_parameters", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 785, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": {}, "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off", "referrer_utm_parameters": { "source": "facebook", "medium": "cpc", "campaign": "black_friday", "term": "car_owners", "content": "get_10_off" } } } } } }, "201": { "description": "Adds the subscriber to the form", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": {} }, "referrer": { "type": "string" }, "referrer_utm_parameters": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" } }, "required": [ "source", "medium", "campaign", "term", "content" ] } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "referrer", "referrer_utm_parameters", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 786, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": {}, "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off", "referrer_utm_parameters": { "source": "facebook", "medium": "cpc", "campaign": "black_friday", "term": "car_owners", "content": "get_10_off" } } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when missing email address", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Either subscriber id or email address is required to add subscriber to form" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email_address": { "type": "string" }, "referrer": { "type": "string", "nullable": true } }, "required": [ "email_address" ] }, "example": { "email_address": "alice@convertkit.dev", "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off" } } } }, "x-mcp": { "enabled": true } } }, "/v4/forms/{form_id}/subscribers/{id}": { "post": { "summary": "Add subscriber to form", "description": "The subscriber being added to the form must already exist. Subscribers can be created using the \"[Create a subscriber](#create-a-subscriber)\" endpoint.", "tags": [ "Forms" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "form_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 210 }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 767 } ], "responses": { "200": { "description": "Returns a 200 when the subscriber has already been added to the form", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": {} }, "referrer": { "type": "string" }, "referrer_utm_parameters": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" } }, "required": [ "source", "medium", "campaign", "term", "content" ] } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "referrer", "referrer_utm_parameters", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 760, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": {}, "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off", "referrer_utm_parameters": { "source": "facebook", "medium": "cpc", "campaign": "black_friday", "term": "car_owners", "content": "get_10_off" } } } } } }, "201": { "description": "Adds the subscriber to the form", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "nullable": true, "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": {} }, "referrer": { "type": "string" }, "referrer_utm_parameters": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" } }, "required": [ "source", "medium", "campaign", "term", "content" ] } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "referrer", "referrer_utm_parameters", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 762, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": {}, "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off", "referrer_utm_parameters": { "source": "facebook", "medium": "cpc", "campaign": "black_friday", "term": "car_owners", "content": "get_10_off" } } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "referrer": { "type": "string" } }, "required": [ "referrer" ] }, "example": { "referrer": "https://mywebsite.com/bfpromo/?utm_source=facebook&utm_medium=cpc&utm_campaign=black_friday&utm_term=car_owners&utm_content=get_10_off" } } } }, "x-mcp": { "enabled": true } } }, "/v4/posts": { "get": { "summary": "List posts", "tags": [ "Posts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_content", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false, "description": "To include the `content` field on each post in the response, use `true`. Omitted by default because it significantly increases response size and latency for large collections." }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of all posts for your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "publication_id": { "type": "integer", "description": "Identifier of the underlying publication. Posts that were also sent as broadcasts share the same `publication_id` — use it to match a post to its broadcast via `GET /v4/broadcasts`." }, "created_at": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "description": { "nullable": true }, "meta_description": { "nullable": true }, "status": { "type": "string" }, "published_at": { "type": "string", "nullable": true }, "sent_at": { "type": "string", "nullable": true }, "thumbnail_alt": { "nullable": true }, "thumbnail_url": { "nullable": true }, "is_paid": { "type": "boolean" }, "public_url": { "type": "string", "nullable": true } }, "required": [ "id", "publication_id", "created_at", "title", "slug", "description", "meta_description", "status", "published_at", "sent_at", "thumbnail_alt", "thumbnail_url", "is_paid", "public_url" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "posts", "pagination" ] }, "example": { "posts": [ { "id": 3, "publication_id": 127, "created_at": "2026-06-11T16:15:02Z", "title": "Draft Post", "slug": null, "description": null, "meta_description": null, "status": "draft", "published_at": null, "sent_at": null, "thumbnail_alt": null, "thumbnail_url": null, "is_paid": false, "public_url": null }, { "id": 2, "publication_id": 126, "created_at": "2026-06-11T16:15:02Z", "title": "Email and Web Post", "slug": "email-and-web-post", "description": null, "meta_description": null, "status": "published", "published_at": "2026-06-09T16:15:02Z", "sent_at": "2026-06-11T16:15:02Z", "thumbnail_alt": null, "thumbnail_url": null, "is_paid": false, "public_url": "https://asdf.kit.com/posts/email-and-web-post" }, { "id": 1, "publication_id": 125, "created_at": "2026-06-11T16:15:02Z", "title": "Web Only Post", "slug": "web-only-post", "description": null, "meta_description": null, "status": "published", "published_at": "2026-06-10T16:15:02Z", "sent_at": null, "thumbnail_alt": null, "thumbnail_url": null, "is_paid": false, "public_url": "https://asdf.kit.com/posts/web-only-post" } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzNd", "end_cursor": "WzFd", "per_page": 500 } } } } } }, "x-mcp": { "enabled": true } } }, "/v4/posts/{id}": { "get": { "summary": "Get a post", "tags": [ "Posts" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 29 } ], "responses": { "200": { "description": "Returns the post details", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "integer" }, "publication_id": { "type": "integer", "description": "Identifier of the underlying publication. Posts that were also sent as broadcasts share the same `publication_id` — use it to match a post to its broadcast via `GET /v4/broadcasts`." }, "created_at": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "description": { "nullable": true }, "meta_description": { "nullable": true }, "status": { "type": "string" }, "published_at": { "type": "string" }, "sent_at": { "nullable": true }, "thumbnail_alt": { "nullable": true }, "thumbnail_url": { "nullable": true }, "is_paid": { "type": "boolean" }, "public_url": { "type": "string" }, "content": { "type": "string" } }, "required": [ "id", "publication_id", "created_at", "title", "slug", "description", "meta_description", "status", "published_at", "sent_at", "thumbnail_alt", "thumbnail_url", "is_paid", "public_url", "content" ] } }, "required": [ "post" ] }, "example": { "post": { "id": 25, "publication_id": 149, "created_at": "2026-06-11T16:15:07Z", "title": "My Newsletter Post", "slug": "my-newsletter-post", "description": null, "meta_description": null, "status": "published", "published_at": "2026-06-10T16:15:07Z", "sent_at": null, "thumbnail_alt": null, "thumbnail_url": null, "is_paid": false, "public_url": "https://asdf.kit.com/posts/my-newsletter-post", "content": "\n\n" } } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/purchases": { "get": { "summary": "List purchases", "tags": [ "Purchases" ], "security": [ { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of all purchases for your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "transaction_id": { "type": "string" }, "subscriber_id": { "type": "integer" }, "status": { "type": "string" }, "email_address": { "type": "string", "description": "The subscriber that the purchase belongs to" }, "currency": { "type": "string", "description": "3 letter currency code (e.g. `USD`)" }, "transaction_time": { "type": "string" }, "subtotal": { "type": "number", "format": "float" }, "discount": { "type": "number", "format": "float" }, "tax": { "type": "number", "format": "float" }, "total": { "type": "number", "format": "float" }, "products": { "type": "array", "description": "Array of purchased products", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "Product quantity" }, "lid": { "type": "string", "description": "Each product should have a unique `lid` (i.e., line item identifier) for this purchase." }, "unit_price": { "type": "number", "format": "float", "description": "Product price" }, "sku": { "nullable": true, "description": "Product sku" }, "name": { "type": "string", "description": "Product name" }, "pid": { "type": "string", "description": "This is your identifier for a product. Each product provided in the `products` array must have a unique pid. Variants of the same product should have the same pid." } }, "required": [ "quantity", "lid", "unit_price", "sku", "name", "pid" ] } } }, "required": [ "id", "transaction_id", "status", "email_address", "subscriber_id", "currency", "transaction_time", "subtotal", "discount", "tax", "total", "products" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "purchases", "pagination" ] }, "example": { "purchases": [ { "id": 3, "transaction_id": "512-41-4101", "status": "paid", "email_address": "pru.magoo@convertkit.dev", "subscriber_id": 12, "currency": "USD", "transaction_time": "2023-02-17T11:43:55Z", "subtotal": 5.0, "discount": 0.0, "tax": 0.0, "total": 5.0, "products": [ { "quantity": 1, "lid": "000-13-0000", "unit_price": 0.05, "sku": null, "name": "Tip", "pid": "111-75-7524" } ] }, { "id": 2, "transaction_id": "323-79-5320", "status": "paid", "email_address": "pru.magoo@convertkit.dev", "subscriber_id": 12, "currency": "USD", "transaction_time": "2023-02-17T11:43:55Z", "subtotal": 10.0, "discount": 0.0, "tax": 1.05, "total": 11.05, "products": [ { "quantity": 1, "lid": "000-12-0000", "unit_price": 0.1, "sku": null, "name": "Monthly Game Review", "pid": "000-11-0000" } ] }, { "id": 1, "transaction_id": "796-92-4892", "status": "paid", "email_address": "pru.magoo@convertkit.dev", "subscriber_id": 12, "currency": "USD", "transaction_time": "2023-02-17T11:43:55Z", "subtotal": 78.66, "discount": 5.0, "tax": 7.87, "total": 81.53, "products": [ { "quantity": 1, "lid": "811-75-7900", "unit_price": 23.22, "sku": null, "name": "Phantom Hourglass", "pid": "804-02-4430" }, { "quantity": 1, "lid": "766-49-1241", "unit_price": 32.22, "sku": null, "name": "Twilight Princess", "pid": "833-51-1151" } ] } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzNd", "end_cursor": "WzFd", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } } }, "post": { "summary": "Create a purchase", "tags": [ "Purchases" ], "security": [ { "OAuth2": [] } ], "parameters": [], "responses": { "201": { "description": "Creates a purchase for the provided subscriber and returns its details. It also creates products if they don't exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "integer" }, "transaction_id": { "type": "string" }, "subscriber_id": { "type": "integer" }, "status": { "type": "string" }, "email_address": { "type": "string", "description": "The subscriber that the purchase belongs to" }, "currency": { "type": "string", "description": "3 letter currency code (e.g. `USD`)" }, "transaction_time": { "type": "string" }, "subtotal": { "type": "number", "format": "float" }, "discount": { "type": "number", "format": "float" }, "tax": { "type": "number", "format": "float" }, "total": { "type": "number", "format": "float" }, "products": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "Product quantity" }, "lid": { "type": "string", "description": "Each product should have a unique `lid` (i.e., line item identifier) for this purchase." }, "unit_price": { "type": "number", "format": "float", "description": "Product price" }, "sku": { "type": "string", "description": "Product sku" }, "name": { "type": "string", "description": "Product name" }, "pid": { "type": "string", "description": "This is your identifier for a product. Each product provided in the `products` array must have a unique pid. Variants of the same product should have the same pid." } }, "required": [ "quantity", "lid", "unit_price", "sku", "name", "pid" ] } } }, "required": [ "id", "transaction_id", "status", "email_address", "subscriber_id", "currency", "transaction_time", "subtotal", "discount", "tax", "total", "products" ] } }, "required": [ "purchase" ] }, "example": { "purchase": { "id": 21, "transaction_id": "796-92-4892", "subscriber_id": 40, "status": "paid", "email_address": "pru.magoo@convertkit.dev", "currency": "USD", "transaction_time": "2023-02-17T11:43:55Z", "subtotal": 78.66, "discount": 5.0, "tax": 7.87, "total": 81.53, "products": [ { "quantity": 1, "lid": "811-75-7900", "unit_price": 23.22, "sku": "SM21-SH-M02-RD-S-001", "name": "Phantom Hourglass", "pid": "804-02-4430" }, { "quantity": 1, "lid": "766-49-1241", "unit_price": 32.22, "sku": "WT21-JK-M03-BK-L-012", "name": "Twilight Princess", "pid": "833-51-1151" }, { "quantity": 1, "lid": "563-95-8878", "unit_price": 23.22, "sku": "FL21-TS-M01-BL-M-020", "name": "Four Swords", "pid": "217-99-4325" } ] } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "422": { "description": "Returns a 422 when one or more of the parameters are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Transaction cannot be blank" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "email_address": { "type": "string", "description": "The subscriber that the purchase belongs to" }, "transaction_id": { "type": "string" }, "status": { "type": "string" }, "subtotal": { "type": "number", "format": "float" }, "tax": { "type": "number", "format": "float" }, "shipping": { "type": "integer" }, "discount": { "type": "number", "format": "float" }, "total": { "type": "number", "format": "float" }, "currency": { "type": "string", "description": "3 letter currency code (e.g. `USD`)" }, "transaction_time": { "type": "string" }, "products": { "type": "array", "description": "Array of purchased products", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Product name" }, "pid": { "type": "string", "description": "This is your identifier for a product. Each product provided in the `products` array must have a unique pid. Variants of the same product should have the same pid." }, "lid": { "type": "string", "description": "Each product should have a unique `lid` (i.e., line item identifier) for this purchase." }, "quantity": { "type": "integer", "description": "Product quantity" }, "unit_price": { "type": "number", "format": "float", "description": "Product price" }, "sku": { "type": "string", "description": "Product sku" } }, "required": [ "name", "pid", "lid", "quantity", "unit_price", "sku" ] } } }, "required": [ "email_address", "transaction_id", "status", "subtotal", "tax", "shipping", "discount", "total", "currency", "transaction_time", "products" ] } }, "required": [ "purchase" ] }, "example": { "purchase": { "email_address": "pru.magoo@convertkit.dev", "transaction_id": "796-92-4892", "status": "paid", "subtotal": 78.66, "tax": 7.87, "shipping": 0, "discount": 5.0, "total": 81.53, "currency": "USD", "transaction_time": "2023-02-17T11:43:55Z", "products": [ { "name": "Phantom Hourglass", "pid": "804-02-4430", "lid": "811-75-7900", "quantity": 1, "unit_price": 23.22, "sku": "SM21-SH-M02-RD-S-001" }, { "name": "Twilight Princess", "pid": "833-51-1151", "lid": "766-49-1241", "quantity": 1, "unit_price": 32.22, "sku": "WT21-JK-M03-BK-L-012" }, { "name": "Four Swords", "pid": "217-99-4325", "lid": "563-95-8878", "quantity": 1, "unit_price": 23.22, "sku": "FL21-TS-M01-BL-M-020" } ] } } } } } } }, "/v4/purchases/{id}": { "get": { "summary": "Get a purchase", "tags": [ "Purchases" ], "security": [ { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 15 } ], "responses": { "200": { "description": "Returns the purchase details", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "integer" }, "transaction_id": { "type": "string" }, "subscriber_id": { "type": "integer" }, "status": { "type": "string" }, "email_address": { "type": "string" }, "currency": { "type": "string" }, "transaction_time": { "type": "string" }, "subtotal": { "type": "number", "format": "float" }, "discount": { "type": "number", "format": "float" }, "tax": { "type": "number", "format": "float" }, "total": { "type": "number", "format": "float" }, "products": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "Product quantity" }, "lid": { "type": "string", "description": "Each product should have a unique `lid` (i.e., line item identifier) for this purchase." }, "unit_price": { "type": "number", "format": "float", "description": "Product price" }, "sku": { "nullable": true }, "name": { "type": "string", "description": "Product name" }, "pid": { "type": "string", "description": "This is your identifier for a product. Each product provided in the `products` array must have a unique pid. Variants of the same product should have the same pid." } }, "required": [ "quantity", "lid", "unit_price", "sku", "name", "pid" ] } } }, "required": [ "id", "transaction_id", "status", "email_address", "subscriber_id", "currency", "transaction_time", "subtotal", "discount", "tax", "total", "products" ] } }, "required": [ "purchase" ] }, "example": { "purchase": { "id": 14, "transaction_id": "796-92-4892", "subscriber_id": 23, "status": "paid", "email_address": "pru.magoo@convertkit.dev", "currency": "USD", "transaction_time": "2023-02-17T11:43:55Z", "subtotal": 78.66, "discount": 5.0, "tax": 7.87, "total": 81.53, "products": [ { "quantity": 1, "lid": "811-75-7900", "unit_price": 23.22, "sku": null, "name": "Phantom Hourglass", "pid": "804-02-4430" }, { "quantity": 1, "lid": "766-49-1241", "unit_price": 32.22, "sku": null, "name": "Twilight Princess", "pid": "833-51-1151" } ] } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } } } }, "/v4/segments": { "get": { "summary": "List segments", "tags": [ "Segments" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of all segments for your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "created_at" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "segments", "pagination" ] }, "example": { "segments": [ { "id": 75, "name": "Segment B", "created_at": "2023-02-17T11:43:55Z" }, { "id": 74, "name": "Segment A", "created_at": "2023-02-17T11:43:55Z" } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "Wzc1XQ==", "end_cursor": "Wzc0XQ==", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/sequences": { "get": { "summary": "List sequences", "description": "Returns every sequence on the account. A sequence is a self-contained set of automated emails — subscribers join, then receive each email in order, governed by per-email `delay_value` / `delay_unit` and the sequence's overall `send_days`, `send_hour`, and `time_zone` schedule.\n\nEach entry carries the schedule defaults plus three behavioural toggles: `active` (whether the sequence is delivering), `repeat` (whether subscribers can re-enter), and `hold` (whether subscribers stay active after receiving every published email — an evergreen pattern). See [Create a sequence](/api-reference/sequences/create-a-sequence) for the full sequence model.\n\nOnce you have a sequence's `id`, [List sequence emails](/api-reference/sequence-emails/list-sequence-emails) returns the individual emails inside it.\n\nFor end-user context on how creators build sequences, see the help articles on [creating and sending a sequence](https://help.kit.com/en/articles/2502629-creating-and-sending-a-sequence-in-kit) and [evergreen content](https://help.kit.com/en/articles/2502575-what-is-evergreen-content).", "tags": [ "Sequences" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of all sequences for your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hold": { "type": "boolean" }, "repeat": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "email_address": { "nullable": true }, "email_template_id": { "nullable": true }, "send_days": { "type": "array", "items": { "type": "string" } }, "send_hour": { "type": "integer" }, "time_zone": { "type": "string" }, "active": { "type": "boolean" }, "exclude_subscriber_sources": { "type": "array", "items": {} }, "email_count": { "type": "integer" }, "subscriber_count": { "type": "integer" } }, "required": [ "id", "name", "hold", "repeat", "created_at" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "sequences", "pagination" ] }, "example": { "sequences": [ { "id": 1, "name": "Evergreen sequence", "hold": false, "repeat": false, "created_at": "2023-02-17T11:43:55Z", "updated_at": "2023-02-17T11:43:55Z", "email_address": null, "email_template_id": null, "email_count": 0, "subscriber_count": 0, "send_days": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "send_hour": 11, "time_zone": "America/New_York", "active": true, "exclude_subscriber_sources": [] } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzFd", "end_cursor": "WzFd", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Create a sequence", "description": "Creates an empty sequence — the container that holds sequence emails. After creating the shell, use [Create a sequence email](/api-reference/sequence-emails/create-a-sequence-email) to populate it.\n\nOnly `name` is required. Every other field has a sensible default: Kit fills in the account's default sending address, a daily send schedule, and the account time zone — and any of these can be tuned later via [Update a sequence](/api-reference/sequences/update-a-sequence).\n\nTwo behavioural toggles worth flagging up front. `repeat` controls whether a subscriber can re-enter the sequence: by default a subscriber receives the emails once and is marked complete, but with `repeat: true`, re-adding the same subscriber via a Visual Automation, Rule, Bulk Action, or Import resets their position to the start. Filters and exclusions still apply across restarts. `hold` (evergreen) keeps subscribers active in the sequence after they've received every published email — useful when you plan to add more emails later. Without `hold`, subscribers transition to Completed and won't pick up future additions.\n\n`exclude_subscriber_sources` lets you exclude subscribers acquired via specific tags, sequences, forms, or segments — they'll skip this sequence entirely.\n\nFor end-user context, see the help articles on [creating and sending a sequence](https://help.kit.com/en/articles/2502629-creating-and-sending-a-sequence-in-kit), [restarting a sequence](https://help.kit.com/en/articles/5022528-restart-a-sequence), and [holding subscribers in evergreen sequences](https://help.kit.com/en/articles/5192801-how-to-hold-subscribers-in-evergreen-sequences).", "tags": [ "Sequences" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "201": { "description": "Creates a new sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hold": { "type": "boolean" }, "repeat": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "email_address": { "type": "string" }, "email_template_id": { "type": "integer" }, "send_days": { "type": "array", "items": { "type": "string" } }, "send_hour": { "type": "integer" }, "time_zone": { "type": "string" }, "active": { "type": "boolean" }, "exclude_subscriber_sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] } }, "email_count": { "type": "integer" }, "subscriber_count": { "type": "integer" } }, "required": [ "id", "name", "hold", "repeat", "created_at", "updated_at", "email_address", "email_template_id", "send_days", "send_hour", "time_zone", "active", "exclude_subscriber_sources" ] } }, "required": [ "sequence" ] }, "example": { "sequence": { "id": 30, "name": "Full Series", "hold": true, "repeat": true, "created_at": "2026-06-11T16:15:56Z", "updated_at": "2026-06-11T16:15:56Z", "email_address": "joe1010@ck.lol", "email_template_id": 38, "send_days": [ "monday", "wednesday", "friday" ], "send_hour": 9, "time_zone": "America/Los_Angeles", "active": true, "exclude_subscriber_sources": [ { "type": "sequence", "ids": [ 29 ] }, { "type": "tag", "ids": [ 2 ] } ], "email_count": 0, "subscriber_count": 0 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "403": { "description": "Returns a 403 with an error message if the current account is unauthorized to create a sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "You do not have sufficient permissions to access this resource. Please contact support." ] } } } }, "422": { "description": "Returns a 422 with an error message when one or more of the parameters were invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "send_hour must be an integer between 0 and 23" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the sequence." }, "email_address": { "type": "string", "description": "The sending email address to use. Uses the account's sending email address if not provided." }, "email_template_id": { "type": "integer", "description": "Id of the email template to use." }, "send_days": { "type": "array", "items": { "type": "string" }, "description": "The days of the week to send the sequence on. Must be one of: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`." }, "send_hour": { "type": "integer", "description": "The hour of the day to send the sequence at. Must be an integer between 0 and 23." }, "time_zone": { "type": "string", "description": "The timezone to use for the sequence. Must be a valid IANA timezone string." }, "active": { "type": "boolean", "description": "`true` to activate the sequence, `false` to deactivate it." }, "repeat": { "type": "boolean", "description": "When `true`, subscribers can restart the sequence multiple times." }, "hold": { "type": "boolean", "description": "When `true`, subscribers added via Visual Automations stay in the sequence after receiving the last email." }, "exclude_subscriber_sources": { "type": "array", "description": "The subscriber sources to exclude from the sequence.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of subscriber source to exclude. Must be one of: `tag`, `sequence`, `form`, `segment`." }, "ids": { "type": "array", "items": { "type": "integer", "description": "The ids of the subscriber sources to exclude." } } }, "required": [ "type", "ids" ] } } } }, "example": { "name": "Full Series", "email_address": "joe1010@ck.lol", "email_template_id": 38, "send_days": [ "monday", "wednesday", "friday" ], "send_hour": 9, "time_zone": "America/Los_Angeles", "active": true, "repeat": true, "hold": true, "exclude_subscriber_sources": [ { "type": "tag", "ids": [ 2 ] }, { "type": "sequence", "ids": [ 29 ] } ] } } } }, "x-mcp": { "enabled": true } } }, "/v4/sequences/{id}": { "delete": { "summary": "Delete a sequence", "description": "Soft-deletes a sequence. The sequence is removed from active delivery immediately, with cleanup of associated state happening in the background.\n\n**Warning:** deleting a sequence with active subscribers stops deliveries to those subscribers — they will not receive remaining emails, and any Visual Automations referencing the sequence will need to be updated. Confirm the sequence is not in active use before deleting.\n\nIf you want to pause rather than delete, use [Update a sequence](/api-reference/sequences/update-a-sequence) with `active: false` instead.", "tags": [ "Sequences" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 81 } ], "responses": { "204": { "description": "Deletes the sequence" }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "get": { "summary": "Get a sequence", "description": "Fetches a single sequence by `id`. Use this when you need the current schedule, the `active` / `repeat` / `hold` flags, the configured `email_address` and `email_template_id`, or `exclude_subscriber_sources` for a known sequence — for example, to confirm settings before adding subscribers or to render an editor.\n\nFor the individual emails inside the sequence, use [List sequence emails](/api-reference/sequence-emails/list-sequence-emails). For the sequence model and field semantics, see [Create a sequence](/api-reference/sequences/create-a-sequence).", "tags": [ "Sequences" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 23 } ], "responses": { "200": { "description": "Returns the sequence details", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hold": { "type": "boolean" }, "repeat": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "email_address": { "nullable": true }, "email_template_id": { "nullable": true }, "send_days": { "type": "array", "items": { "type": "string" } }, "send_hour": { "type": "integer" }, "time_zone": { "type": "string" }, "active": { "type": "boolean" }, "exclude_subscriber_sources": { "type": "array", "items": {} }, "email_count": { "type": "integer" }, "subscriber_count": { "type": "integer" } }, "required": [ "id", "name", "hold", "repeat", "created_at", "updated_at", "email_address", "email_template_id", "send_days", "send_hour", "time_zone", "active", "exclude_subscriber_sources" ] } }, "required": [ "sequence" ] }, "example": { "sequence": { "id": 22, "name": "Welcome sequence", "hold": false, "repeat": false, "created_at": "2023-02-17T11:43:55Z", "updated_at": "2023-02-17T11:43:55Z", "email_address": null, "email_template_id": null, "send_days": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "send_hour": 11, "time_zone": "America/New_York", "active": true, "exclude_subscriber_sources": [], "email_count": 0, "subscriber_count": 0 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "put": { "summary": "Update a sequence", "description": "Updates any sequence settings — `name`, `email_address`, schedule (`send_days`, `send_hour`, `time_zone`), `email_template_id`, `exclude_subscriber_sources`, or the `active` / `repeat` / `hold` flags. Only fields included in the request body change; everything else is preserved.\n\nSome changes have user-visible side effects on subscribers already in the sequence:\n\n**Note:** flipping `active` from `false` to `true` resumes delivery for queued subscribers. Flipping it back to `false` pauses the sequence — subscribers stay in their current position but no new emails are sent until it's reactivated.\n\n**Note:** changing the schedule (`send_days`, `send_hour`, or `time_zone`) only affects future sends. It does not retroactively reschedule emails already queued for delivery.\n\n**Warning:** turning off `repeat` while subscribers are mid-sequence does not stop them from finishing — but they won't be re-eligible to start over after completing.\n\nSee [Create a sequence](/api-reference/sequences/create-a-sequence) for the full sequence model and what each field controls.", "tags": [ "Sequences" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 60 } ], "responses": { "200": { "description": "Updates the sequence and returns its details", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hold": { "type": "boolean" }, "repeat": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "email_address": { "type": "string" }, "email_template_id": { "type": "integer" }, "send_days": { "type": "array", "items": { "type": "string" } }, "send_hour": { "type": "integer" }, "time_zone": { "type": "string" }, "active": { "type": "boolean" }, "exclude_subscriber_sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "type", "ids" ] } }, "email_count": { "type": "integer" }, "subscriber_count": { "type": "integer" } }, "required": [ "id", "name", "hold", "repeat", "created_at", "updated_at", "email_address", "email_template_id", "send_days", "send_hour", "time_zone", "active", "exclude_subscriber_sources" ] } }, "required": [ "sequence" ] }, "example": { "sequence": { "id": 49, "name": "New Name", "hold": true, "repeat": true, "created_at": "2026-06-11T16:16:00Z", "updated_at": "2026-06-11T16:16:00Z", "email_address": "joe1040@ck.lol", "email_template_id": 40, "send_days": [ "tuesday", "thursday" ], "send_hour": 14, "time_zone": "America/Chicago", "active": false, "exclude_subscriber_sources": [ { "type": "sequence", "ids": [ 48 ] }, { "type": "tag", "ids": [ 3 ] } ], "email_count": 0, "subscriber_count": 0 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when one or more of the parameters were invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "name can't be blank" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the sequence." }, "email_address": { "type": "string", "description": "The sending email address to use. Uses the account's sending email address if not provided." }, "email_template_id": { "type": "integer", "description": "Id of the email template to use." }, "send_days": { "type": "array", "items": { "type": "string" }, "description": "The days of the week to send the sequence on. Must be one of: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`." }, "send_hour": { "type": "integer", "description": "The hour of the day to send the sequence at. Must be an integer between 0 and 23." }, "time_zone": { "type": "string", "description": "The timezone to use for the sequence. Must be a valid IANA timezone string." }, "active": { "type": "boolean", "description": "`true` to activate the sequence, `false` to deactivate it." }, "repeat": { "type": "boolean", "description": "When `true`, subscribers can restart the sequence multiple times." }, "hold": { "type": "boolean", "description": "When `true`, subscribers added via Visual Automations stay in the sequence after receiving the last email." }, "exclude_subscriber_sources": { "type": "array", "description": "The subscriber sources to exclude from the sequence.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of subscriber source to exclude. Must be one of: `tag`, `sequence`, `form`, `segment`." }, "ids": { "type": "array", "items": { "type": "integer", "description": "The ids of the subscriber sources to exclude." } } }, "required": [ "type", "ids" ] } } } }, "example": { "name": "New Name", "email_address": "joe1040@ck.lol", "email_template_id": 40, "send_days": [ "tuesday", "thursday" ], "send_hour": 14, "time_zone": "America/Chicago", "active": false, "repeat": true, "hold": true, "exclude_subscriber_sources": [ { "type": "tag", "ids": [ 3 ] }, { "type": "sequence", "ids": [ 48 ] } ] } } } }, "x-mcp": { "enabled": true } } }, "/v4/sequences/{sequence_id}/emails": { "get": { "summary": "List sequence emails", "description": "Returns every email inside a sequence, ordered by `position` (the order subscribers receive them). Each entry carries timing (`delay_value`, `delay_unit`, `send_days`), publish state (`published`), and metadata (`subject`, `preview_text`, `email_template_id`).\n\n**Tip:** the heavier `content` field is omitted by default to keep responses fast on sequences with many emails. Pass `include_content=true` when you need the body — for example, to render a preview, audit Liquid usage, or sync an external draft.\n\nFor the field semantics — particularly how `delay_unit` and `send_days` interact, and what happens when subscribers hit a `published: false` email — see [Create a sequence email](/api-reference/sequence-emails/create-a-sequence-email).", "tags": [ "Sequence Emails" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "nullable": true }, "description": "To fetch next page of results, use `?after=`" }, { "name": "before", "in": "query", "required": false, "schema": { "nullable": true }, "description": "To fetch previous page of results, use `?before=`" }, { "name": "include_content", "in": "query", "required": false, "schema": { "nullable": true }, "description": "Pass `true` to include the `content` field on each email in the response. Omitted by default because it increases response size for large sequences." }, { "name": "include_total_count", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false, "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages." }, { "name": "per_page", "in": "query", "required": false, "schema": { "nullable": true }, "description": "Number of results per page. Default 500, maximum 1000." }, { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 108 } ], "responses": { "200": { "description": "Returns a paginated list of all sequence emails for your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "subject": { "type": "string" }, "preview_text": { "type": "string" }, "email_address": { "type": "string" }, "email_template_id": { "nullable": true }, "published": { "type": "boolean" }, "position": { "type": "integer" }, "delay_value": { "type": "integer" }, "delay_unit": { "type": "string" }, "send_days": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "sequence_id", "subject", "preview_text", "email_address", "email_template_id", "published", "position", "delay_value", "delay_unit", "send_days" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "emails", "pagination" ] }, "example": { "emails": [ { "id": 6, "sequence_id": 107, "subject": "Welcome to the series", "preview_text": "Here's what to expect", "email_address": "joe2463@ck.lol", "email_template_id": null, "published": true, "position": 0, "delay_value": 0, "delay_unit": "days", "send_days": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzAsNl0=", "end_cursor": "WzAsNl0=", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Create a sequence email", "description": "Adds a single email to a sequence. Each sequence email represents one step subscribers receive on their journey through the sequence — its `position` determines order, and `delay_value` / `delay_unit` / `send_days` determine when it fires relative to either the previous email or the subscriber's entry.\n\n`subject`, `delay_value`, and `delay_unit` are required. **Day-based** emails (`delay_unit: \"days\"`) follow the parent sequence's `send_days` and `send_hour`; their per-email `send_days` (e.g. `[\"monday\", \"wednesday\"]`) overrides the sequence schedule for that one email. **Hour-based** emails (`delay_unit: \"hours\"`) ignore the sequence schedule and fire once the delay elapses — Kit checks for hour-delayed sends every 15 minutes — and always return `send_days` as `null`.\n\nNew emails are created in draft (`published: false`) so they don't go out until you flip the flag. `position` is auto-assigned to the end of the sequence if omitted. `content` accepts HTML and can embed snippets with `{{ snippet. }}` — see [Create a snippet](/api-reference/snippets/create-a-snippet) — which Kit resolves at send time, so editing a snippet later updates every email referencing it without a re-publish.\n\n**Note:** only the first email in a sequence can be an immediate send (`delay_value: 0` with `delay_unit: \"days\"`). Subsequent emails need a positive delay.\n\n**Warning:** publishing an immediate first email, or inserting a new email at a `position` earlier than where existing subscribers sit, processes those subscribers and triggers a send right away. Plan around active sequences carefully.\n\nFor end-user context on how creators build sequences in the Kit UI, see the help article on [creating and sending a sequence](https://help.kit.com/en/articles/2502629-creating-and-sending-a-sequence-in-kit).", "tags": [ "Sequence Emails" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 154 } ], "responses": { "201": { "description": "Creates a new sequence email", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "subject": { "type": "string" }, "preview_text": { "nullable": true }, "email_address": { "type": "string" }, "email_template_id": { "nullable": true }, "published": { "type": "boolean" }, "position": { "nullable": true }, "delay_value": { "type": "integer" }, "delay_unit": { "type": "string" }, "send_days": { "type": "array", "items": { "type": "string" } }, "content": { "nullable": true } }, "required": [ "id", "sequence_id", "subject", "preview_text", "email_address", "email_template_id", "published", "position", "delay_value", "delay_unit", "send_days", "content" ] } }, "required": [ "email" ] }, "example": { "email": { "id": 35, "sequence_id": 153, "subject": "Welcome to the sequence", "preview_text": null, "email_address": "joe2527@ck.lol", "email_template_id": null, "published": false, "position": null, "delay_value": 1, "delay_unit": "days", "send_days": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "content": null } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when one or more of the parameters were invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "subject can't be blank" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "subject", "delay_value", "delay_unit" ], "properties": { "subject": { "type": "string", "description": "Subject line of the email" }, "preview_text": { "type": "string", "nullable": true, "description": "Preview text shown in email clients before the email is opened" }, "content": { "type": "string", "nullable": true, "description": "HTML body content of the email" }, "delay_value": { "type": "integer", "description": "Number of days or hours to wait before sending this email after the previous one" }, "delay_unit": { "type": "string", "enum": [ "days", "hours" ], "description": "Unit for the send delay. Use `days` for schedule-aware delivery, `hours` for a fixed hourly delay" }, "email_template_id": { "type": "integer", "nullable": true, "description": "ID of the email template to use for layout and styling" }, "published": { "type": "boolean", "description": "Whether the email is active and will be sent to subscribers. Defaults to `false` (draft)" }, "send_days": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Days of the week this email may be sent. Defaults to all 7 days (inherits the sequence schedule). Pass a subset to restrict delivery, or `null` to reset to all days" }, "position": { "type": "integer", "nullable": true, "description": "Zero-based position of the email in the sequence. Assigned automatically after the last email if omitted" } } }, "example": { "subject": "Welcome to the sequence", "delay_value": 1, "delay_unit": "days", "preview_text": null, "content": null, "email_template_id": null, "published": null, "send_days": null, "position": null } } } }, "x-mcp": { "enabled": true } } }, "/v4/sequences/{sequence_id}/emails/{id}": { "delete": { "summary": "Delete a sequence email", "description": "Permanently removes one email from a sequence.\n\n**Warning:** subscribers already queued to receive the deleted email will skip it — they'll continue to the next email in sequence order. This is intentional and not retryable. If subscribers need to receive the email's content, send a broadcast or re-add subscribers to the sequence (with `repeat: true`) before deleting.\n\nIf you want to pause rather than delete, use [Update a sequence email](/api-reference/sequence-emails/update-a-sequence-email) with `published: false` instead.", "tags": [ "Sequence Emails" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 91 }, { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 212 } ], "responses": { "204": { "description": "Deletes the sequence email" }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "get": { "summary": "Get a sequence email", "description": "Fetches a single sequence email by `id`. Unlike [List sequence emails](/api-reference/sequence-emails/list-sequence-emails), this endpoint **always returns the full `content`** — no `include_content` flag needed.\n\nUse this when you have an email's `id` and need the current body, timing, or publish state — for example, to render a preview before pushing an update via [Update a sequence email](/api-reference/sequence-emails/update-a-sequence-email).\n\nFor the field semantics, see [Create a sequence email](/api-reference/sequence-emails/create-a-sequence-email).", "tags": [ "Sequence Emails" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 26 }, { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 129 } ], "responses": { "200": { "description": "Returns the sequence email details", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "subject": { "type": "string" }, "preview_text": { "type": "string" }, "email_address": { "type": "string" }, "email_template_id": { "nullable": true }, "published": { "type": "boolean" }, "position": { "type": "integer" }, "delay_value": { "type": "integer" }, "delay_unit": { "type": "string" }, "send_days": { "type": "array", "items": { "type": "string" } }, "content": { "type": "string" } }, "required": [ "id", "sequence_id", "subject", "preview_text", "email_address", "email_template_id", "published", "position", "delay_value", "delay_unit", "send_days", "content" ] } }, "required": [ "email" ] }, "example": { "email": { "id": 24, "sequence_id": 127, "subject": "Welcome email", "preview_text": "Thanks for signing up", "email_address": "joe2492@ck.lol", "email_template_id": null, "published": true, "position": 0, "delay_value": 0, "delay_unit": "days", "send_days": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "content": "

Welcome!

" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "put": { "summary": "Update a sequence email", "description": "Updates any field on a sequence email — `subject`, `preview_text`, `content`, `delay_value`, `delay_unit`, `send_days`, `position`, `email_template_id`, or `published`. Only fields included in the request body change; everything else is preserved.\n\n**Note:** pass `send_days: null` to revert a per-email schedule override and inherit the parent sequence's `send_days` again. The response will then return all 7 days, indicating no per-email restriction.\n\n**Warning:** sending `send_days` on an email with `delay_unit: \"hours\"` returns `422` — `send_days` only applies to day-based emails.\n\n**Warning:** changing `position` while subscribers are actively progressing through the sequence can cause emails to be sent out of order or skipped. The same caution applies to flipping `published` on a `position: 0` email — it triggers Kit to process all queued subscribers for that email.\n\nFor the sequence-email model and how `delay_unit` and `send_days` interact, see [Create a sequence email](/api-reference/sequence-emails/create-a-sequence-email).", "tags": [ "Sequence Emails" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 67 }, { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 188 } ], "responses": { "200": { "description": "Updates the sequence email and returns its details", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "subject": { "type": "string" }, "preview_text": { "type": "string" }, "email_address": { "type": "string" }, "email_template_id": { "nullable": true }, "published": { "type": "boolean" }, "position": { "nullable": true }, "delay_value": { "type": "integer" }, "delay_unit": { "type": "string" }, "send_days": { "type": "array", "items": { "type": "string" } }, "content": { "nullable": true, "type": "string" } }, "required": [ "id", "sequence_id", "subject", "preview_text", "email_address", "email_template_id", "published", "position", "delay_value", "delay_unit", "send_days", "content" ] } }, "required": [ "email" ] }, "example": { "email": { "id": 66, "sequence_id": 187, "subject": "Updated subject", "preview_text": "Updated preview", "email_address": "joe2570@ck.lol", "email_template_id": null, "published": true, "position": null, "delay_value": 3, "delay_unit": "days", "send_days": [ "monday", "wednesday", "friday" ], "content": "Content 37" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when one or more of the parameters were invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "delay_unit must be one of: days, hours" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "New subject line for the email" }, "preview_text": { "type": "string", "nullable": true, "description": "New preview text shown in email clients before the email is opened" }, "content": { "type": "string", "nullable": true, "description": "New HTML body content of the email" }, "delay_value": { "type": "integer", "description": "New delay value" }, "delay_unit": { "type": "string", "enum": [ "days", "hours" ], "description": "New delay unit. Use `days` for schedule-aware delivery, `hours` for a fixed hourly delay" }, "email_template_id": { "type": "integer", "nullable": true, "description": "New email template ID for layout and styling. Pass `null` to clear" }, "published": { "type": "boolean", "description": "Pass `true` to publish a draft email or `false` to unpublish it" }, "send_days": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Days of the week this email may be sent. Pass a subset to restrict delivery, or `null` to reset to all days (inherits the sequence schedule)" }, "position": { "type": "integer", "nullable": true, "description": "New zero-based position of the email in the sequence" } } }, "example": { "subject": "Updated subject", "preview_text": "Updated preview", "content": null, "delay_value": 3, "delay_unit": "days", "email_template_id": null, "published": true, "send_days": [ "monday", "wednesday", "friday" ], "position": null } } } }, "x-mcp": { "enabled": true } } }, "/v4/sequences/{sequence_id}/subscribers": { "get": { "summary": "List subscribers for a sequence", "tags": [ "Sequences" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "added_after", "description": "Filter subscribers who have been added to the form after this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-02-14T11:43:55Z" }, { "name": "added_before", "description": "Filter subscribers who have been added to the form before this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-02-18T11:43:55Z" }, { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "created_after", "description": "Filter subscribers who have been created after this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-01-17T11:43:55Z" }, { "name": "created_before", "description": "Filter subscribers who have been created before this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-02-18T11:43:55Z" }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 255 }, { "name": "status", "description": "Filter subscribers who have this status (`active`, `inactive`, `bounced`, `complained`, `cancelled` or `all`). Defaults to `active`.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "bounced", "complained", "cancelled", "all" ] }, "example": "all" } ], "responses": { "200": { "description": "Returns a paginated list of subscribers for the specified sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": { "category": { "type": "string", "nullable": true } }, "required": [ "category" ] } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "fields" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "subscribers", "pagination" ] }, "example": { "subscribers": [ { "id": 917, "first_name": null, "email_address": "subscriber492@kit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": { "category": "One" } }, { "id": 916, "first_name": null, "email_address": "subscriber491@kit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": { "category": null } }, { "id": 915, "first_name": null, "email_address": "subscriber490@kit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": { "category": null } } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzkxN10=", "end_cursor": "WzkxNV0=", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Add subscriber to sequence by email address", "description": "The subscriber being added to the sequence must already exist. Subscribers can be created using the \"[Create a subscriber](#create-a-subscriber)\" endpoint.", "tags": [ "Sequences" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 324 } ], "responses": { "200": { "description": "Returns a 200 when the subscriber has already been added to the sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": {} } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 1028, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": {} } } } } }, "201": { "description": "Adds the subscriber to the sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": {} } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 1029, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": {} } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when a sequence is inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Sequence is inactive" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email_address": { "type": "string" } }, "required": [ "email_address" ] }, "example": { "email_address": "alice@convertkit.dev" } } } }, "x-mcp": { "enabled": true } } }, "/v4/sequences/{sequence_id}/subscribers/{id}": { "post": { "summary": "Add subscriber to sequence", "description": "The subscriber being added to the sequence must already exist. Subscribers can be created using the \"[Create a subscriber](#create-a-subscriber)\" endpoint.", "tags": [ "Sequences" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1006 }, { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 293 } ], "responses": { "200": { "description": "Returns a 200 when the subscriber has already been added to the sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": {} } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 1002, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": {} } } } } }, "201": { "description": "Adds the subscriber to the sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "added_at": { "type": "string" }, "fields": { "type": "object", "properties": {} } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "added_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 1003, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "added_at": "2023-02-17T11:43:55Z", "fields": {} } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "x-mcp": { "enabled": true } } }, "/v4/snippets": { "get": { "summary": "List snippets", "description": "Returns every snippet on the account. Each snippet's `key` is the identifier used in Liquid — `{{ snippet.key }}` — when creating a broadcast or sequence email. See [Create a snippet](/api-reference/snippets/create-a-snippet) for how snippets work end-to-end.\n\n**Tip:** the heavier `content` and `document` fields are omitted by default to keep responses fast. Pass `include_content=true` when you need the body — for example, to render a preview or audit Liquid usage.\n\nFilter the result with `snippet_type` (`inline` or `block`) and `archived` (defaults to `false`, set `true` to list only archived snippets).", "tags": [ "Snippets" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "archived", "description": "When `true`, returns only archived snippets. Defaults to `false`.", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_content", "description": "When `true`, includes both the `content` and `document` fields for each snippet in the response. Defaults to `false`.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "snippet_type", "description": "Filter snippets by type. Use `inline` for text snippets or `block` for rich-text block snippets.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of all snippets for your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "snippets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "snippet_type": { "type": "string" }, "archived": { "type": "boolean" }, "key": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "content": { "type": "string" }, "document": { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "nullable": true }, "value_html": { "type": "string" }, "value_plain": { "nullable": true }, "version": { "type": "integer" } }, "required": [ "id", "value", "value_html", "value_plain", "version" ] } }, "required": [ "id", "name", "snippet_type", "archived", "key", "created_at", "updated_at", "content", "document" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "snippets", "pagination" ] }, "example": { "snippets": [ { "id": 5, "name": "Welcome message", "snippet_type": "inline", "archived": false, "key": "welcome-message", "created_at": "2023-02-17T11:43:55Z", "updated_at": "2023-02-17T11:43:55Z", "content": "Hello {{ subscriber.first_name }}", "document": { "id": 152, "value": null, "value_html": "content", "value_plain": null, "version": 1 } } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzVd", "end_cursor": "WzVd", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Create a snippet", "description": "Snippets are reusable pieces of email content you can drop into a broadcast or sequence email using Liquid: `{{ snippet.key }}`. Update the snippet once and every email that references it picks up the new content on next send.\n\nThere are two `snippet_type`s. **`inline`** snippets store plain-text content (with Liquid variable support like `{{ subscriber.first_name }}`) in the `content` field. **`block`** snippets store rich-text HTML — text, lists, images, buttons — in `document_attributes.value_html`. A snippet's type is fixed at creation: it cannot be changed via [Update a snippet](/api-reference/snippets/update-a-snippet).\n\nThe response includes a `key` field. That's the identifier you use in Liquid — for example, a snippet returned with `\"key\": \"welcome-message\"` is referenced inside a broadcast as `{{ snippet.welcome-message }}`. Keys are derived from the snippet name on creation.\n\n**Note:** the API rejects circular references — a snippet cannot reference itself, directly or transitively — with a `422` validation error.\n\nFor end-user context on how creators build and edit snippets in the Kit UI, see the help articles on [content snippets](https://help.kit.com/en/articles/3812712-creating-and-using-content-snippets-in-your-kit-emails) and [code snippets for custom templates](https://help.kit.com/en/articles/2810398-code-snippets-for-custom-email-templates).", "tags": [ "Snippets" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "201": { "description": "Creates a new snippet", "content": { "application/json": { "schema": { "type": "object", "properties": { "snippet": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "snippet_type": { "type": "string" }, "archived": { "type": "boolean" }, "key": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "content": { "type": "string" }, "document": { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "nullable": true }, "value_html": { "nullable": true }, "value_plain": { "nullable": true }, "version": { "type": "integer" } }, "required": [ "id", "value", "value_html", "value_plain", "version" ] } }, "required": [ "id", "name", "snippet_type", "archived", "key", "created_at", "updated_at", "content", "document" ] } }, "required": [ "snippet" ] }, "example": { "snippet": { "id": 31, "name": "Cat Fact of the Day", "snippet_type": "inline", "archived": false, "key": "cat-fact-of-the-day", "created_at": "2026-06-11T16:16:17Z", "updated_at": "2026-06-11T16:16:17Z", "content": "Did you know, {{ subscriber.first_name }}? Cats can rotate their ears 180 degrees.", "document": { "id": 178, "value": null, "value_html": null, "value_plain": null, "version": 1 } } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "422": { "description": "Returns a 422 with an error message when one or more of the parameters were invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "name can't be blank" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "Inline snippet", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the snippet" }, "snippet_type": { "type": "string", "enum": [ "inline" ], "description": "Must be 'inline'" }, "content": { "type": "string", "description": "Liquid-enabled text content for the snippet" } }, "required": [ "name", "snippet_type", "content" ] }, { "title": "Block snippet", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the snippet" }, "snippet_type": { "type": "string", "enum": [ "block" ], "description": "Must be 'block'" }, "document_attributes": { "type": "object", "description": "Rich-text document for the snippet", "properties": { "value_html": { "type": "string", "description": "HTML content for the block snippet" } }, "required": [ "value_html" ] } }, "required": [ "name", "snippet_type", "document_attributes" ] } ] }, "example": { "name": "Cat Fact of the Day", "snippet_type": "inline", "content": "Did you know, {{ subscriber.first_name }}? Cats can rotate their ears 180 degrees." } } } }, "x-mcp": { "enabled": true } } }, "/v4/snippets/{id}": { "get": { "summary": "Get a snippet", "description": "Fetches a single snippet by `id`. Unlike [List snippets](/api-reference/snippets/list-snippets), this endpoint **always returns the full `content` and `document`** — no `include_content` flag needed.\n\nUse this when you have an `id` (e.g. stored from a prior create call) and need the current `key` and body — for example, to preview the resolved HTML or confirm a snippet still exists before referencing it as `{{ snippet.key }}` in a broadcast or sequence email. See [Create a snippet](/api-reference/snippets/create-a-snippet) for the snippet model.", "tags": [ "Snippets" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 25 } ], "responses": { "200": { "description": "Returns the snippet details", "content": { "application/json": { "schema": { "type": "object", "properties": { "snippet": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "snippet_type": { "type": "string" }, "archived": { "type": "boolean" }, "key": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "content": { "type": "string" }, "document": { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "nullable": true }, "value_html": { "type": "string" }, "value_plain": { "nullable": true }, "version": { "type": "integer" } }, "required": [ "id", "value", "value_html", "value_plain", "version" ] } }, "required": [ "id", "name", "snippet_type", "archived", "key", "created_at", "updated_at", "content", "document" ] } }, "required": [ "snippet" ] }, "example": { "snippet": { "id": 24, "name": "Welcome message", "snippet_type": "inline", "archived": false, "key": "welcome-message", "created_at": "2023-02-17T11:43:55Z", "updated_at": "2023-02-17T11:43:55Z", "content": "Hello {{ subscriber.first_name }}", "document": { "id": 171, "value": null, "value_html": "content", "value_plain": null, "version": 1 } } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "put": { "summary": "Update a snippet", "description": "Rename a snippet, replace its body, or archive/restore it. Updates apply on the next send of any email that references the snippet via `{{ snippet.key }}` — there's no per-email versioning, so a content change ripples to every broadcast or sequence email using that key.\n\nThe request body must match the existing `snippet_type`. For an **`inline`** snippet, send `content` (and optionally `name`, `archived`). For a **`block`** snippet, send `document_attributes.value_html` (and optionally `name`, `archived`). Pass `archived: true` to archive, `false` to restore.\n\n**Warning:** `snippet_type` is immutable. Sending a different value, or sending the body shape for the wrong type, returns a `422` with `snippet_type cannot be changed`.\n\nSee [Create a snippet](/api-reference/snippets/create-a-snippet) for the full snippet model and how `key` ties into Liquid.", "tags": [ "Snippets" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 60 } ], "responses": { "200": { "description": "Updates the snippet and returns its details", "content": { "application/json": { "schema": { "type": "object", "properties": { "snippet": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "snippet_type": { "type": "string" }, "archived": { "type": "boolean" }, "key": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "content": { "type": "string" }, "document": { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "nullable": true }, "value_html": { "type": "string" }, "value_plain": { "nullable": true }, "version": { "type": "integer" } }, "required": [ "id", "value", "value_html", "value_plain", "version" ] } }, "required": [ "id", "name", "snippet_type", "archived", "key", "created_at", "updated_at", "content", "document" ] } }, "required": [ "snippet" ] }, "example": { "snippet": { "id": 59, "name": "Dog Fact of the Day", "snippet_type": "inline", "archived": false, "key": "welcome-message", "created_at": "2023-02-17T11:43:55Z", "updated_at": "2026-06-11T16:16:22Z", "content": "Hello {{ subscriber.first_name }}", "document": { "id": 206, "value": null, "value_html": "content", "value_plain": null, "version": 1 } } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when one or more of the parameters were invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "snippet_type cannot be changed" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "Inline snippet", "type": "object", "properties": { "name": { "type": "string", "description": "New name for the snippet" }, "snippet_type": { "type": "string", "description": "Cannot be changed — must match the existing type if provided" }, "archived": { "type": "boolean", "description": "Pass `true` to archive or `false` to restore the snippet" }, "content": { "type": "string", "description": "New Liquid-enabled text content" } } }, { "title": "Block snippet", "type": "object", "properties": { "name": { "type": "string", "description": "New name for the snippet" }, "snippet_type": { "type": "string", "description": "Cannot be changed — must match the existing type if provided" }, "archived": { "type": "boolean", "description": "Pass `true` to archive or `false` to restore the snippet" }, "document_attributes": { "type": "object", "description": "Updated rich-text document", "properties": { "value_html": { "type": "string", "description": "New HTML content for the block snippet" } }, "required": [ "value_html" ] } } } ] }, "example": { "name": "Dog Fact of the Day" } } } }, "x-mcp": { "enabled": true } } }, "/v4/subscribers": { "get": { "summary": "List subscribers", "tags": [ "Subscribers" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "created_after", "description": "Filter subscribers who have been created after this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2023-01-17T11:43:55Z" }, { "name": "created_before", "description": "Filter subscribers who have been created before this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2023-02-18T11:43:55Z" }, { "name": "email_address", "in": "query", "required": false, "schema": { "type": "string" }, "example": "subscriber89@kit.dev,subscriber90@kit.dev,subscriber91@kit.dev" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "example": "attribution,tags,location", "description": "Comma-separated list of additional fields to include on each subscriber. Valid options: `attribution`, `tags`, `location`, `canceled_at`. `canceled_at` may only be used together with `status=cancelled`." }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "type": "number", "nullable": true }, "example": 10 }, { "name": "slim", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false, "description": "When `true`, omits expensive optional fields from the response. Produces a faster, smaller response — useful when extra fields are not needed." }, { "name": "sort_field", "in": "query", "required": false, "schema": { "type": "string" }, "example": "cancelled_at" }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "example": "asc" }, { "name": "status", "description": "Filter subscribers who have this status (`active`, `inactive`, `bounced`, `complained`, `cancelled` or `all`). Defaults to `active`.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "bounced", "complained", "cancelled", "all" ] }, "example": "bounced" }, { "name": "updated_after", "description": "Filter subscribers who have been updated after this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2023-01-17T11:43:55Z" }, { "name": "updated_before", "description": "Filter subscribers who have been updated before this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2023-02-18T11:43:55Z" } ], "responses": { "200": { "description": "Returns subscriber attribution, tags, and primary location when requested via the include param", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "fields": { "type": "object", "properties": { "category": { "type": "string", "nullable": true } } }, "attribution": { "type": "object", "description": "Returned when `include` contains `attribution`.", "nullable": true, "properties": { "referrer": { "type": "string", "nullable": true }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true }, "source_type": { "type": "string", "nullable": true }, "source_name": { "type": "string", "nullable": true }, "source_mechanism": { "type": "string", "nullable": true }, "source_mechanism_id": { "type": "integer", "nullable": true } }, "required": [ "referrer", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "source_type", "source_name", "source_mechanism", "source_mechanism_id" ] }, "tags": { "type": "array", "description": "Returned when `include` contains `tags`.", "items": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true } } } }, "location": { "type": "object", "description": "Returned when `include` contains `location`.", "nullable": true, "properties": { "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true, "format": "float" }, "longitude": { "type": "number", "nullable": true, "format": "float" }, "timezone": { "type": "string", "nullable": true } }, "required": [ "city", "state", "country", "latitude", "longitude", "timezone" ] }, "canceled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Returned when `include` contains `canceled_at`. Requires `status=cancelled`." } }, "required": [ "id", "state", "first_name", "email_address", "created_at", "fields" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "subscribers", "pagination" ] }, "example": { "subscribers": [ { "id": 200, "state": "active", "first_name": "Alice", "email_address": "alice@convertkit.dev", "created_at": "2023-01-27T11:43:55Z", "fields": { "category": "One" }, "attribution": { "referrer": "https://t.co/abc123", "utm_source": "twitter", "utm_medium": "cpc", "utm_campaign": "spring_launch", "utm_term": "newsletter+for+creators", "utm_content": "hero_cta", "source_type": "form_subscription", "source_name": "Welcome Form", "source_mechanism": "landing_page", "source_mechanism_id": null }, "tags": [ { "id": 1, "name": "VIP" } ], "location": { "city": "Portland", "state": "OR", "country": "US", "latitude": 45.5, "longitude": -122.6, "timezone": "America/Los_Angeles" } }, { "id": 201, "state": "active", "first_name": "Benito", "email_address": "benito@convertkit.dev", "created_at": "2023-02-03T11:43:55Z", "fields": {}, "attribution": { "referrer": "https://creator.kit.com/jane-smith", "utm_source": "kit", "utm_medium": "referral", "utm_campaign": null, "utm_term": null, "utm_content": null, "source_type": "form_subscription", "source_name": "Jane Smith's Recommendations", "source_mechanism": "recommendations", "source_mechanism_id": null }, "tags": [ { "id": 2, "name": "Newsletter" } ], "location": { "city": "Austin", "state": "TX", "country": "US", "latitude": 30.27, "longitude": -97.74, "timezone": "America/Chicago" } }, { "id": 202, "state": "active", "first_name": "Camille", "email_address": "camille@convertkit.dev", "created_at": "2023-02-10T11:43:55Z", "fields": {}, "attribution": { "referrer": null, "utm_source": null, "utm_medium": null, "utm_campaign": null, "utm_term": null, "utm_content": null, "source_type": "api_subscription", "source_name": "Partner Integration", "source_mechanism": "api", "source_mechanism_id": 12345 }, "tags": [], "location": null }, { "id": 203, "state": "active", "first_name": "Elliot", "email_address": "elliot@convertkit.dev", "created_at": "2023-02-13T11:43:55Z", "fields": {}, "attribution": { "referrer": null, "utm_source": null, "utm_medium": null, "utm_campaign": null, "utm_term": null, "utm_content": null, "source_type": null, "source_name": null, "source_mechanism": null, "source_mechanism_id": null }, "tags": [ { "id": 3, "name": "Imported" } ], "location": { "city": null, "state": null, "country": null, "latitude": null, "longitude": null, "timezone": null } } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "MjAyMy0wMS0yNyAxMTo0Mzo1NSBVVEM=", "end_cursor": "MjAyMy0wMi0xMyAxMTo0Mzo1NSBVVEM=", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "422": { "description": "raises an error when sorting on cancelled_at without the cancelled status", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The status param must be `cancelled` if sort_field is `cancelled_at`" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Create a subscriber", "description": "Behaves as an upsert. If a subscriber with the provided email address does not exist, it creates one with the specified first name and state. If a subscriber with the provided email address already exists, it updates the first name.

If you include a custom field key that does not exist on your account, the request returns an error. Use [List custom fields](/api-reference/custom-fields/list-custom-fields) to retrieve existing keys, or [Create a custom field](/api-reference/custom-fields/create-a-custom-field) to add new fields before setting them for subscribers.

NOTE: Updating the subscriber state with this endpoint is not supported at this time.
NOTE: We support creating/updating a maximum of 140 custom fields at a time.", "tags": [ "Subscribers" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Returns a 200 and updates the subscriber first name when a subscriber with provided email already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "fields": { "type": "object", "properties": {} } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 353, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "inactive", "created_at": "2023-02-17T11:43:55Z", "fields": {} } } } } }, "201": { "description": "Creates a new subscriber", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom field values for the subscriber, keyed by the custom field's `key`." } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "fields" ] }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Present only when the request referenced custom field keys that don't exist on the account. Each entry names an unknown key that was ignored; the subscriber is still created or updated." } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 349, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "fields": { "birthday": "Feb 17", "last_name": "Lamarr", "source": "landing page" } } } } } }, "202": { "description": "Returns a 202 and asynchronously adds custom fields for the new subscriber when more than 10 custom fields are included in the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "fields": { "type": "object", "properties": { "company": { "nullable": true }, "coupon": { "nullable": true }, "enrolled_in_coaching": { "nullable": true }, "how_did_you_hear_about_us": { "nullable": true }, "interests": { "nullable": true }, "lead_score": { "nullable": true }, "phone_number": { "nullable": true }, "postal_code": { "nullable": true }, "role": { "nullable": true }, "social_media": { "nullable": true }, "website": { "nullable": true } }, "required": [ "company", "coupon", "enrolled_in_coaching", "how_did_you_hear_about_us", "interests", "lead_score", "phone_number", "postal_code", "role", "social_media", "website" ] } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 351, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "fields": { "company": null, "coupon": null, "enrolled_in_coaching": null, "how_did_you_hear_about_us": null, "interests": null, "lead_score": null, "phone_number": null, "postal_code": null, "role": null, "social_media": null, "website": null } } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "422": { "description": "Returns a 422 with an error message when one or more of the parameters are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Email address is invalid" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "nullable": true, "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ], "description": "Create subscriber in this state (`active`, `bounced`, `cancelled`, `complained` or `inactive`). Defaults to `active`." }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom field values keyed by the custom field's `key` (e.g. `last_name`, not `Last Name`). Unknown keys are ignored and reported in the response `warnings` array." } }, "required": [ "email_address" ] }, "example": { "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "fields": { "last_name": "Lamarr", "birthday": "Feb 17", "source": "landing page", "role": "Software developer", "company": "Convertkit", "postal_code": "83702", "website": "convertkit.com", "social_media": "https://www.linkedin.com/company/convertkit", "how_did_you_hear_about_us": "Social media", "interests": "Monetization", "coupon": "", "phone_number": "555-555-5555", "enrolled_in_coaching": "true", "lead_score": "87" } } } } }, "x-mcp": { "enabled": true } } }, "/v4/subscribers/filter": { "post": { "summary": "Filter subscribers based on engagement", "tags": [ "Subscribers" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Returns a list of subscribers matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "created_at": { "type": "string" }, "tag_names": { "type": "array", "items": { "type": "string" } }, "tag_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "first_name", "email_address", "created_at" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "subscribers", "pagination" ] }, "example": { "subscribers": [ { "id": "456", "first_name": "Jane", "email_address": "jane@example.com", "created_at": "2024-12-01T15:45:00Z", "tag_names": [ "newsletter", "engaged" ], "tag_ids": [ "123", "456" ] }, { "id": "789", "first_name": null, "email_address": "anonymous@example.com", "created_at": "2024-11-15T10:00:00Z", "tag_names": [], "tag_ids": [] } ], "pagination": { "has_previous_page": false, "has_next_page": true, "start_cursor": "WzQ1Nl0=", "end_cursor": "Wzc4OV0=", "per_page": 10, "total_count": 42 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberFilterRequest" }, "example": { "all": [ { "type": "opens", "count_greater_than": 5, "after": "2024-01-01", "before": "2024-12-31" }, { "type": "clicks", "count_greater_than": 2, "after": "2024-01-01", "before": "2024-12-31", "any": [ { "type": "urls", "urls": [ "kit.com", "amazon.com" ], "matching": "contains" }, { "type": "broadcasts", "ids": [ 1, 2, 3 ] } ] }, { "type": "tags", "any": [ { "type": "ids", "matching": [ 123, 456 ] } ] }, { "type": "attribution", "any": [ { "type": "forms", "ids": [ 789, 1001 ] } ] } ] } } } }, "x-mcp": { "enabled": true } } }, "/v4/subscribers/{id}": { "get": { "summary": "Get a subscriber", "tags": [ "Subscribers" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 325 } ], "responses": { "200": { "description": "Returns the subscriber details", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "fields": { "type": "object", "properties": { "category": { "type": "string" } }, "required": [ "category" ] }, "canceled_at": { "type": "string", "nullable": true } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 324, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "fields": { "category": "One" }, "canceled_at": null } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "put": { "summary": "Update a subscriber", "description": "If you include a custom field key that does not exist on your account, the request returns an error. Use [List custom fields](/api-reference/custom-fields/list-custom-fields) to retrieve existing keys, or [Create a custom field](/api-reference/custom-fields/create-a-custom-field) to add new fields before setting them for subscribers.

NOTE: We support creating/updating a maximum of 140 custom fields at a time.", "tags": [ "Subscribers" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 387 } ], "responses": { "200": { "description": "Updates the subscriber's email address and first name", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom field values for the subscriber, keyed by the custom field's `key`." } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "fields" ] }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Present only when the request referenced custom field keys that don't exist on the account. Each entry names an unknown key that was ignored; the subscriber is still created or updated." } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 378, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "fields": { "birthday": "Feb 17", "last_name": "Lamarr", "source": "landing page" } } } } } }, "202": { "description": "Returns a 202 and asynchronously updates custom fields for the subscriber when more than 10 custom fields are included in the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "fields": { "type": "object", "properties": { "birthday": { "nullable": true }, "company": { "nullable": true }, "coupon": { "nullable": true }, "how_did_you_hear_about_us": { "nullable": true }, "interests": { "nullable": true }, "last_name": { "nullable": true }, "postal_code": { "nullable": true }, "role": { "nullable": true }, "social_media": { "nullable": true }, "source": { "nullable": true }, "website": { "nullable": true } }, "required": [ "birthday", "company", "coupon", "how_did_you_hear_about_us", "interests", "last_name", "postal_code", "role", "social_media", "source", "website" ] } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 380, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "fields": { "birthday": null, "company": null, "coupon": null, "how_did_you_hear_about_us": null, "interests": null, "last_name": null, "postal_code": null, "role": null, "social_media": null, "source": null, "website": null } } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns 422 with an error when email address is already in use", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Email address has already been taken" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom field values keyed by the custom field's `key` (e.g. `last_name`, not `Last Name`). Unknown keys are ignored and reported in the response `warnings` array." } }, "required": [ "email_address" ] }, "example": { "first_name": "Alice", "email_address": "alice@convertkit.dev", "fields": { "last_name": "Lamarr", "birthday": "Feb 17", "source": "landing page", "role": "Software developer", "company": "Convertkit", "postal_code": "83702", "website": "convertkit.com", "social_media": "https://www.linkedin.com/company/convertkit", "how_did_you_hear_about_us": "Social media", "interests": "Monetization", "coupon": "" } } } } }, "x-mcp": { "enabled": true } } }, "/v4/subscribers/{id}/unsubscribe": { "post": { "summary": "Unsubscribe subscriber", "tags": [ "Subscribers" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 344 } ], "responses": { "204": { "description": "Unsubscribes the subscriber" }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "x-mcp": { "enabled": true } } }, "/v4/subscribers/{subscriber_id}/stats": { "get": { "summary": "List stats for a subscriber", "description": "Retrieve email stats for a specific subscriber. You can filter the stats by providing `email_sent_after` and/or `email_sent_before` query parameters to limit the stats to emails sent within a specific date range.\nNote: Only data for events in the last 5 years will be included.", "tags": [ "Subscribers" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "email_sent_after", "description": "Filter to stats for emails sent after this date (YYYY-MM-DD)/nNOTE: This will only include stats for emails sent in the last 5 years.", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2025-07-01" }, { "name": "email_sent_before", "description": "Filter to stats for emails sent before this date (YYYY-MM-DD)/nNote: Only data for events in the last 5 years will be included.", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2025-08-31" }, { "name": "subscriber_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1097 } ], "responses": { "200": { "description": "Returns the stats for a subscriber", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "stats": { "type": "object", "properties": { "sent": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "bounced": { "type": "integer" }, "open_rate": { "type": "number", "format": "float" }, "click_rate": { "type": "number", "format": "float" }, "last_sent": { "type": "string" }, "last_opened": { "type": "string" }, "last_clicked": { "type": "string" }, "sends_since_last_open": { "type": "integer" }, "sends_since_last_click": { "type": "integer" } }, "required": [ "sent", "opened", "clicked", "bounced", "open_rate", "click_rate", "last_sent", "last_opened", "last_clicked", "sends_since_last_open", "sends_since_last_click" ] } }, "required": [ "id", "stats" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 1097, "stats": { "sent": 2, "opened": 1, "clicked": 1, "bounced": 1, "open_rate": 0.5, "click_rate": 0.5, "last_sent": "2025-07-13T12:00:00Z", "last_opened": "2025-07-13T12:00:00Z", "last_clicked": "2025-07-14T12:00:00Z", "sends_since_last_open": 0, "sends_since_last_click": 0 } } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/subscribers/{subscriber_id}/tags": { "get": { "summary": "List tags for a subscriber", "tags": [ "Subscribers" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "subscriber_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1131 } ], "responses": { "200": { "description": "Returns a paginated list of all tags for a subscriber", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "tagged_at": { "type": "string" } }, "required": [ "id", "name", "tagged_at" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "tags", "pagination" ] }, "example": { "tags": [ { "id": 111, "name": "Tag B", "tagged_at": "2023-02-17T10:43:55Z" }, { "id": 112, "name": "Tag A", "tagged_at": "2023-02-17T10:43:55Z" } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzExXQ==", "end_cursor": "WzEwXQ==", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } } }, "/v4/tags": { "get": { "summary": "List tags", "tags": [ "Tags" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of all tags for your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "string" }, "subscriber_count": { "type": "integer" } }, "required": [ "id", "name", "created_at" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "tags", "pagination" ] }, "example": { "tags": [ { "id": 11, "name": "Tag B", "created_at": "2023-02-17T11:43:55Z", "subscriber_count": 0 }, { "id": 10, "name": "Tag A", "created_at": "2023-02-17T11:43:55Z", "subscriber_count": 0 } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzExXQ==", "end_cursor": "WzEwXQ==", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Create a tag", "tags": [ "Tags" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "200": { "description": "Returns the tag if it already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "created_at" ] } }, "required": [ "tag" ] }, "example": { "tag": { "id": 20, "name": "Completed", "created_at": "2023-02-17T11:43:55Z" } } } } }, "201": { "description": "Creates the tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "created_at" ] } }, "required": [ "tag" ] }, "example": { "tag": { "id": 19, "name": "Completed", "created_at": "2023-02-17T11:43:55Z" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "422": { "description": "Returns a 422 if a name is not provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Name can't be blank" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "example": { "name": "Completed" } } } }, "x-mcp": { "enabled": true } } }, "/v4/tags/{id}": { "put": { "summary": "Update tag name", "tags": [ "Tags" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 40 } ], "responses": { "200": { "description": "Updates the tag name", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "created_at" ] } }, "required": [ "tag" ] }, "example": { "tag": { "id": 38, "name": "signed up", "created_at": "2023-02-17T11:43:55Z" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when name is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Name can't be blank" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "example": { "name": "signed up" } } } }, "x-mcp": { "enabled": true } } }, "/v4/tags/{tag_id}/subscribers": { "delete": { "summary": "Remove tag from subscriber by email address", "tags": [ "Tags" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 250 } ], "responses": { "204": { "description": "Removes the tag from the subscriber" }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when missing email address", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Either subscriber id or email address is required to remove tag from subscriber" ] } } } } }, "x-mcp": { "enabled": true } }, "get": { "summary": "List subscribers for a tag", "tags": [ "Tags" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "created_after", "description": "Filter subscribers who have been created after this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-01-17T11:43:55Z" }, { "name": "created_before", "description": "Filter subscribers who have been created before this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-02-18T11:43:55Z" }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "slim", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false, "description": "When `true`, omits expensive optional fields from the response. Produces a faster, smaller response — useful when extra fields are not needed." }, { "name": "status", "description": "Filter subscribers who have this status (`active`, `inactive`, `bounced`, `complained`, `cancelled` or `all`). Defaults to `active`.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "bounced", "complained", "cancelled", "all" ] }, "example": "all" }, { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 141 }, { "name": "tagged_after", "description": "Filter subscribers who have been tagged after this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-02-14T11:43:55Z" }, { "name": "tagged_before", "description": "Filter subscribers who have been tagged before this date (format yyyy-mm-dd)", "in": "query", "required": false, "schema": { "nullable": true, "type": "string" }, "example": "2023-02-18T11:43:55Z" } ], "responses": { "200": { "description": "Returns a paginated list of subscribers for the specified tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "tagged_at": { "type": "string" }, "fields": { "type": "object", "properties": { "category": { "type": "string", "nullable": true } }, "required": [ "category" ] } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "tagged_at", "fields" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "subscribers", "pagination" ] }, "example": { "subscribers": [ { "id": 1134, "first_name": null, "email_address": "subscriber632@kit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "tagged_at": "2023-02-17T11:43:55Z", "fields": { "category": "One" } }, { "id": 1133, "first_name": null, "email_address": "subscriber631@kit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "tagged_at": "2023-02-17T11:43:55Z", "fields": { "category": null } }, { "id": 1132, "first_name": null, "email_address": "subscriber630@kit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "tagged_at": "2023-02-17T11:43:55Z", "fields": { "category": null } } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WyIyMDIzLTAyLTE3VDExOjQzOjU1LjAwMFoiLDE2XQ==", "end_cursor": "WyIyMDIzLTAyLTE3VDExOjQzOjU1LjAwMFoiLDE0XQ==", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Tag a subscriber by email address", "description": "The subscriber being tagged must already exist. Subscribers can be created using the \"[Create a subscriber](#create-a-subscriber)\" endpoint.", "tags": [ "Tags" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 207 } ], "responses": { "200": { "description": "Returns a 200 when the subscriber already has the tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "tagged_at": { "type": "string" }, "fields": { "type": "object", "properties": {} } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "tagged_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 1265, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "tagged_at": "2023-02-17T11:43:55Z", "fields": {} } } } } }, "201": { "description": "Tags the subscriber", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "tagged_at": { "type": "string" }, "fields": { "type": "object", "properties": {} } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "tagged_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 1266, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "tagged_at": "2023-02-17T11:43:55Z", "fields": {} } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 with an error message when missing email address", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Either subscriber id or email address is required to tag subscriber" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email_address": { "type": "string" } }, "required": [ "email_address" ] }, "example": { "email_address": "alice@convertkit.dev" } } } }, "x-mcp": { "enabled": true } } }, "/v4/tags/{tag_id}/subscribers/{id}": { "delete": { "summary": "Remove tag from subscriber", "tags": [ "Tags" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1290 }, { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 228 } ], "responses": { "204": { "description": "Removes the tag from the subscriber" }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Tag a subscriber", "description": "The subscriber being tagged must already exist. Subscribers can be created using the \"[Create a subscriber](#create-a-subscriber)\" endpoint.", "tags": [ "Tags" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1247 }, { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 184 } ], "responses": { "200": { "description": "Returns a 200 when the subscriber already has the tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "tagged_at": { "type": "string" }, "fields": { "type": "object", "properties": {} } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "tagged_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 1245, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "tagged_at": "2023-02-17T11:43:55Z", "fields": {} } } } } }, "201": { "description": "Tags the subscriber", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "cancelled", "bounced", "complained", "inactive" ] }, "created_at": { "type": "string" }, "tagged_at": { "type": "string" }, "fields": { "type": "object", "properties": {} } }, "required": [ "id", "first_name", "email_address", "state", "created_at", "tagged_at", "fields" ] } }, "required": [ "subscriber" ] }, "example": { "subscriber": { "id": 1246, "first_name": "Alice", "email_address": "alice@convertkit.dev", "state": "active", "created_at": "2023-02-17T11:43:55Z", "tagged_at": "2023-02-17T11:43:55Z", "fields": {} } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "x-mcp": { "enabled": true } } }, "/v4/webhooks": { "get": { "summary": "List webhooks", "description": "Webhooks are automations that will receive subscriber data when a subscriber event is triggered, such as when a subscriber completes a sequence.

When a webhook is triggered, a `POST` request will be made to your URL with a JSON payload.", "tags": [ "Webhooks" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "after", "description": "To fetch next page of results, use `?after=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "before", "description": "To fetch previous page of results, use `?before=`", "in": "query", "required": false, "schema": { "nullable": true } }, { "name": "include_total_count", "description": "Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "per_page", "description": "Number of results per page. Default 500, maximum 1000.", "in": "query", "required": false, "schema": { "nullable": true } } ], "responses": { "200": { "description": "Returns a paginated list of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "account_id": { "type": "integer" }, "event": { "type": "object", "properties": { "name": { "type": "string", "description": "Product name" }, "tag_id": { "type": "integer", "nullable": true }, "form_id": { "type": "integer", "nullable": true } }, "required": [ "name" ] }, "target_url": { "type": "string" } }, "required": [ "id", "account_id", "event", "target_url" ] } }, "pagination": { "type": "object", "properties": { "has_previous_page": { "type": "boolean" }, "has_next_page": { "type": "boolean" }, "start_cursor": { "type": "string" }, "end_cursor": { "type": "string" }, "per_page": { "type": "integer" } }, "required": [ "has_previous_page", "has_next_page", "start_cursor", "end_cursor", "per_page" ] } }, "required": [ "webhooks", "pagination" ] }, "example": { "webhooks": [ { "id": 2, "account_id": 1617, "event": { "name": "tag_add", "tag_id": 44 }, "target_url": "http://example.convertkit.dev/tags" }, { "id": 1, "account_id": 1617, "event": { "name": "form_subscribe", "form_id": 10 }, "target_url": "http://example.convertkit.dev/" } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzJd", "end_cursor": "WzFd", "per_page": 500 } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } } }, "x-mcp": { "enabled": true } }, "post": { "summary": "Create a webhook", "description": "Available event types:
- `subscriber.subscriber_activate`
- `subscriber.subscriber_unsubscribe`
- `subscriber.subscriber_bounce`
- `subscriber.subscriber_complain`
- `subscriber.form_subscribe`, required parameter `form_id` [Integer]
- `subscriber.course_subscribe`, required parameter `sequence_id` [Integer]
- `subscriber.course_complete`, required parameter `sequence_id` [Integer]
- `subscriber.link_click`, required parameter `initiator_value` [String] as a link URL
- `subscriber.product_purchase`, required parameter `product_id` [Integer]
- `subscriber.tag_add`, required parameter `tag_id` [Integer]
- `subscriber.tag_remove`, required parameter `tag_id` [Integer]
- `purchase.purchase_create`
- `custom_field.field_created`
- `custom_field.field_deleted`
- `custom_field.field_value_updated`, required parameter `custom_field_id` [Integer]", "tags": [ "Webhooks" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [], "responses": { "201": { "description": "Creates the webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "account_id": { "type": "integer" }, "event": { "type": "object", "properties": { "name": { "type": "string", "description": "Product name" }, "initiator_value": { "nullable": true } }, "required": [ "name", "initiator_value" ] }, "target_url": { "type": "string" } }, "required": [ "id", "account_id", "event", "target_url" ] } }, "required": [ "webhook" ] }, "example": { "webhook": { "id": 9, "account_id": 1643, "event": { "name": "subscriber_activate", "initiator_value": null }, "target_url": "https://example.convertkit.dev/" } } } } }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "422": { "description": "Returns an error when missing required params", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "`event` and `target` parameters must be provided" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "target_url": { "type": "string" }, "event": { "type": "object", "properties": { "name": { "type": "string" }, "form_id": { "nullable": true }, "tag_id": { "nullable": true }, "sequence_id": { "nullable": true }, "product_id": { "nullable": true }, "initiator_value": { "nullable": true }, "custom_field_id": { "nullable": true } }, "required": [ "name", "form_id", "tag_id", "sequence_id", "product_id", "initiator_value" ] } }, "required": [ "target_url", "event" ] }, "example": { "target_url": "https://example.convertkit.dev/", "event": { "name": "subscriber.subscriber_activate", "form_id": null, "tag_id": null, "sequence_id": null, "product_id": null, "initiator_value": null, "custom_field_id": null } } } } }, "x-mcp": { "enabled": true } } }, "/v4/webhooks/{id}": { "delete": { "summary": "Delete a webhook", "tags": [ "Webhooks" ], "security": [ { "API Key": [] }, { "OAuth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 31 } ], "responses": { "204": { "description": "Deletes the webhook" }, "401": { "description": "Returns a 401 if the token and/or account cannot be authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "The access token is invalid" ] } } } }, "404": { "description": "Returns a 404 when the provided id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Not Found" ] } } } }, "422": { "description": "Returns a 422 when the webhook cannot be deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ] }, "example": { "errors": [ "Unable to destroy the webhook." ] } } } } }, "x-mcp": { "enabled": true } } } }, "components": { "securitySchemes": { "API Key": { "description": "Authenticate API requests via an API Key", "type": "apiKey", "in": "header", "name": "X-Kit-Api-Key" }, "OAuth2": { "description": "Authenticate API requests via an OAuth token", "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.kit.com/v4/oauth/authorize", "tokenUrl": "https://api.kit.com/v4/oauth/token", "refreshUrl": "https://api.kit.com/v4/oauth/token", "scopes": { "read": "Read access to Kit API v4", "write": "Write access to Kit API v4" } } } } }, "schemas": { "SubscriberFilterRequest": { "type": "object", "description": "Filter subscribers based on engagement and subscription criteria using the 'all' array with filter conditions that must all be met (AND logic).", "properties": { "counting_mode": { "type": "string", "enum": [ "raw", "unique_email" ], "description": "Controls how engagement-filter count thresholds are tallied. `raw` (default) counts every event — five opens of the same email = five. `unique_email` counts distinct emails on which the action occurred — five opens of the same email = one. Applies to every engagement filter (opens, clicks, sent, delivered) in the request; ignored for other filter types." }, "all": { "type": "array", "description": "Array of filter conditions where ALL must be met (AND logic)", "items": { "$ref": "#/components/schemas/FilterCondition" } } }, "required": [ "all" ] }, "FilterCondition": { "type": "object", "description": "A filter condition with type and optional parameters. Used within the 'all' array for complex filtering where multiple conditions must be met.", "properties": { "type": { "type": "string", "enum": [ "opens", "clicks", "sent", "delivered", "subscribed", "subscriber_state", "tags", "attribution" ], "description": "Type of filter condition. `attribution` matches subscribers by their *original signup attribution* — currently supports a `forms` sub-condition that matches by the form / landing-page id the subscriber signed up through. Attribution is the original signup source; it does not track current subscription state." }, "count_greater_than": { "type": "integer", "description": "Minimum count (exclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered')." }, "count_greater_than_or_equal": { "type": "integer", "description": "Minimum count (inclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered')." }, "count_less_than": { "type": "integer", "description": "Maximum count (exclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered')." }, "count_less_than_or_equal": { "type": "integer", "description": "Maximum count (inclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered')." }, "after": { "type": "string", "format": "date", "description": "Start date (YYYY-MM-DD). For 'subscribed' type, filters by subscriber_created_at. For engagement types, filters by event date. Not applicable for 'tags', 'subscriber_state', or 'attribution' types." }, "before": { "type": "string", "format": "date", "description": "End date (YYYY-MM-DD). For 'subscribed' type, filters by subscriber_created_at. For engagement types, filters by event date. Not applicable for 'tags', 'subscriber_state', or 'attribution' types." }, "states": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive", "bounced", "cancelled", "complained" ] }, "description": "Subscriber lifecycle states. Required for 'subscriber_state' type; ignored for other types. Subscribers matching any of the listed states pass the filter. Strongly recommended to use `['active']` unless you specifically need other states — most subscriber-facing queries elsewhere in the app scope to active subscribers by default." }, "any": { "type": "array", "description": "Array of OR conditions. Subscriber activity must match ANY of these conditions. Engagement types accept broadcasts/URLs; 'tags' accepts tag id matchers; 'attribution' accepts attribution sub-conditions (currently 'forms'). Not applicable for 'subscribed' or 'subscriber_state' types.", "items": { "oneOf": [ { "title": "Broadcasts", "$ref": "#/components/schemas/BroadcastAnyCondition" }, { "title": "URLs (clicks only)", "$ref": "#/components/schemas/UrlAnyCondition" }, { "title": "Tag ids (tags only)", "$ref": "#/components/schemas/IdsAnyCondition" }, { "title": "Forms (attribution only)", "$ref": "#/components/schemas/FormsAnyCondition" } ] } } }, "required": [ "type" ] }, "BroadcastAnyCondition": { "type": "object", "description": "Filter by specific broadcast IDs. Subscriber must have interacted with ANY of the specified broadcasts.", "properties": { "type": { "type": "string", "enum": [ "broadcasts" ], "description": "Must be 'broadcasts'" }, "ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of broadcast IDs. Subscriber must match ANY of these." } }, "required": [ "type", "ids" ] }, "UrlAnyCondition": { "type": "object", "description": "Filter by URL patterns. Only applicable for 'clicks' type. Subscriber must have clicked ANY of the specified URLs.", "properties": { "type": { "type": "string", "enum": [ "urls" ], "description": "Must be 'urls'" }, "ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of URL IDs. Subscriber must have clicked ANY of these." }, "urls": { "type": "array", "items": { "type": "string" }, "description": "Array of URL patterns. Subscriber must have clicked ANY of these." }, "matching": { "type": "string", "enum": [ "exact", "contains", "starts_with", "ends_with" ], "description": "URL matching strategy", "default": "exact" } }, "required": [ "type" ] }, "IdsAnyCondition": { "type": "object", "description": "Match a list of ids. Used by the 'tags' filter to select tag ids.", "properties": { "type": { "type": "string", "enum": [ "ids" ], "description": "Must be 'ids'" }, "matching": { "type": "array", "items": { "type": "integer" }, "description": "Ids the filter should match against." } }, "required": [ "type", "matching" ] }, "FormsAnyCondition": { "type": "object", "description": "Attribution sub-condition: matches subscribers whose original signup attribution points at one of the given form / landing-page ids. Ids may refer to either a form or a legacy landing page — the attribution source does not distinguish between the two.", "properties": { "type": { "type": "string", "enum": [ "forms" ], "description": "Must be 'forms'" }, "ids": { "type": "array", "items": { "type": "integer" }, "description": "Form / landing-page ids the subscriber's attribution should match." } }, "required": [ "type", "ids" ] } } } }