{
  "openapi": "3.1.0",
  "info": {
    "title": "Mailnaptic API",
    "version": "1.0.0",
    "summary": "REST API of the Mailnaptic email marketing platform.",
    "description": "Contacts, lists, segments, campaigns, automations, signup forms, webhooks and transactional email. Authenticate with an API key created in Mailnaptic under Settings. Full reference with examples: https://app.mailnaptic.com/api-docs/",
    "termsOfService": "https://mailnaptic.com/terms-and-conditions/",
    "contact": {
      "name": "Mailnaptic",
      "url": "https://mailnaptic.com/contact/",
      "email": "legal@mailnaptic.com"
    }
  },
  "servers": [
    {
      "url": "https://api.mailnaptic.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "externalDocs": {
    "description": "API reference with examples",
    "url": "https://app.mailnaptic.com/api-docs/"
  },
  "tags": [
    {
      "name": "User",
      "description": "Manage the authenticated user's profile, password, and organization context."
    },
    {
      "name": "Organization",
      "description": "Manage organization members, invitations, API keys, custom fields, preferences, deliverability settings, and compliance."
    },
    {
      "name": "Domains",
      "description": "Manage sending domains, DNS verification, DMARC reporting, BIMI settings, and domain health monitoring."
    },
    {
      "name": "Lists",
      "description": "Create and manage contact lists for organizing your audience."
    },
    {
      "name": "Signup forms",
      "description": "Create embeddable signup forms and popups and read their submissions. Management endpoints need the Starter plan or above (Growth for popups) and the lists:read / lists:write API key scopes. The public endpoints at the end of this section are used by the embed script on your website: they need no authentication, accept cross-origin requests, and answer 404 for unknown, paused or plan-locked forms. Responses use the envelope {\"status\": \"ok\", \"data\": {...}}; errors use {\"status\": \"error\", \"data\": {\"message\": ...}}."
    },
    {
      "name": "Contacts",
      "description": "Create, update, import, export, and manage contacts. Contacts are the people you send emails to."
    },
    {
      "name": "Segments",
      "description": "Create dynamic segments using rule-based definitions to target specific groups of contacts."
    },
    {
      "name": "Campaigns",
      "description": "Create, send, schedule, and analyze email campaigns. Includes test sending, A/B testing, and detailed performance metrics."
    },
    {
      "name": "Automations",
      "description": "Create automated email flows triggered by events like tag additions, form submissions, webhooks, or web activity."
    },
    {
      "name": "Transactional",
      "description": "Send one-off transactional emails (order confirmations, password resets, etc.) via the API."
    },
    {
      "name": "Webhooks",
      "description": "Configure outbound webhooks that notify your systems when events occur. Supported events: contact.created, contact.updated, contact.deleted, contact.subscribed, contact.resubscribed, contact.unsubscribed, campaign.sent, campaign.completed, campaign.paused, campaign.resumed, email.delivered, email.opened, email.clicked, email.bounced, email.complained, email.unsubscribed, automation.triggered, automation.completed, form.submitted. Each delivery is a JSON POST with the body {id, event, timestamp, organization_id, data}. The id (evt_ followed by a UUID) uniquely identifies the event, is also sent in the X-Webhook-Id header, and stays the same across retries, across the endpoints subscribed to the event and across manual replays, so use it to deduplicate. Request headers: X-Webhook-Id, X-Webhook-Event, X-Webhook-Attempt, X-Webhook-Signature (hex HMAC-SHA256 of the raw body), X-Webhook-Timestamp (unix seconds) and X-Webhook-Signature-V2 (hex HMAC-SHA256 of the timestamp, a dot, then the raw body, signed with your secret). Verify V2 and reject old timestamps to guard against replays. Automation webhook actions that have a signing secret send the same X-Webhook-Timestamp and X-Webhook-Signature-V2 headers (plus the older X-Mailnaptic-Timestamp and X-Mailnaptic-Signature), so one verification routine works for both. A delivery that you re-send with the replay endpoint carries X-Webhook-Replay: true. email.delivered, email.bounced and email.complained are also sent for transactional emails: their data has type set to \"transactional\" and message_id set to the message_id returned by POST /transactional/send (campaign events keep their campaign_id fields). Transactional emails do not produce open or click events, and the bounce and complaint events only carry message_id when the report includes the original message headers. A delivery succeeds on a 2xx response. Failed deliveries are retried up to 4 times, after 30 seconds, 5 minutes, 30 minutes and 2 hours (5 attempts in total). email.opened is also sent for automatic opens, and data.open_source tells you where the open came from: human, apple_mpp (Apple Mail Privacy Protection), gmail_proxy (Gmail image proxy) or security_scanner. Filter on data.open_source === \"human\" if you only want opens by people. email.bounced also carries data.bounce_type (hard, soft or unknown) and data.category, the reason of the bounce: address_invalid (the address does not exist), mailbox_full (the inbox is full), account_inactive, blocked (the receiving server refused the sender), message_issue (for example too large), temporary or unknown."
    },
    {
      "name": "Scheduled reports",
      "description": "Configure automated reports delivered to your inbox on a recurring schedule."
    },
    {
      "name": "Email design",
      "description": "Build emails from blocks through the API and get the same HTML the visual editor produces. Campaigns, templates and automation emails created with builder_json (and no html_content) are rendered on the server when they are saved, so they are ready to send without opening the editor. Dark mode, Outlook buttons, mobile layout and your brand kit are handled by the renderer."
    },
    {
      "name": "Templates",
      "description": "Manage reusable email templates, saved blocks, and automation templates."
    },
    {
      "name": "Predictive",
      "description": "AI-powered predictions for contact engagement, campaign performance, and optimal send times."
    },
    {
      "name": "Dashboard",
      "description": "Dashboard KPIs, onboarding checklist, audit log, and public mail tracking/subscription endpoints."
    },
    {
      "name": "Workflow",
      "description": "Labels, pause and resume, resend to non-openers, version history, language variants, trash and bulk actions, approvals, holdout groups, send-time comparison and import mappings. Endpoints that list a scope work with API keys that carry it."
    }
  ],
  "paths": {
    "/user": {
      "get": {
        "operationId": "getUser",
        "tags": [
          "User"
        ],
        "summary": "Fetch the current user profile with the active organization context.",
        "description": "Fetch the current user profile with the active organization context.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "User object with organization memberships.",
            "content": {
              "application/json": {
                "example": {
                  "user": {
                    "id": 1,
                    "name": "Jane Doe",
                    "email": "jane@example.com",
                    "role": "owner",
                    "organization_id": 1,
                    "organization_name": "Acme Inc",
                    "organizations": [
                      {
                        "id": 1,
                        "name": "Acme Inc",
                        "role": "owner"
                      }
                    ]
                  },
                  "csrfToken": "..."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "put": {
        "operationId": "putUser",
        "tags": [
          "User"
        ],
        "summary": "Update the current user's name and/or email address.",
        "description": "Update the current user's name and/or email address.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Updated user object.",
            "content": {
              "application/json": {
                "example": {
                  "user": {
                    "id": 1,
                    "name": "Jane Smith",
                    "email": "jane@example.com"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "New display name. Max 255 chars."
                  },
                  "email": {
                    "type": "string",
                    "description": "New email address. Requires re-verification."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/organization/members": {
      "get": {
        "operationId": "getOrganizationMembers",
        "tags": [
          "Organization"
        ],
        "summary": "List all members and their roles in the active organization.",
        "description": "List all members and their roles in the active organization.\n\nRequired API key scope: organization:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of organization members with roles.",
            "content": {
              "application/json": {
                "example": {
                  "members": [
                    {
                      "id": 1,
                      "name": "Jane Doe",
                      "email": "jane@example.com",
                      "role": "owner",
                      "joined_at": "2025-01-15T10:30:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/custom-fields": {
      "get": {
        "operationId": "getOrganizationCustomFields",
        "tags": [
          "Organization"
        ],
        "summary": "List all contact custom field definitions for the organization.",
        "description": "List all contact custom field definitions for the organization.\n\nRequired API key scope: organization:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of custom field definitions and a flat list of keys.",
            "content": {
              "application/json": {
                "example": {
                  "fields": [
                    {
                      "id": 1,
                      "field_key": "favorite_city",
                      "field_label": "Favorite City",
                      "field_type": "text"
                    }
                  ],
                  "keys": [
                    "favorite_city"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/preferences-settings": {
      "get": {
        "operationId": "getOrganizationPreferencesSettings",
        "tags": [
          "Organization"
        ],
        "summary": "Get organization preference center settings.",
        "description": "Get organization preference center settings.\n\nRequired API key scope: organization:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Preference center configuration.",
            "content": {
              "application/json": {
                "example": {
                  "allow_list_unsubscribe_preferences": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/deliverability-settings": {
      "get": {
        "operationId": "getOrganizationDeliverabilitySettings",
        "tags": [
          "Organization"
        ],
        "summary": "Get deliverability and warmup settings with current overview metrics.",
        "description": "Get deliverability and warmup settings with current overview metrics.\n\nRequired API key scope: organization:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Deliverability settings and overview metrics."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/compliance-settings": {
      "get": {
        "operationId": "getOrganizationComplianceSettings",
        "tags": [
          "Organization"
        ],
        "summary": "Get GDPR, CASL, and frequency cap compliance settings.",
        "description": "Get GDPR, CASL, and frequency cap compliance settings.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Compliance configuration object.",
            "content": {
              "application/json": {
                "example": {
                  "require_consent_per_message_type": false,
                  "double_optin_recency_days": null,
                  "dpa_accepted_at": null,
                  "frequency_cap_enabled": false,
                  "frequency_cap_max_sends": 5,
                  "frequency_cap_window_days": 7
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/settings": {
      "patch": {
        "operationId": "patchOrganizationSettings",
        "tags": [
          "Organization"
        ],
        "summary": "Update compliance settings (partial update).",
        "description": "Update compliance settings (partial update).\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Confirmation message.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Compliance settings updated"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "require_consent_per_message_type": {
                    "type": "boolean",
                    "description": "Enable strict GDPR/CASL consent per message type."
                  },
                  "double_optin_recency_days": {
                    "type": "integer",
                    "description": "Number of days before double opt-in expires."
                  },
                  "frequency_cap_enabled": {
                    "type": "boolean",
                    "description": "Enable per-contact frequency capping."
                  },
                  "frequency_cap_max_sends": {
                    "type": "integer",
                    "description": "Max sends per contact within the window."
                  },
                  "frequency_cap_window_days": {
                    "type": "integer",
                    "description": "Window in days for frequency cap."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/organization/open-tracking-settings": {
      "get": {
        "operationId": "getOrganizationOpenTrackingSettings",
        "tags": [
          "Organization"
        ],
        "summary": "Get the open tracking setting.",
        "description": "Get the open tracking setting. Apple Mail Privacy Protection and Gmail prefetch open pixels automatically, so these opens are tagged as automatic. By default they are ignored for engagement scores, open-based segments (email_opened, email_not_opened, last_active_days), campaign_open and campaign_activity automation triggers, A/B test winners by opens, and send-time optimization. They are still included in total opens and in email.opened webhooks (see data.open_source).\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "The count_proxy_opens flag (default false). schema_ready is false only while a database update is still being applied.",
            "content": {
              "application/json": {
                "example": {
                  "count_proxy_opens": false,
                  "schema_ready": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "patch": {
        "operationId": "patchOrganizationOpenTrackingSettings",
        "tags": [
          "Organization"
        ],
        "summary": "Choose whether automatic opens (Apple Mail Privacy Protection, Gmail image proxy, security scanners) count as engagement.",
        "description": "Choose whether automatic opens (Apple Mail Privacy Protection, Gmail image proxy, security scanners) count as engagement. Owner or admin only.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "The updated setting. Responds 400 for a non-boolean value, 403 for members without owner or admin rights and 409 while a database update is pending.",
            "content": {
              "application/json": {
                "example": {
                  "count_proxy_opens": true,
                  "schema_ready": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "count_proxy_opens": {
                    "type": "boolean",
                    "description": "true to count automatic opens for engagement scores, segments, automations, A/B winners and send-time optimization. Default false."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/organization/unsubscribe-reasons": {
      "get": {
        "operationId": "getOrganizationUnsubscribeReasons",
        "tags": [
          "Organization"
        ],
        "summary": "List unsubscribe reasons collected from the preference center.",
        "description": "List unsubscribe reasons collected from the preference center.\n\nRequired API key scope: organization:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Aggregated unsubscribe reasons with counts.",
            "content": {
              "application/json": {
                "example": {
                  "reasons": [
                    {
                      "reason": "Too many emails",
                      "count": 42
                    },
                    {
                      "reason": "Not relevant",
                      "count": 15
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/unsubscribe-reasons/export": {
      "get": {
        "operationId": "getOrganizationUnsubscribeReasonsExport",
        "tags": [
          "Organization"
        ],
        "summary": "Export unsubscribe reasons as CSV.",
        "description": "Export unsubscribe reasons as CSV.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "CSV string of unsubscribe reasons.",
            "content": {
              "application/json": {
                "example": {
                  "csv": "reason,count\nToo many emails,42\nNot relevant,15"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/engagement-rules": {
      "get": {
        "operationId": "getOrganizationEngagementRules",
        "tags": [
          "Organization"
        ],
        "summary": "Get engagement scoring rules for the organization.",
        "description": "Get engagement scoring rules for the organization. Returns defaults if no custom rules exist.\n\nRequired API key scope: organization:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Engagement rules array and whether they are customized.",
            "content": {
              "application/json": {
                "example": {
                  "rules": [
                    {
                      "trigger_event": "email_open",
                      "points": 2,
                      "decay_days": 90,
                      "priority": 1
                    },
                    {
                      "trigger_event": "email_click",
                      "points": 5,
                      "decay_days": 90,
                      "priority": 2
                    },
                    {
                      "trigger_event": "site_visit",
                      "points": 1,
                      "decay_days": 30,
                      "priority": 3
                    },
                    {
                      "trigger_event": "site_event",
                      "points": 3,
                      "decay_days": 30,
                      "priority": 4
                    }
                  ],
                  "has_custom_rules": false
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/site-tracking-key": {
      "get": {
        "operationId": "getOrganizationSiteTrackingKey",
        "tags": [
          "Organization"
        ],
        "summary": "Get the site tracking key for embedding the tracking script.",
        "description": "Get the site tracking key for embedding the tracking script.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "The organization site tracking key.",
            "content": {
              "application/json": {
                "example": {
                  "site_key": "sk_abc123def456..."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/site-tracking-key/regenerate": {
      "post": {
        "operationId": "postOrganizationSiteTrackingKeyRegenerate",
        "tags": [
          "Organization"
        ],
        "summary": "Regenerate the site tracking key.",
        "description": "Regenerate the site tracking key. The old key stops working immediately.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new site tracking key.",
            "content": {
              "application/json": {
                "example": {
                  "site_key": "sk_new789ghi012..."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/domains": {
      "get": {
        "operationId": "getDomains",
        "tags": [
          "Domains"
        ],
        "summary": "List all sending domains for the active organization.",
        "description": "List all sending domains for the active organization.\n\nRequired API key scope: domains:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of domain objects.",
            "content": {
              "application/json": {
                "example": {
                  "domains": [
                    {
                      "id": 1,
                      "name": "example.com",
                      "from_name": "Phillip from Example",
                      "from_local_part": "hello",
                      "status": "verified",
                      "health": "good",
                      "created_at": "2025-01-01T00:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postDomains",
        "tags": [
          "Domains"
        ],
        "summary": "Create a new sending domain draft.",
        "description": "Create a new sending domain draft. After creation, verify DNS records.\n\nRequired API key scope: domains:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new domain ID and required DNS records.",
            "content": {
              "application/json": {
                "example": {
                  "domain_id": 1,
                  "dns_records": [
                    {
                      "type": "CNAME",
                      "name": "em1234.example.com",
                      "value": "u1234.wl.sendgrid.net",
                      "status": "pending"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "The domain name, e.g. \"example.com\". Max 255 chars."
                  },
                  "from_name": {
                    "type": "string",
                    "description": "Default sender name. Max 255 chars."
                  },
                  "from_local_part": {
                    "type": "string",
                    "description": "Local part of from address (before @). Max 64 chars."
                  }
                },
                "required": [
                  "domain"
                ]
              }
            }
          }
        }
      }
    },
    "/domains/{id}/dns-records": {
      "get": {
        "operationId": "getDomainsIdDnsRecords",
        "tags": [
          "Domains"
        ],
        "summary": "Get required DNS records and their current verification status.",
        "description": "Get required DNS records and their current verification status.\n\nRequired API key scope: domains:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DNS check results and any DMARC warnings.",
            "content": {
              "application/json": {
                "example": {
                  "domain_id": 1,
                  "checks": [
                    {
                      "type": "CNAME",
                      "name": "em1234.example.com",
                      "expected": "u1234.wl.sendgrid.net",
                      "valid": true
                    }
                  ],
                  "dmarc_warning": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/domains/{id}/verify-dns": {
      "post": {
        "operationId": "postDomainsIdVerifyDns",
        "tags": [
          "Domains"
        ],
        "summary": "Trigger an immediate DNS verification check for the domain.",
        "description": "Trigger an immediate DNS verification check for the domain.\n\nRequired API key scope: domains:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Verification status with detailed check results.",
            "content": {
              "application/json": {
                "example": {
                  "domain_id": 1,
                  "status": {
                    "verified": true
                  },
                  "checks": [
                    "..."
                  ],
                  "checked_at": "2025-06-15T12:00:00Z"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/domains/{id}": {
      "put": {
        "operationId": "putDomainsId",
        "tags": [
          "Domains"
        ],
        "summary": "Update sender defaults, mailing address, and brand colors for a domain.",
        "description": "Update sender defaults, mailing address, and brand colors for a domain.\n\nRequired API key scope: domains:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated domain object.",
            "content": {
              "application/json": {
                "example": {
                  "domain": {
                    "id": 1,
                    "name": "example.com",
                    "from_name": "Support Team",
                    "account_mailing_address": "123 Main St, Copenhagen, Denmark"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from_name": {
                    "type": "string",
                    "description": "Default sender name. Max 255 chars."
                  },
                  "from_local_part": {
                    "type": "string",
                    "description": "Local part of from address. Max 64 chars."
                  },
                  "organization_name": {
                    "type": "string",
                    "description": "Organization name shown in emails. Max 255 chars."
                  },
                  "account_mailing_address": {
                    "type": "string",
                    "description": "Physical mailing address (CAN-SPAM). Max 500 chars."
                  },
                  "brand_colors": {
                    "type": "object",
                    "description": "Brand color palette. Max 50 items. Each has name (string) and color (string)."
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteDomainsId",
        "tags": [
          "Domains"
        ],
        "summary": "Delete a sending domain.",
        "description": "Delete a sending domain.\n\nRequired API key scope: domains:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation message.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Domain deleted"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/domains/{id}/dmarc-policy": {
      "put": {
        "operationId": "putDomainsIdDmarcPolicy",
        "tags": [
          "Domains"
        ],
        "summary": "Update the stored DMARC policy metadata for a domain.",
        "description": "Update the stored DMARC policy metadata for a domain.\n\nRequired API key scope: domains:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated DMARC policy with recommended DNS value.",
            "content": {
              "application/json": {
                "example": {
                  "domain_id": 1,
                  "dmarc_policy": "quarantine",
                  "dmarc_rua": "dmarc@example.com",
                  "previous_policy": "none",
                  "dns_value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "policy": {
                    "type": "string",
                    "description": "DMARC policy level."
                  },
                  "rua": {
                    "type": "string",
                    "description": "DMARC aggregate report email address. Max 255 chars."
                  }
                },
                "required": [
                  "policy"
                ]
              }
            }
          }
        }
      }
    },
    "/domains/{id}/dmarc-reports": {
      "get": {
        "operationId": "getDomainsIdDmarcReports",
        "tags": [
          "Domains"
        ],
        "summary": "List DMARC aggregate reports and statistics for a domain.",
        "description": "List DMARC aggregate reports and statistics for a domain.\n\nRequired API key scope: domains:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DMARC reports, stats, and recommendations."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/domains/{id}/tracking": {
      "get": {
        "operationId": "getDomainsIdTracking",
        "tags": [
          "Domains"
        ],
        "summary": "Get site tracking status for a domain, including the embeddable snippet.",
        "description": "Get site tracking status for a domain, including the embeddable snippet.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tracking key, snippet, and event stats.",
            "content": {
              "application/json": {
                "example": {
                  "site_key": "sk_abc123...",
                  "snippet": "<script src=\"...\" data-key=\"sk_abc123...\"></script>",
                  "last_received_at": "2025-06-14T18:00:00Z",
                  "events_last_30_days": 1523,
                  "total_events": 8420,
                  "receiving_data": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/domains/{id}/fbl-guidance": {
      "get": {
        "operationId": "getDomainsIdFblGuidance",
        "tags": [
          "Domains"
        ],
        "summary": "Get feedback loop program guidance for major email providers.",
        "description": "Get feedback loop program guidance for major email providers.\n\nRequired API key scope: domains:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "FBL program list with setup instructions.",
            "content": {
              "application/json": {
                "example": {
                  "domain": "example.com",
                  "fbl_programs": [
                    {
                      "name": "Gmail Postmaster Tools",
                      "description": "Monitor spam rate and domain reputation for Gmail",
                      "url": "https://postmaster.google.com/v2/",
                      "steps": [
                        "..."
                      ],
                      "free": true
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/domains/{id}/blacklist-status": {
      "get": {
        "operationId": "getDomainsIdBlacklistStatus",
        "tags": [
          "Domains"
        ],
        "summary": "Check if the domain appears on any major blocklists.",
        "description": "Check if the domain appears on any major blocklists.\n\nRequired API key scope: domains:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Blocklist check results and recent listing events.",
            "content": {
              "application/json": {
                "example": {
                  "domain": "example.com",
                  "listed": false,
                  "checks": [
                    "..."
                  ],
                  "recent_events": []
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/domains/{id}/bimi-settings": {
      "put": {
        "operationId": "putDomainsIdBimiSettings",
        "tags": [
          "Domains"
        ],
        "summary": "Update BIMI (Brand Indicators for Message Identification) settings for a domain.",
        "description": "Update BIMI (Brand Indicators for Message Identification) settings for a domain.\n\nRequired API key scope: domains:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated BIMI settings with recommended DNS value.",
            "content": {
              "application/json": {
                "example": {
                  "domain_id": 1,
                  "bimi_logo_url": "https://example.com/logo.svg",
                  "bimi_vmc_url": null,
                  "bimi_dns_value": "v=BIMI1; l=https://example.com/logo.svg"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bimi_logo_url": {
                    "type": "string",
                    "description": "URL to the SVG logo for BIMI."
                  },
                  "bimi_vmc_url": {
                    "type": "string",
                    "description": "URL to the VMC (Verified Mark Certificate)."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/lists": {
      "get": {
        "operationId": "getLists",
        "tags": [
          "Lists"
        ],
        "summary": "List all contact lists in the active organization.",
        "description": "List all contact lists in the active organization.\n\nRequired API key scope: lists:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of list objects with contact counts.",
            "content": {
              "application/json": {
                "example": {
                  "lists": [
                    {
                      "id": 1,
                      "name": "Newsletter Subscribers",
                      "description": "Main newsletter list",
                      "double_optin": false,
                      "bounce_limit": 3,
                      "sending_domain_id": null,
                      "contact_count": 2500,
                      "created_at": "2025-01-01T00:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postLists",
        "tags": [
          "Lists"
        ],
        "summary": "Create a new contact list.",
        "description": "Create a new contact list.\n\nRequired API key scope: lists:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new list ID.",
            "content": {
              "application/json": {
                "example": {
                  "list_id": 1
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sending_domain_id": {
                    "type": "integer",
                    "description": "A verified sending domain. Double opt-in confirmation emails for this list come from that domain (for example info@yourdomain.com) in its brand kit colours. Send null to clear. Without one, your only verified domain is used, or the Mailnaptic address when you have several."
                  },
                  "name": {
                    "type": "string",
                    "description": "List name. Max 255 chars."
                  },
                  "description": {
                    "type": "string",
                    "description": "List description. Max 1000 chars."
                  },
                  "double_optin": {
                    "type": "boolean",
                    "description": "Require double opt-in for new subscribers. Default false."
                  },
                  "bounce_limit": {
                    "type": "integer",
                    "description": "Auto-remove contacts after N bounces. Min 1."
                  },
                  "mailbox_full_wait_days": {
                    "type": "integer",
                    "description": "When a contact's inbox is full, wait this many days before trying them again (1 to 365, default 14). The contact is paused, not suppressed. On several lists the longest wait applies."
                  },
                  "mailbox_full_retries": {
                    "type": "integer",
                    "description": "How many times to try again after a full inbox before suppressing the contact (0 to 10, default 2). 0 suppresses at once."
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        }
      }
    },
    "/lists/{id}": {
      "get": {
        "operationId": "getListsId",
        "tags": [
          "Lists"
        ],
        "summary": "Fetch one list with its contacts and metrics.",
        "description": "Fetch one list with its contacts and metrics.\n\nRequired API key scope: lists:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List object with associated contacts.",
            "content": {
              "application/json": {
                "example": {
                  "list": {
                    "id": 1,
                    "name": "Newsletter Subscribers",
                    "description": "Main newsletter list",
                    "double_optin": false,
                    "bounce_limit": 3
                  },
                  "contacts": [
                    {
                      "id": 1,
                      "email": "jane@example.com",
                      "first_name": "Jane"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "put": {
        "operationId": "putListsId",
        "tags": [
          "Lists"
        ],
        "summary": "Update a contact list.",
        "description": "Update a contact list.\n\nRequired API key scope: lists:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The updated list ID.",
            "content": {
              "application/json": {
                "example": {
                  "list_id": 1
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sending_domain_id": {
                    "type": "integer",
                    "description": "A verified sending domain. Double opt-in confirmation emails for this list come from that domain (for example info@yourdomain.com) in its brand kit colours. Send null to clear. Without one, your only verified domain is used, or the Mailnaptic address when you have several."
                  },
                  "name": {
                    "type": "string",
                    "description": "Updated list name. Max 255 chars."
                  },
                  "description": {
                    "type": "string",
                    "description": "Updated description. Max 1000 chars."
                  },
                  "double_optin": {
                    "type": "boolean",
                    "description": "Toggle double opt-in."
                  },
                  "bounce_limit": {
                    "type": "integer",
                    "description": "Updated bounce limit."
                  },
                  "mailbox_full_wait_days": {
                    "type": "integer",
                    "description": "Days to wait after a full inbox (1 to 365)."
                  },
                  "mailbox_full_retries": {
                    "type": "integer",
                    "description": "Retries after a full inbox before suppressing (0 to 10)."
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteListsId",
        "tags": [
          "Lists"
        ],
        "summary": "Delete a contact list.",
        "description": "Delete a contact list. Contacts in the list are not deleted.\n\nRequired API key scope: lists:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation of deletion.",
            "content": {
              "application/json": {
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/signup-forms": {
      "get": {
        "operationId": "getSignupForms",
        "tags": [
          "Signup forms"
        ],
        "summary": "List the signup forms of the organization with the plan limits.",
        "description": "List the signup forms of the organization with the plan limits.\n\nRequired API key scope: lists:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "forms (each with the full form configuration) and limits. limits.max is null for unlimited plans. Responds 403 with code FEATURE_LOCKED when the plan has no signup forms.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "data": {
                    "forms": [
                      {
                        "id": 3,
                        "public_key": "Qm3x9k2LpV7aR1tYc8WzNd4B",
                        "name": "Footer signup",
                        "status": "active",
                        "list_id": 1,
                        "tags": [
                          "website"
                        ],
                        "double_optin": true,
                        "submissions_30d": 42,
                        "created_at": "2026-10-01T09:00:00Z"
                      }
                    ],
                    "limits": {
                      "used": 1,
                      "max": 5,
                      "popups_enabled": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postSignupForms",
        "tags": [
          "Signup forms"
        ],
        "summary": "Create a signup form.",
        "description": "Create a signup form. Limited to 30 requests per minute. Custom field keys used in fields are registered as custom fields of the organization.\n\nRequired API key scope: lists:write.\n\nAuthentication: Session or API key, owner or admin only (members get 403). Each change is written to the audit log..",
        "responses": {
          "201": {
            "description": "The created form with HTTP 201. Errors: 400 for invalid input or an unknown list, 402 with code SIGNUP_FORM_LIMIT_REACHED when the plan limit is reached, 403 with code FEATURE_LOCKED when the plan has no signup forms or popups are not included.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "data": {
                    "form": {
                      "id": 3,
                      "public_key": "Qm3x9k2LpV7aR1tYc8WzNd4B",
                      "name": "Footer signup",
                      "status": "active"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Form name. Max 255 chars."
                  },
                  "list_id": {
                    "type": "integer",
                    "description": "List that new subscribers join. Must belong to your organization."
                  },
                  "status": {
                    "type": "string",
                    "description": "active or paused."
                  },
                  "tags": {
                    "type": "string",
                    "description": "Tags applied to new subscribers. Up to 10, stored in lower case."
                  },
                  "double_optin": {
                    "type": "boolean",
                    "description": "Send a confirmation email before subscribing. Default true. Always true when the list requires double opt-in."
                  },
                  "fields": {
                    "type": "object",
                    "description": "Up to 10 fields: { key, label, type (text or tel), required, placeholder }. email is always present and required; first_name and last_name are built in; any other key becomes a custom field."
                  },
                  "consent_text": {
                    "type": "string",
                    "description": "Consent text shown under the fields. Max 2000 chars."
                  },
                  "consent_required": {
                    "type": "boolean",
                    "description": "Require the visitor to tick a consent box. Needs consent_text."
                  },
                  "success_message": {
                    "type": "string",
                    "description": "Message shown after signup. Max 500 chars."
                  },
                  "redirect_url": {
                    "type": "string",
                    "description": "https URL to send the visitor to after signup."
                  },
                  "style": {
                    "type": "object",
                    "description": "title, description, primary_color, text_color, background_color (hex), border_radius (0 to 32), font_size (12 to 20), button_text."
                  },
                  "popup": {
                    "type": "object",
                    "description": "enabled, trigger (delay_seconds, scroll_percent, exit_intent or click_selector), delay_seconds, scroll_percent, click_selector, frequency_days (0 to 365), mobile_enabled, position (modal, bottom_right or bottom_left). Enabling a popup needs the Growth plan."
                  },
                  "allowed_origins": {
                    "type": "string",
                    "description": "Up to 20 origins that may show and submit the form, for example https://example.com or https://*.example.com. Empty means any site."
                  }
                },
                "required": [
                  "name",
                  "list_id"
                ]
              }
            }
          }
        }
      }
    },
    "/signup-forms/{id}": {
      "get": {
        "operationId": "getSignupFormsId",
        "tags": [
          "Signup forms"
        ],
        "summary": "Fetch one signup form.",
        "description": "Fetch one signup form.\n\nRequired API key scope: lists:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The form. Responds 404 if the form does not exist in your organization.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "data": {
                    "form": {
                      "id": 3,
                      "public_key": "Qm3x9k2LpV7aR1tYc8WzNd4B",
                      "name": "Footer signup",
                      "status": "active",
                      "list_id": 1,
                      "tags": [
                        "website"
                      ],
                      "double_optin": true,
                      "fields": [
                        {
                          "key": "email",
                          "label": "Email",
                          "type": "email",
                          "required": true,
                          "placeholder": "you@example.com"
                        }
                      ],
                      "consent_text": "I agree to receive emails.",
                      "consent_required": true,
                      "success_message": null,
                      "redirect_url": null,
                      "style": {
                        "title": "Join our newsletter",
                        "primary_color": "#6366f1",
                        "button_text": "Subscribe"
                      },
                      "popup": {
                        "enabled": false,
                        "trigger": "delay_seconds",
                        "delay_seconds": 5,
                        "position": "modal"
                      },
                      "allowed_origins": []
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "put": {
        "operationId": "putSignupFormsId",
        "tags": [
          "Signup forms"
        ],
        "summary": "Update a signup form.",
        "description": "Update a signup form. Send only the fields you want to change. Changes apply to the embedded form the next time it loads.\n\nRequired API key scope: lists:write.\n\nAuthentication: Session or API key, owner or admin only (members get 403). Each change is written to the audit log..",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The updated form. The body accepts the same fields as the create endpoint. Responds 400 for invalid input, 404 if the form does not exist.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "data": {
                    "form": {
                      "id": 3,
                      "status": "paused"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "delete": {
        "operationId": "deleteSignupFormsId",
        "tags": [
          "Signup forms"
        ],
        "summary": "Delete a signup form.",
        "description": "Delete a signup form. The form stops working on your website. Existing contacts are not affected.\n\nRequired API key scope: lists:write.\n\nAuthentication: Session or API key, owner or admin only (members get 403). Each change is written to the audit log..",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation of deletion. Responds 404 if the form does not exist.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "data": {
                    "message": "Form deleted"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/signup-forms/{id}/submissions": {
      "get": {
        "operationId": "getSignupFormsIdSubmissions",
        "tags": [
          "Signup forms"
        ],
        "summary": "List the 100 most recent submissions of a form, newest first.",
        "description": "List the 100 most recent submissions of a form, newest first. IP addresses are masked.\n\nRequired API key scope: lists:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "submissions with status ok (subscribed), spam, invalid or blocked (not added, for example a suppressed address). email is null once the contact has been erased.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "data": {
                    "submissions": [
                      {
                        "id": 120,
                        "status": "ok",
                        "email": "jane@example.com",
                        "contact_id": 55,
                        "ip": "203.0.113.***",
                        "user_agent": "Mozilla/5.0",
                        "created_at": "2026-10-12T10:15:00Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/public/form-embed.js": {
      "get": {
        "operationId": "getPublicFormEmbed",
        "tags": [
          "Signup forms"
        ],
        "summary": "The embed script.",
        "description": "The embed script. Add it to your page with a div that has data-mailnaptic-form=\"<public_key>\" for an inline form, or with data-form=\"<public_key>\" and data-mode=\"popup\" on the script tag for a popup. The form renders inside an isolated container.\n\nAuthentication: None.",
        "responses": {
          "200": {
            "description": "JavaScript. Supports ETag based revalidation."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "security": []
      }
    },
    "/public/forms/{publicKey}": {
      "get": {
        "operationId": "getPublicFormsKey",
        "tags": [
          "Signup forms"
        ],
        "summary": "Public form configuration used by the embed script.",
        "description": "Public form configuration used by the embed script. Returns the fields, style, popup settings and consent text, plus a signed token that must be sent back when submitting. Limited to 120 requests per minute per IP address. Not cached. If the form has allowed_origins, requests from other sites get 403.\n\nAuthentication: None.",
        "parameters": [
          {
            "name": "publicKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The public configuration and a token. Responds 404 for unknown, paused or plan-locked forms.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "data": {
                    "public_key": "Qm3x9k2LpV7aR1tYc8WzNd4B",
                    "name": "Footer signup",
                    "fields": [
                      {
                        "key": "email",
                        "label": "Email",
                        "type": "email",
                        "required": true
                      }
                    ],
                    "style": {
                      "title": "Join our newsletter",
                      "button_text": "Subscribe"
                    },
                    "popup": {
                      "enabled": false
                    },
                    "consent": {
                      "text": "I agree to receive emails.",
                      "required": true
                    },
                    "double_optin": true,
                    "success_message": "Thanks! Please check your email to confirm your subscription.",
                    "redirect_url": null,
                    "token": "m1abc.Zx9..."
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "security": []
      }
    },
    "/public/forms/{publicKey}/submit": {
      "post": {
        "operationId": "postPublicFormsKeySubmit",
        "tags": [
          "Signup forms"
        ],
        "summary": "Submit the form.",
        "description": "Submit the form. The body must be plain application/json (no compression, no text/plain) and at most 16 KB. Send each configured field by its key, the token from the config call, consent: true when consent is required, and leave hp empty (it is a honeypot). Submissions made less than a few seconds after the config call are discarded. Rate limited per IP address and form. Spam, suppressed, already subscribed and over-limit submissions all receive the same success response, so the endpoint never reveals whether an address exists.\n\nAuthentication: None.",
        "parameters": [
          {
            "name": "publicKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The success body. Errors: 400 for missing fields, invalid email, missing consent or an expired token; 403 when the site is not allowed; 404 for unknown forms; 415 when the content type is not application/json or the body is compressed; 429 when rate limited. Successful signups also fire the form.submitted, contact.created and contact.subscribed webhooks.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "data": {
                    "success": true,
                    "message": "Thanks! Please check your email to confirm your subscription.",
                    "double_optin": true,
                    "redirect_url": null
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Email address. Invalid syntax and disposable domains get 400."
                  },
                  "first_name": {
                    "type": "string",
                    "description": "Any other field configured on the form, by its key."
                  },
                  "token": {
                    "type": "string",
                    "description": "Token from the config call. Valid for 48 hours; an expired token gets 400."
                  },
                  "consent": {
                    "type": "boolean",
                    "description": "Must be true when the form requires consent."
                  },
                  "hp": {
                    "type": "string",
                    "description": "Honeypot. Leave empty."
                  }
                },
                "required": [
                  "email",
                  "token"
                ]
              }
            }
          }
        }
      }
    },
    "/contacts": {
      "get": {
        "operationId": "getContacts",
        "tags": [
          "Contacts"
        ],
        "summary": "List contacts in the active organization with pagination, search, and filtering.",
        "description": "List contacts in the active organization with pagination, search, and filtering.\n\nRequired API key scope: contacts:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (default 1).",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Results per page (default 50, max 500). per_page is accepted as an alias.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search by email, first name, or last name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by status: active, suppressed, or unsubscribed (the contacts that unsubscribed themselves). A suppressed contact has a suppression_reason: unsubscribe, hard_bounce, soft_bounce, complaint and so on. A contact whose inbox was full (mailbox_full) or whose account was inactive (account_inactive) is paused: they stay suppressed until suppression_retry_at, then become active again by themselves.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "list_id",
            "in": "query",
            "required": false,
            "description": "Filter to contacts in a specific list.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Filter to contacts with a specific tag.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated array of contacts. Contacts who unsubscribed have status \"suppressed\" and suppression_reason \"unsubscribe\".",
            "content": {
              "application/json": {
                "example": {
                  "contacts": [
                    {
                      "id": 1,
                      "email": "jane@example.com",
                      "first_name": "Jane",
                      "last_name": "Doe",
                      "status": "active",
                      "suppression_reason": null,
                      "tags": [
                        "vip",
                        "newsletter"
                      ],
                      "engagement_score": 85,
                      "created_at": "2025-01-15T10:30:00Z"
                    }
                  ],
                  "pagination": {
                    "total": 1250,
                    "page": 1,
                    "page_size": 20,
                    "total_pages": 63
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postContacts",
        "tags": [
          "Contacts"
        ],
        "summary": "Create a new contact.",
        "description": "Create a new contact. If the email already exists, the existing contact is upserted.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new (or existing) contact ID.",
            "content": {
              "application/json": {
                "example": {
                  "contact_id": 42
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Contact email address."
                  },
                  "first_name": {
                    "type": "string",
                    "description": "First name. Max 255 chars."
                  },
                  "last_name": {
                    "type": "string",
                    "description": "Last name. Max 255 chars."
                  },
                  "list_ids": {
                    "type": "integer",
                    "description": "IDs of lists to subscribe the contact to."
                  },
                  "tags": {
                    "type": "string",
                    "description": "Tags to assign. Each max 100 chars."
                  },
                  "custom_fields": {
                    "type": "object",
                    "description": "Key-value map of custom field data."
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        }
      }
    },
    "/contacts/{id}": {
      "get": {
        "operationId": "getContactsId",
        "tags": [
          "Contacts"
        ],
        "summary": "Fetch a single contact with all fields, tags, lists, and custom data.",
        "description": "Fetch a single contact with all fields, tags, lists, and custom data.\n\nRequired API key scope: contacts:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full contact object.",
            "content": {
              "application/json": {
                "example": {
                  "contact": {
                    "id": 42,
                    "email": "jane@example.com",
                    "first_name": "Jane",
                    "last_name": "Doe",
                    "status": "subscribed",
                    "tags": [
                      "vip",
                      "newsletter"
                    ],
                    "lists": [
                      {
                        "id": 1,
                        "name": "Newsletter Subscribers"
                      }
                    ],
                    "custom_fields": {
                      "favorite_city": "Lisbon"
                    },
                    "engagement_score": 85,
                    "created_at": "2025-01-15T10:30:00Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "put": {
        "operationId": "putContactsId",
        "tags": [
          "Contacts"
        ],
        "summary": "Update a contact's fields, tags, list memberships, and custom data.",
        "description": "Update a contact's fields, tags, list memberships, and custom data.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The updated contact ID.",
            "content": {
              "application/json": {
                "example": {
                  "contact_id": 42
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Contact email (can be changed)."
                  },
                  "first_name": {
                    "type": "string",
                    "description": "Updated first name."
                  },
                  "last_name": {
                    "type": "string",
                    "description": "Updated last name."
                  },
                  "status": {
                    "type": "string",
                    "description": "Update subscription status."
                  },
                  "list_ids": {
                    "type": "integer",
                    "description": "Replace list memberships with these list IDs."
                  },
                  "tags": {
                    "type": "string",
                    "description": "Replace tags with this array."
                  },
                  "custom_fields": {
                    "type": "object",
                    "description": "Merge custom field key-value pairs."
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteContactsId",
        "tags": [
          "Contacts"
        ],
        "summary": "Soft-delete a contact.",
        "description": "Soft-delete a contact. The contact is marked as deleted but data is retained.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation of deletion.",
            "content": {
              "application/json": {
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/{id}/activity": {
      "get": {
        "operationId": "getContactsIdActivity",
        "tags": [
          "Contacts"
        ],
        "summary": "Fetch the activity timeline for a contact, including email and web events.",
        "description": "Fetch the activity timeline for a contact, including email and web events.\n\nRequired API key scope: contacts:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "description": "Filter type: \"all\", \"email\", or \"web\". Default \"all\".",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of activity events.",
            "content": {
              "application/json": {
                "example": {
                  "activities": [
                    {
                      "type": "email_open",
                      "campaign_name": "Spring launch",
                      "timestamp": "2025-06-14T10:30:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/{id}/lists/{listId}": {
      "delete": {
        "operationId": "deleteContactsIdListsListid",
        "tags": [
          "Contacts"
        ],
        "summary": "Take a contact off one list.",
        "description": "Take a contact off one list. Other lists, tags and fields are untouched (PUT /contacts/:id replaces all of them). Returns 404 when the contact is not on that list.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "listId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation that the contact was removed from the list.",
            "content": {
              "application/json": {
                "example": {
                  "removed": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/{id}/tags/{tagId}": {
      "delete": {
        "operationId": "deleteContactsIdTagsTagid",
        "tags": [
          "Contacts"
        ],
        "summary": "Take one tag off a contact.",
        "description": "Take one tag off a contact. The tag stays on other contacts. Returns 404 when the contact does not have that tag.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "tagId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation that the tag was removed from the contact.",
            "content": {
              "application/json": {
                "example": {
                  "removed": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/{id}/unsuppress": {
      "post": {
        "operationId": "postContactsIdUnsuppress",
        "tags": [
          "Contacts"
        ],
        "summary": "Remove suppression from a contact, allowing them to receive emails again.",
        "description": "Remove suppression from a contact, allowing them to receive emails again.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Confirmation of unsuppression.",
            "content": {
              "application/json": {
                "example": {
                  "unsuppressed": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/{id}/unsubscribe": {
      "post": {
        "operationId": "postContactsIdUnsubscribe",
        "tags": [
          "Contacts"
        ],
        "summary": "Unsubscribe a contact exactly as the unsubscribe link does: the address is added to the suppression list (reason unsubscribe, source api), the contact status be",
        "description": "Unsubscribe a contact exactly as the unsubscribe link does: the address is added to the suppression list (reason unsubscribe, source api), the contact status becomes suppressed, and the contact_unsubscribed automation trigger and webhook events fire.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Confirmation of unsubscription. The optional reason is stored with the suppression.",
            "content": {
              "application/json": {
                "example": {
                  "unsubscribed": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/{id}/merge": {
      "post": {
        "operationId": "postContactsIdMerge",
        "tags": [
          "Contacts"
        ],
        "summary": "Merge another contact into this one.",
        "description": "Merge another contact into this one. The source contact is deleted and its data transferred.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The surviving contact with merged data.",
            "content": {
              "application/json": {
                "example": {
                  "contact": {
                    "id": 42,
                    "email": "jane@example.com",
                    "tags": [
                      "vip",
                      "newsletter",
                      "merged-tag"
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "source_contact_id": {
                    "type": "integer",
                    "description": "ID of the contact to merge from (will be deleted)."
                  }
                },
                "required": [
                  "source_contact_id"
                ]
              }
            }
          }
        }
      }
    },
    "/contacts/bulk": {
      "post": {
        "operationId": "postContactsBulk",
        "tags": [
          "Contacts"
        ],
        "summary": "Run bulk actions across multiple contacts (delete, tag, untag, subscribe, unsubscribe).",
        "description": "Run bulk actions across multiple contacts (delete, tag, untag, subscribe, unsubscribe).\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The number of contacts affected.",
            "content": {
              "application/json": {
                "example": {
                  "affected": 3
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contact_ids": {
                    "type": "integer",
                    "description": "Array of contact IDs to act on."
                  },
                  "action": {
                    "type": "string",
                    "description": "The bulk action to perform."
                  },
                  "value": {
                    "type": "string",
                    "description": "Tag name or list ID depending on action."
                  }
                },
                "required": [
                  "contact_ids",
                  "action"
                ]
              }
            }
          }
        }
      }
    },
    "/contacts/import/preview": {
      "post": {
        "operationId": "postContactsImportPreview",
        "tags": [
          "Contacts"
        ],
        "summary": "Preview a CSV import to see mapping and impact before committing.",
        "description": "Preview a CSV import to see mapping and impact before committing.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "Import preview with row counts and column mapping.",
            "content": {
              "application/json": {
                "example": {
                  "total_rows": 1,
                  "new_contacts": 1,
                  "existing_contacts": 0,
                  "columns": [
                    "email",
                    "first_name"
                  ],
                  "sample_rows": [
                    [
                      "jane@example.com",
                      "Jane"
                    ]
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/import": {
      "post": {
        "operationId": "postContactsImport",
        "tags": [
          "Contacts"
        ],
        "summary": "Run a CSV import.",
        "description": "Run a CSV import. Contacts are created or updated by email match. Send consent_attested: true to confirm you have a valid legal basis to email the contacts; the request is refused without it, and the confirmation is recorded in the audit log.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "Import results with counts and any errors.",
            "content": {
              "application/json": {
                "example": {
                  "imported": 1,
                  "updated": 0,
                  "skipped": 0,
                  "errors": []
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/export": {
      "get": {
        "operationId": "getContactsExport",
        "tags": [
          "Contacts"
        ],
        "summary": "Export contacts as a CSV download.",
        "description": "Export contacts as a CSV download.\n\nRequired API key scope: contacts:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "CSV file stream."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/custom-fields": {
      "get": {
        "operationId": "getContactsCustomFields",
        "tags": [
          "Contacts"
        ],
        "summary": "List available contact custom field keys.",
        "description": "List available contact custom field keys.\n\nRequired API key scope: contacts:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of custom field key names.",
            "content": {
              "application/json": {
                "example": {
                  "fields": [
                    "favorite_city",
                    "company_size"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/{id}/gdpr": {
      "delete": {
        "operationId": "deleteContactsIdGdpr",
        "tags": [
          "Contacts"
        ],
        "summary": "Permanently delete a contact and all associated data (GDPR right to erasure).",
        "description": "Permanently delete a contact and all associated data (GDPR right to erasure). This cannot be undone.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation of permanent deletion.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Contact and all associated data permanently deleted"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/{id}/dsar-export": {
      "get": {
        "operationId": "getContactsIdDsarExport",
        "tags": [
          "Contacts"
        ],
        "summary": "Export all data held about a contact (GDPR/CCPA data subject access request).",
        "description": "Export all data held about a contact (GDPR/CCPA data subject access request).\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Complete data export for the contact."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/{id}/ccpa-opt-out": {
      "put": {
        "operationId": "putContactsIdCcpaOptOut",
        "tags": [
          "Contacts"
        ],
        "summary": "Update a contact's CCPA opt-out of sale status.",
        "description": "Update a contact's CCPA opt-out of sale status.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation with updated opt-out status.",
            "content": {
              "application/json": {
                "example": {
                  "message": "CCPA opt-out updated",
                  "opt_out_of_sale": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "opt_out_of_sale": {
                    "type": "boolean",
                    "description": "Whether the contact opts out of data sale."
                  }
                },
                "required": [
                  "opt_out_of_sale"
                ]
              }
            }
          }
        }
      }
    },
    "/contacts/recalculate-engagement-scores": {
      "post": {
        "operationId": "postContactsRecalculateEngagementScores",
        "tags": [
          "Contacts"
        ],
        "summary": "Recalculate engagement scores for all contacts using the current org rules.",
        "description": "Recalculate engagement scores for all contacts using the current org rules.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "Count of updated contacts.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Updated 1250 contacts",
                  "updated": 1250
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/segments": {
      "get": {
        "operationId": "getSegments",
        "tags": [
          "Segments"
        ],
        "summary": "List all segments with their contact counts.",
        "description": "List all segments with their contact counts.\n\nRequired API key scope: segments:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of segments with contact counts."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postSegments",
        "tags": [
          "Segments"
        ],
        "summary": "Create a new segment with a rule-based definition.",
        "description": "Create a new segment with a rule-based definition.\n\nRequired API key scope: segments:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new segment ID and initial contact count.",
            "content": {
              "application/json": {
                "example": {
                  "segment_id": 1,
                  "contact_count": 340
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Segment name. Max 255 chars."
                  },
                  "definition": {
                    "type": "object",
                    "description": "Rule definition with operator (\"and\"/\"or\") and rules array."
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        }
      }
    },
    "/segments/{id}": {
      "get": {
        "operationId": "getSegmentsId",
        "tags": [
          "Segments"
        ],
        "summary": "Fetch one segment with its matching contacts.",
        "description": "Fetch one segment with its matching contacts.\n\nRequired API key scope: segments:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Segment definition with matching contacts.",
            "content": {
              "application/json": {
                "example": {
                  "segment": {
                    "id": 1,
                    "name": "VIP customers",
                    "definition": {
                      "operator": "and",
                      "rules": [
                        {
                          "field": "tag",
                          "operator": "has_tag",
                          "value": "vip"
                        }
                      ]
                    }
                  },
                  "contacts": [
                    {
                      "id": 42,
                      "email": "jane@example.com"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "put": {
        "operationId": "putSegmentsId",
        "tags": [
          "Segments"
        ],
        "summary": "Update a segment's name and/or definition.",
        "description": "Update a segment's name and/or definition.\n\nRequired API key scope: segments:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The updated segment ID and new contact count.",
            "content": {
              "application/json": {
                "example": {
                  "segment_id": 1,
                  "contact_count": 285
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Segment name. Max 255 chars."
                  },
                  "definition": {
                    "type": "object",
                    "description": "Updated rule definition."
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteSegmentsId",
        "tags": [
          "Segments"
        ],
        "summary": "Delete a segment.",
        "description": "Delete a segment. Contacts in the segment are not affected.\n\nRequired API key scope: segments:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation of deletion.",
            "content": {
              "application/json": {
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/segments/preview": {
      "post": {
        "operationId": "postSegmentsPreview",
        "tags": [
          "Segments"
        ],
        "summary": "Preview the contact count for a segment definition without saving.",
        "description": "Preview the contact count for a segment definition without saving.\n\nRequired API key scope: segments:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The number of contacts matching the definition.",
            "content": {
              "application/json": {
                "example": {
                  "contact_count": 890
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "definition": {
                    "type": "object",
                    "description": "Segment rule definition to preview."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/campaigns": {
      "get": {
        "operationId": "getCampaigns",
        "tags": [
          "Campaigns"
        ],
        "summary": "List all campaigns in the active organization.",
        "description": "List all campaigns in the active organization.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Results per page.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by status: draft, scheduled, sending, sent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated array of campaigns."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postCampaigns",
        "tags": [
          "Campaigns"
        ],
        "summary": "Create a new campaign draft.",
        "description": "Create a new campaign draft.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new campaign ID.",
            "content": {
              "application/json": {
                "example": {
                  "campaign_id": 1
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Campaign name."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Email subject line. Supports merge tags like {{person.firstName}}."
                  },
                  "preheader": {
                    "type": "string",
                    "description": "Preview text shown in inbox."
                  },
                  "domain_id": {
                    "type": "integer",
                    "description": "Sending domain ID."
                  },
                  "from_name": {
                    "type": "string",
                    "description": "Sender display name."
                  },
                  "from_email": {
                    "type": "string",
                    "description": "Sender email address."
                  },
                  "target_list_ids": {
                    "type": "integer",
                    "description": "Target list IDs."
                  },
                  "target_segment_ids": {
                    "type": "integer",
                    "description": "Target segment IDs."
                  },
                  "exclude_segment_ids": {
                    "type": "integer",
                    "description": "Segment IDs to exclude from recipients."
                  },
                  "builder_json": {
                    "type": "object",
                    "description": "Email content as blocks (see GET /email/schema). When html_content is empty, the server renders it to HTML and plain text with the same code as the visual editor, using your brand kit. Invalid content is answered with 400 INVALID_BUILDER_JSON."
                  },
                  "render_html": {
                    "type": "boolean",
                    "description": "Set true to render builder_json again even though html_content is present."
                  },
                  "apply_brand_kit": {
                    "type": "boolean",
                    "description": "Default true. Set false to skip the brand kit when rendering."
                  },
                  "html_content": {
                    "type": "string",
                    "description": "HTML email content. Leave empty to have it rendered from builder_json."
                  },
                  "text_content": {
                    "type": "string",
                    "description": "Plain text fallback content."
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        }
      }
    },
    "/campaigns/{id}": {
      "get": {
        "operationId": "getCampaignsId",
        "tags": [
          "Campaigns"
        ],
        "summary": "Fetch a single campaign with all details.",
        "description": "Fetch a single campaign with all details.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full campaign object."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "put": {
        "operationId": "putCampaignsId",
        "tags": [
          "Campaigns"
        ],
        "summary": "Update a campaign draft.",
        "description": "Update a campaign draft. Only editable while in draft status.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The updated campaign ID.",
            "content": {
              "application/json": {
                "example": {
                  "campaign_id": 1
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Updated campaign name."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Updated subject line."
                  },
                  "preheader": {
                    "type": "string",
                    "description": "Updated preheader."
                  },
                  "html_content": {
                    "type": "string",
                    "description": "Updated HTML content."
                  },
                  "text_content": {
                    "type": "string",
                    "description": "Updated text content."
                  },
                  "target_list_ids": {
                    "type": "integer",
                    "description": "Updated target lists."
                  },
                  "exclude_segment_ids": {
                    "type": "integer",
                    "description": "Updated exclusion segments."
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteCampaignsId",
        "tags": [
          "Campaigns"
        ],
        "summary": "Delete a campaign.",
        "description": "Delete a campaign.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation of deletion.",
            "content": {
              "application/json": {
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/send": {
      "post": {
        "operationId": "postCampaignsIdSend",
        "tags": [
          "Campaigns"
        ],
        "summary": "Send a campaign immediately or schedule it for later.",
        "description": "Send a campaign immediately or schedule it for later. Requires a verified domain with a CAN-SPAM mailing address.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Confirmation with recipient count and any warnings.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Campaign queued for sending",
                  "recipients": 1250,
                  "pre_send_warnings": []
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "send_now": {
                    "type": "boolean",
                    "description": "Set true to send immediately."
                  },
                  "scheduled_at": {
                    "type": "string",
                    "description": "ISO 8601 date-time for scheduled send. Mutually exclusive with send_now."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/campaigns/{id}/reschedule": {
      "post": {
        "operationId": "postCampaignsIdReschedule",
        "tags": [
          "Campaigns"
        ],
        "summary": "Change the scheduled send time for a scheduled campaign.",
        "description": "Change the scheduled send time for a scheduled campaign.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Confirmation with new scheduled time.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Campaign rescheduled",
                  "scheduled_at": "2025-07-01T10:00:00Z"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scheduled_at": {
                    "type": "string",
                    "description": "New ISO 8601 date-time for sending."
                  }
                },
                "required": [
                  "scheduled_at"
                ]
              }
            }
          }
        }
      }
    },
    "/campaigns/{id}/cancel-schedule": {
      "post": {
        "operationId": "postCampaignsIdCancelSchedule",
        "tags": [
          "Campaigns"
        ],
        "summary": "Cancel a scheduled campaign and return it to draft status.",
        "description": "Cancel a scheduled campaign and return it to draft status.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Confirmation message.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Schedule cancelled"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/test-send": {
      "post": {
        "operationId": "postCampaignsTestSend",
        "tags": [
          "Campaigns"
        ],
        "summary": "Send a test email to one or more addresses without queuing the full campaign.",
        "description": "Send a test email to one or more addresses without queuing the full campaign.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "Confirmation message.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Test email sent"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "description": "Email address(es) to send the test to."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Subject line."
                  },
                  "html_content": {
                    "type": "string",
                    "description": "HTML content."
                  },
                  "from_name": {
                    "type": "string",
                    "description": "Sender name."
                  },
                  "from_email": {
                    "type": "string",
                    "description": "Sender email."
                  }
                },
                "required": [
                  "to",
                  "subject",
                  "html_content"
                ]
              }
            }
          }
        }
      }
    },
    "/campaigns/{id}/duplicate": {
      "post": {
        "operationId": "postCampaignsIdDuplicate",
        "tags": [
          "Campaigns"
        ],
        "summary": "Create a copy of an existing campaign as a new draft.",
        "description": "Create a copy of an existing campaign as a new draft.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The new duplicated campaign ID.",
            "content": {
              "application/json": {
                "example": {
                  "campaign_id": 2
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/stats": {
      "get": {
        "operationId": "getCampaignsIdStats",
        "tags": [
          "Campaigns"
        ],
        "summary": "Get detailed performance metrics for a sent campaign.",
        "description": "Get detailed performance metrics for a sent campaign. opens and unique_opens include every open, including automatic opens by Apple Mail Privacy Protection, the Gmail image proxy and security scanners. human_opens and proxy_opens split the total (opens = human_opens + proxy_opens), and unique_human_opens / unique_proxy_opens count recipients with at least one human / automatic open. Opens recorded before this split existed count as human. count_proxy_opens echoes the organization setting that decides whether automatic opens also feed engagement scores, open-based segments, automation triggers, A/B winners and send-time optimization (default false).\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign performance metrics.",
            "content": {
              "application/json": {
                "example": {
                  "stats": {
                    "sent": 1250,
                    "delivered": 1230,
                    "opens": 450,
                    "unique_opens": 380,
                    "human_opens": 160,
                    "proxy_opens": 290,
                    "unique_human_opens": 140,
                    "unique_proxy_opens": 250,
                    "count_proxy_opens": false,
                    "clicks": 120,
                    "unique_clicks": 95,
                    "bounces": 20,
                    "complaints": 2,
                    "unsubscribes": 8,
                    "open_rate": 0.309,
                    "click_rate": 0.077,
                    "bounce_rate": 0.016
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/stats/people": {
      "get": {
        "operationId": "getCampaignsIdStatsPeople",
        "tags": [
          "Campaigns"
        ],
        "summary": "List individual contact-level engagement data for a campaign.",
        "description": "List individual contact-level engagement data for a campaign.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Results per page.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "description": "Filter by event type: opened, clicked, bounced, etc.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of contacts with their engagement events."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/activity": {
      "get": {
        "operationId": "getCampaignsIdActivity",
        "tags": [
          "Campaigns"
        ],
        "summary": "List raw message activity events for a campaign (opens, clicks, bounces, etc.).",
        "description": "List raw message activity events for a campaign (opens, clicks, bounces, etc.).\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of activity events.",
            "content": {
              "application/json": {
                "example": {
                  "events": [
                    {
                      "type": "open",
                      "contact_id": 42,
                      "email": "jane@example.com",
                      "timestamp": "2025-06-01T10:15:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/heatmap": {
      "get": {
        "operationId": "getCampaignsIdHeatmap",
        "tags": [
          "Campaigns"
        ],
        "summary": "Get click heatmap data showing which links in the email were clicked most.",
        "description": "Get click heatmap data showing which links in the email were clicked most.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Email HTML with link-level click data.",
            "content": {
              "application/json": {
                "example": {
                  "html": "<p>Email HTML...</p>",
                  "links": [
                    {
                      "url": "https://example.com/offer",
                      "selector": "a[href*='offer']",
                      "total_clicks": 85,
                      "unique_clicks": 72,
                      "click_rate": 0.058
                    }
                  ],
                  "total_delivered": 1230
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/spam-score": {
      "post": {
        "operationId": "postCampaignsSpamScore",
        "tags": [
          "Campaigns"
        ],
        "summary": "Analyze email content for spam triggers and get a deliverability score.",
        "description": "Analyze email content for spam triggers and get a deliverability score.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "Spam score with detailed issue breakdown.",
            "content": {
              "application/json": {
                "example": {
                  "score": 7.2,
                  "verdict": "high_risk",
                  "issues": [
                    {
                      "rule": "ALL_CAPS_SUBJECT",
                      "score": 2.5,
                      "description": "Subject is all capitals"
                    },
                    {
                      "rule": "SPAM_PHRASE",
                      "score": 3,
                      "description": "Contains spam trigger words"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subject": {
                    "type": "string",
                    "description": "Email subject line to analyze."
                  },
                  "html_content": {
                    "type": "string",
                    "description": "HTML email content to analyze."
                  }
                },
                "required": [
                  "subject",
                  "html_content"
                ]
              }
            }
          }
        }
      }
    },
    "/campaigns/compare": {
      "get": {
        "operationId": "getCampaignsCompare",
        "tags": [
          "Campaigns"
        ],
        "summary": "Compare performance metrics across multiple campaigns side by side.",
        "description": "Compare performance metrics across multiple campaigns side by side.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "description": "Comma-separated campaign IDs to compare.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Comparison data for the requested campaigns.",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "campaigns": [
                      {
                        "id": 1,
                        "name": "Campaign A",
                        "open_rate": 0.32,
                        "click_rate": 0.08
                      },
                      {
                        "id": 2,
                        "name": "Campaign B",
                        "open_rate": 0.28,
                        "click_rate": 0.12
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/preview-as": {
      "post": {
        "operationId": "postCampaignsIdPreviewAs",
        "tags": [
          "Campaigns"
        ],
        "summary": "Render the campaign email as it would appear for a specific contact (with merge tags resolved).",
        "description": "Render the campaign email as it would appear for a specific contact (with merge tags resolved).\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Rendered subject and HTML with merge tags resolved.",
            "content": {
              "application/json": {
                "example": {
                  "subject": "Welcome Jane",
                  "html": "<p>Hello Jane, welcome to...</p>"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contact_id": {
                    "type": "integer",
                    "description": "Contact ID to render the preview for."
                  }
                },
                "required": [
                  "contact_id"
                ]
              }
            }
          }
        }
      }
    },
    "/automations": {
      "get": {
        "operationId": "getAutomations",
        "tags": [
          "Automations"
        ],
        "summary": "List all automations in the active organization.",
        "description": "List all automations in the active organization.\n\nRequired API key scope: automations:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of automation objects.",
            "content": {
              "application/json": {
                "example": {
                  "automations": [
                    {
                      "id": 1,
                      "name": "Welcome flow",
                      "status": "active",
                      "trigger_type": "tag_added",
                      "total_runs": 450,
                      "created_at": "2025-02-01T00:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postAutomations",
        "tags": [
          "Automations"
        ],
        "summary": "Create a new automation.",
        "description": "Create a new automation.\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new automation ID.",
            "content": {
              "application/json": {
                "example": {
                  "automation_id": 1
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Automation name."
                  },
                  "trigger_type": {
                    "type": "string",
                    "description": "Event that triggers the flow."
                  },
                  "trigger_config": {
                    "type": "object",
                    "description": "Configuration for the trigger (e.g. tag name, list ID, event_type/event_name for site_event)."
                  },
                  "graph": {
                    "type": "object",
                    "description": "Flow graph with nodes and edges arrays."
                  }
                },
                "required": [
                  "name",
                  "trigger_type"
                ]
              }
            }
          }
        }
      }
    },
    "/automations/{id}": {
      "get": {
        "operationId": "getAutomationsId",
        "tags": [
          "Automations"
        ],
        "summary": "Fetch one automation with its full flow graph.",
        "description": "Fetch one automation with its full flow graph.\n\nRequired API key scope: automations:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full automation object with flow graph.",
            "content": {
              "application/json": {
                "example": {
                  "automation": {
                    "id": 1,
                    "name": "Welcome flow",
                    "status": "active",
                    "trigger_type": "tag_added",
                    "trigger_config": {
                      "tag": "new-signup"
                    },
                    "graph": {
                      "nodes": [
                        "..."
                      ],
                      "edges": [
                        "..."
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "put": {
        "operationId": "putAutomationsId",
        "tags": [
          "Automations"
        ],
        "summary": "Update an automation's name, trigger, or flow graph.",
        "description": "Update an automation's name, trigger, or flow graph.\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The updated automation ID.",
            "content": {
              "application/json": {
                "example": {
                  "automation_id": 1
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "delete": {
        "operationId": "deleteAutomationsId",
        "tags": [
          "Automations"
        ],
        "summary": "Delete an automation.",
        "description": "Delete an automation.\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation of deletion.",
            "content": {
              "application/json": {
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/{id}/toggle-status": {
      "post": {
        "operationId": "postAutomationsIdToggleStatus",
        "tags": [
          "Automations"
        ],
        "summary": "Toggle an automation between active and paused.",
        "description": "Toggle an automation between active and paused.\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The automation ID and new status.",
            "content": {
              "application/json": {
                "example": {
                  "automation_id": 1,
                  "status": "paused"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/{id}/duplicate": {
      "post": {
        "operationId": "postAutomationsIdDuplicate",
        "tags": [
          "Automations"
        ],
        "summary": "Create a copy of an automation as a new paused automation.",
        "description": "Create a copy of an automation as a new paused automation.\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The new duplicated automation ID.",
            "content": {
              "application/json": {
                "example": {
                  "automation_id": 2
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/{id}/enroll": {
      "post": {
        "operationId": "postAutomationsIdEnroll",
        "tags": [
          "Automations"
        ],
        "summary": "Manually enroll a contact into an automation.",
        "description": "Manually enroll a contact into an automation.\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The new automation run ID.",
            "content": {
              "application/json": {
                "example": {
                  "run_id": 789
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contact_id": {
                    "type": "integer",
                    "description": "ID of the contact to enroll."
                  },
                  "payload": {
                    "type": "object",
                    "description": "Optional data to pass into the flow."
                  }
                },
                "required": [
                  "contact_id"
                ]
              }
            }
          }
        }
      }
    },
    "/automations/{id}/runs": {
      "get": {
        "operationId": "getAutomationsIdRuns",
        "tags": [
          "Automations"
        ],
        "summary": "List automation run history.",
        "description": "List automation run history.\n\nRequired API key scope: automations:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of automation runs.",
            "content": {
              "application/json": {
                "example": {
                  "runs": [
                    {
                      "id": 789,
                      "contact_id": 42,
                      "status": "completed",
                      "started_at": "2025-06-01T10:00:00Z",
                      "completed_at": "2025-06-01T10:05:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/runs/{runId}/steps": {
      "get": {
        "operationId": "getAutomationsRunsRunidSteps",
        "tags": [
          "Automations"
        ],
        "summary": "List the step execution details for one automation run.",
        "description": "List the step execution details for one automation run.\n\nRequired API key scope: automations:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of step execution records.",
            "content": {
              "application/json": {
                "example": {
                  "steps": [
                    {
                      "step_id": "node_1",
                      "type": "send_email",
                      "status": "completed",
                      "executed_at": "2025-06-01T10:00:30Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/{id}/webhook-sample": {
      "get": {
        "operationId": "getAutomationsIdWebhookSample",
        "tags": [
          "Automations"
        ],
        "summary": "Return the stored sample payload for webhook-triggered automations.",
        "description": "Return the stored sample payload for webhook-triggered automations.\n\nRequired API key scope: automations:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The stored webhook sample payload.",
            "content": {
              "application/json": {
                "example": {
                  "sample": {
                    "event": "order.completed",
                    "customer_email": "jane@example.com"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/{id}/versions": {
      "get": {
        "operationId": "getAutomationsIdVersions",
        "tags": [
          "Automations"
        ],
        "summary": "List version history for an automation.",
        "description": "List version history for an automation.\n\nRequired API key scope: automations:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of version snapshots."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/{id}/versions/{versionId}/restore": {
      "post": {
        "operationId": "postAutomationsIdVersionsRestore",
        "tags": [
          "Automations"
        ],
        "summary": "Restore an automation to a previous version.",
        "description": "Restore an automation to a previous version.\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "versionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Confirmation message.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Version restored"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/transactional/send": {
      "post": {
        "operationId": "postTransactionalSend",
        "tags": [
          "Transactional"
        ],
        "summary": "Send a single transactional email to one recipient.",
        "description": "Send a single transactional email to one recipient. The sender address always uses one of your verified sending domains. Without from_domain it uses your best verified domain (highest health score, then warm-up level); with from_domain it uses the domain you name. You cannot set an arbitrary from address.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: API key.",
        "responses": {
          "201": {
            "description": "Confirmation with the recipient address and message_id. The message_id identifies this send in webhook events (email.delivered, email.bounced, email.complained, with data.type \"transactional\"). Errors: 400 if a required field is missing or from_domain is not a string, 422 if from_domain is not a verified sending domain of your organization.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Email sent",
                  "message_id": "txm_5b1f0c2e-8a52-4c2e-9d0a-3f6d1b7c9e41",
                  "to": "jane@example.com"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "description": "Recipient email address, or a contact ID."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Email subject line. Merge tags are applied."
                  },
                  "html_body": {
                    "type": "string",
                    "description": "HTML email body. Required unless text_body is set."
                  },
                  "text_body": {
                    "type": "string",
                    "description": "Plain text body. Required unless html_body is set."
                  },
                  "from_name": {
                    "type": "string",
                    "description": "Sender display name. The address comes from your verified sending domain."
                  },
                  "from_domain": {
                    "type": "string",
                    "description": "Which of your verified sending domains to send from, for example pinsleuth.com. A leading @ and letter case are ignored. The sender is the domain's default sender local part at that domain (hello if none is set). If omitted, your best verified domain is used. Returns 422 if the domain is not a verified sending domain of your organization, and 400 if the value is not a string."
                  },
                  "reply_to": {
                    "type": "string",
                    "description": "Reply-to email address."
                  },
                  "merge_tags": {
                    "type": "object",
                    "description": "Extra values available to merge tags in the subject and body."
                  },
                  "metadata": {
                    "type": "object",
                    "description": "Custom key-value pairs attached to the send."
                  },
                  "bypass_frequency_cap": {
                    "type": "boolean",
                    "description": "Skip the frequency cap check. Defaults to false."
                  },
                  "bypass_suppression": {
                    "type": "boolean",
                    "description": "Send even if the contact is unsubscribed, bounced or globally suppressed. Logged in the audit log. Defaults to false."
                  }
                },
                "required": [
                  "to",
                  "subject"
                ]
              }
            }
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "getWebhooks",
        "tags": [
          "Webhooks"
        ],
        "summary": "List all webhook endpoints for the organization.",
        "description": "List all webhook endpoints for the organization.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of webhook endpoint objects.",
            "content": {
              "application/json": {
                "example": {
                  "webhooks": [
                    {
                      "id": 1,
                      "url": "https://example.com/webhooks/mailnaptic",
                      "events": [
                        "contact.created",
                        "email.opened"
                      ],
                      "active": true,
                      "created_at": "2025-06-01T00:00:00Z",
                      "updated_at": "2025-06-01T00:00:00Z",
                      "last_status_code": 200,
                      "last_delivery_at": "2025-06-15T10:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postWebhooks",
        "tags": [
          "Webhooks"
        ],
        "summary": "Create a new webhook endpoint.",
        "description": "Create a new webhook endpoint.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new webhook endpoint object.",
            "content": {
              "application/json": {
                "example": {
                  "webhook": {
                    "id": 1,
                    "url": "https://example.com/webhooks/mailnaptic",
                    "events": [
                      "contact.created",
                      "email.opened",
                      "email.clicked"
                    ],
                    "secret": "whsec_your_secret_here",
                    "active": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The URL to receive webhook events (http or https). URLs that resolve to private or internal addresses are rejected."
                  },
                  "events": {
                    "type": "string",
                    "description": "Array of event types to subscribe to. At least one is required."
                  },
                  "secret": {
                    "type": "string",
                    "description": "Signing secret for HMAC signatures. If omitted, a random secret is generated and returned as secret in the response."
                  }
                },
                "required": [
                  "url",
                  "events"
                ]
              }
            }
          }
        }
      }
    },
    "/webhooks/{id}": {
      "put": {
        "operationId": "putWebhooksId",
        "tags": [
          "Webhooks"
        ],
        "summary": "Update a webhook endpoint URL, events, or active status.",
        "description": "Update a webhook endpoint URL, events, or active status.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The updated webhook endpoint object.",
            "content": {
              "application/json": {
                "example": {
                  "webhook": {
                    "id": 1,
                    "url": "https://example.com/webhooks/mailnaptic",
                    "events": [
                      "contact.created",
                      "email.opened",
                      "email.clicked"
                    ],
                    "active": false
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Updated endpoint URL."
                  },
                  "events": {
                    "type": "string",
                    "description": "Updated event subscriptions."
                  },
                  "active": {
                    "type": "boolean",
                    "description": "Enable or disable the webhook."
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteWebhooksId",
        "tags": [
          "Webhooks"
        ],
        "summary": "Delete a webhook endpoint.",
        "description": "Delete a webhook endpoint.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation message.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Webhook deleted"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/webhooks/{id}/test": {
      "post": {
        "operationId": "postWebhooksIdTest",
        "tags": [
          "Webhooks"
        ],
        "summary": "Send a test event to a webhook endpoint to verify it is receiving data correctly.",
        "description": "Send a test event to a webhook endpoint to verify it is receiving data correctly.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Test delivery result with the status code, a success flag and the first 500 characters of the response body. The test sends an event named webhook.test.",
            "content": {
              "application/json": {
                "example": {
                  "status_code": 200,
                  "success": true,
                  "response_body": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/webhooks/{id}/deliveries": {
      "get": {
        "operationId": "getWebhooksIdDeliveries",
        "tags": [
          "Webhooks"
        ],
        "summary": "List recent delivery attempts for a webhook endpoint.",
        "description": "List recent delivery attempts for a webhook endpoint.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated delivery attempts (newest first) with status codes, attempt numbers, the event id, the stored request body and replayable (true when the stored body is complete and can be replayed). replay_of is set on deliveries created by a replay and points to the original delivery. Request bodies are stored up to 5000 characters; deliveries sent before event ids were introduced have no event_id and cannot be replayed.",
            "content": {
              "application/json": {
                "example": {
                  "deliveries": [
                    {
                      "id": 1,
                      "url": "https://example.com/webhooks/mailnaptic",
                      "status_code": 200,
                      "response_body": "ok",
                      "request_body": "{\"id\":\"evt_5b1f0c2e-8a52-4c2e-9d0a-3f6d1b7c9e41\",\"event\":\"contact.created\",...}",
                      "event_id": "evt_5b1f0c2e-8a52-4c2e-9d0a-3f6d1b7c9e41",
                      "event_type": "contact.created",
                      "replay_of": null,
                      "replayable": true,
                      "success": true,
                      "attempt_number": 1,
                      "created_at": "2025-06-15T10:00:00Z"
                    }
                  ],
                  "total": 1,
                  "page": 1,
                  "pageSize": 50
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/webhooks/{id}/deliveries/{deliveryId}/replay": {
      "post": {
        "operationId": "postWebhooksIdDeliveriesIdReplay",
        "tags": [
          "Webhooks"
        ],
        "summary": "Send the stored payload of a past delivery to the endpoint again.",
        "description": "Send the stored payload of a past delivery to the endpoint again. The body is identical and keeps the same event id (X-Webhook-Id), is signed again with a fresh timestamp, and carries X-Webhook-Replay: true and the next attempt number. A replay is a single attempt and is never retried automatically. It is logged as a new delivery whose replay_of points to the original delivery, and it is returned in the deliveries list.\n\nAuthentication: Owner or Admin, session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "deliveryId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The result of the replay. The response is 200 even when your endpoint answered with an error: check success and status_code. Errors: 403 for members, 404 if the webhook or delivery does not exist in your organization, 409 if the webhook is disabled, 422 if the delivery cannot be replayed (sent before event ids existed, or its payload was too large to be stored in full), 429 after 10 replays per minute.",
            "content": {
              "application/json": {
                "example": {
                  "delivery_id": 57,
                  "replay_of": 42,
                  "event_id": "evt_5b1f0c2e-8a52-4c2e-9d0a-3f6d1b7c9e41",
                  "event_type": "contact.created",
                  "attempt_number": 2,
                  "success": true,
                  "status_code": 200,
                  "blocked": false,
                  "response_body": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/scheduled-reports": {
      "get": {
        "operationId": "getScheduledReports",
        "tags": [
          "Scheduled reports"
        ],
        "summary": "List all scheduled reports for the organization.",
        "description": "List all scheduled reports for the organization.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of scheduled report objects.",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": 1,
                      "name": "Weekly digest",
                      "frequency": "weekly",
                      "recipients": [
                        "jane@example.com"
                      ],
                      "next_send_at": "2025-06-22T09:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postScheduledReports",
        "tags": [
          "Scheduled reports"
        ],
        "summary": "Create a new scheduled report.",
        "description": "Create a new scheduled report.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new report ID.",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": 1
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Report name."
                  },
                  "frequency": {
                    "type": "string",
                    "description": "Send frequency."
                  },
                  "recipients": {
                    "type": "string",
                    "description": "Email addresses to send the report to."
                  }
                },
                "required": [
                  "name",
                  "frequency",
                  "recipients"
                ]
              }
            }
          }
        }
      }
    },
    "/scheduled-reports/{id}": {
      "patch": {
        "operationId": "patchScheduledReportsId",
        "tags": [
          "Scheduled reports"
        ],
        "summary": "Update a scheduled report.",
        "description": "Update a scheduled report.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation message.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Report updated"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Updated name."
                  },
                  "frequency": {
                    "type": "string",
                    "description": "Updated frequency."
                  },
                  "recipients": {
                    "type": "string",
                    "description": "Updated recipients."
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteScheduledReportsId",
        "tags": [
          "Scheduled reports"
        ],
        "summary": "Delete a scheduled report.",
        "description": "Delete a scheduled report.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation message.",
            "content": {
              "application/json": {
                "example": {
                  "message": "Report deleted"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/email/schema": {
      "get": {
        "operationId": "getEmailSchema",
        "tags": [
          "Email design"
        ],
        "summary": "Every block type and property the renderer understands, the available fonts, the text presets and the preview modes.",
        "description": "Every block type and property the renderer understands, the available fonts, the text presets and the preview modes. Use it to build or validate builder_json.\n\nRequired API key scope: templates:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "The block catalog (block_types, common_properties, fonts, text_presets, preview_modes, merge_tags).",
            "content": {
              "application/json": {
                "example": {
                  "renderer_version": 2,
                  "block_types": {
                    "section": {
                      "description": "A coloured, padded, rounded band that contains other blocks",
                      "properties": [
                        {
                          "name": "children",
                          "type": "array of blocks",
                          "description": "Any block type."
                        }
                      ]
                    },
                    "feature_grid": {
                      "description": "Cards in 1-3 columns",
                      "properties": [
                        "..."
                      ]
                    }
                  },
                  "fonts": [
                    {
                      "name": "Inter",
                      "web_font": true,
                      "stack": "Inter, ..."
                    }
                  ],
                  "text_presets": {
                    "eyebrow": {
                      "font_size": 12,
                      "text_transform": "uppercase"
                    }
                  },
                  "preview_modes": {
                    "desktop": {
                      "width": 640
                    },
                    "mobile": {
                      "width": 375
                    },
                    "dark": {
                      "width": 640
                    },
                    "dark-mobile": {
                      "width": 375
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/email/render": {
      "post": {
        "operationId": "postEmailRender",
        "tags": [
          "Email design"
        ],
        "summary": "Render builder JSON to HTML and plain text without saving anything.",
        "description": "Render builder JSON to HTML and plain text without saving anything. Optionally returns ready-to-open previews in desktop, mobile, dark and dark-mobile for a sample contact. The account footer (organization name, mailing address) comes from the sending domain, and the brand kit is applied unless you turn it off. Limited to 60 requests per minute.\n\nRequired API key scope: templates:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "html, text, warnings (for example padding_mode \"all\" with differing sides), the web fonts used, and previews when modes is set. Responds 400 with code INVALID_BUILDER_JSON and an errors list ({ path, message }) when the content is not valid, such as an unknown block type or contradicting padding settings.",
            "content": {
              "application/json": {
                "example": {
                  "html": "<!doctype html>...",
                  "text": "Scheduling is here\nTry it https://app.example.com\n...",
                  "warnings": [],
                  "fonts": [
                    "Arial"
                  ],
                  "renderer_version": 2,
                  "previews": [
                    {
                      "mode": "mobile",
                      "width": 375,
                      "dark": false,
                      "mobile": true,
                      "html": "<!doctype html>..."
                    },
                    {
                      "mode": "dark",
                      "width": 640,
                      "dark": true,
                      "mobile": false,
                      "html": "<!doctype html>..."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "builder_json": {
                    "type": "object",
                    "description": "The email: { blocks, body_settings, link_settings, web_view_settings, footer }. See GET /email/schema."
                  },
                  "domain_id": {
                    "type": "integer",
                    "description": "Sending domain used for the footer details."
                  },
                  "from_email": {
                    "type": "string",
                    "description": "Shown in the footer."
                  },
                  "apply_brand_kit": {
                    "type": "boolean",
                    "description": "Default true. Set false to render without your brand kit."
                  },
                  "modes": {
                    "type": "string",
                    "description": "Previews to return: desktop, mobile, dark, dark-mobile."
                  },
                  "sample": {
                    "type": "object",
                    "description": "Sample contact for the previews: { first_name, last_name, email, custom_fields, tags }. Merge tags with fallbacks, such as {{first_name|there}}, use it."
                  }
                },
                "required": [
                  "builder_json"
                ]
              }
            }
          }
        }
      }
    },
    "/campaigns/{id}/preview": {
      "post": {
        "operationId": "postCampaignsIdPreview",
        "tags": [
          "Email design"
        ],
        "summary": "Preview a campaign as a recipient would see it, in desktop, mobile, dark and dark-mobile, for a real contact or a sample one.",
        "description": "Preview a campaign as a recipient would see it, in desktop, mobile, dark and dark-mobile, for a real contact or a sample one. Merge tags, fallbacks and conditional blocks are resolved. Each preview is a complete HTML document: open it in a browser or screenshot it at the given width. Media queries and dark mode are forced on or off in the document, so the window size and system theme do not matter.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The personalized subject and preheader and one preview document per requested mode. Responds 404 when the campaign or contact is not found.",
            "content": {
              "application/json": {
                "example": {
                  "campaign_id": 12,
                  "subject": "Hi Maya, what is new this month",
                  "preheader": "A short look",
                  "contact": {
                    "first_name": "Maya",
                    "last_name": "Taylor",
                    "email": "alex@example.com"
                  },
                  "previews": [
                    {
                      "mode": "mobile",
                      "width": 375,
                      "dark": false,
                      "mobile": true,
                      "html": "<!doctype html>..."
                    },
                    {
                      "mode": "dark",
                      "width": 640,
                      "dark": true,
                      "mobile": false,
                      "html": "<!doctype html>..."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "modes": {
                    "type": "string",
                    "description": "Default [\"desktop\"]."
                  },
                  "contact_id": {
                    "type": "integer",
                    "description": "Preview as this contact."
                  },
                  "sample": {
                    "type": "object",
                    "description": "Sample contact when contact_id is not given."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/organization/template-library/{id}/render": {
      "post": {
        "operationId": "postOrganizationTemplateLibraryIdRender",
        "tags": [
          "Email design"
        ],
        "summary": "Render a saved template to HTML and text, with optional previews (same options as POST /email/render).",
        "description": "Render a saved template to HTML and text, with optional previews (same options as POST /email/render).\n\nRequired API key scope: templates:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The rendered template. Responds 404 when the template is not found and 400 INVALID_BUILDER_JSON when its content is invalid.",
            "content": {
              "application/json": {
                "example": {
                  "template_id": 3,
                  "subject": "Welcome",
                  "preheader": "",
                  "html": "<!doctype html>...",
                  "text": "...",
                  "warnings": [],
                  "previews": [
                    {
                      "mode": "desktop",
                      "width": 640,
                      "html": "..."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "modes": {
                    "type": "string",
                    "description": "Previews to return."
                  },
                  "sample": {
                    "type": "object",
                    "description": "Sample contact for the previews."
                  },
                  "domain_id": {
                    "type": "integer",
                    "description": "Sending domain used for the footer details."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/organization/brand-kit": {
      "get": {
        "operationId": "getOrganizationBrandKit",
        "tags": [
          "Email design"
        ],
        "summary": "Read a brand kit: logo, colours, fonts, button style, default dark mode and optional header blocks.",
        "description": "Read a brand kit: logo, colours, fonts, button style, default dark mode and optional header blocks. Every email that does not set its own values uses the kit, and blocks can refer to its colours as brand:primary, brand:secondary, brand:accent, brand:text, brand:background and brand:link. There is one account default and, optionally, one kit per sending domain (pass domain_id) for organizations that run several brands. Emails sent from a domain use its own kit, or the account default when it has none.\n\nRequired API key scope: organization:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "domain_id",
            "in": "query",
            "required": false,
            "description": "Work with the kit of one sending domain instead of the account default. A domain without its own kit uses the account default.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "brand_kit is null until one is saved for that scope. For a domain without its own kit, inherited is true and effective shows the account default. domain_kits lists the domains that have their own kit, and fonts lists the fonts you can use. Responds 404 for a domain that is not yours.",
            "content": {
              "application/json": {
                "example": {
                  "scope": "account",
                  "domain_id": null,
                  "inherited": false,
                  "domain_kits": [
                    7
                  ],
                  "brand_kit": {
                    "logo_url": "https://app.example.com/uploads/logo.png",
                    "colors": {
                      "primary": "#6d28d9",
                      "secondary": "#0f172a"
                    },
                    "fonts": {
                      "heading": "Poppins",
                      "body": "Inter"
                    },
                    "button": {
                      "border_radius": 12
                    },
                    "dark_mode": "auto"
                  },
                  "effective": {
                    "...": "the kit with the default logo header filled in"
                  },
                  "updated_at": "2026-10-14 10:00:00",
                  "fonts": [
                    {
                      "name": "Inter",
                      "web_font": true
                    }
                  ],
                  "text_presets": [
                    "eyebrow",
                    "label",
                    "heading_xl"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "put": {
        "operationId": "putOrganizationBrandKit",
        "tags": [
          "Email design"
        ],
        "summary": "Save a brand kit (replaces the previous one of that scope).",
        "description": "Save a brand kit (replaces the previous one of that scope). Only owners and admins can change it. The change is recorded in the audit log. Pass domain_id to save the kit of one sending domain instead of the account default.\n\nRequired API key scope: organization:write.\n\nAuthentication: Owner or Admin; session or API key.",
        "parameters": [
          {
            "name": "domain_id",
            "in": "query",
            "required": false,
            "description": "Work with the kit of one sending domain instead of the account default. A domain without its own kit uses the account default.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The saved kit. Responds 400 with code INVALID_BRAND_KIT and an errors list when a value is not valid, and 403 for members.",
            "content": {
              "application/json": {
                "example": {
                  "brand_kit": {
                    "logo_url": "...",
                    "colors": {
                      "primary": "#6d28d9"
                    }
                  },
                  "effective": {
                    "...": "..."
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "logo_url": {
                    "type": "string",
                    "description": "Logo address, for example from POST /organization/media."
                  },
                  "logo_width": {
                    "type": "integer",
                    "description": "Logo width in pixels (20 to 600)."
                  },
                  "colors": {
                    "type": "object",
                    "description": "primary, secondary, accent, text, background, link as hex colours."
                  },
                  "fonts": {
                    "type": "object",
                    "description": "heading and body font names from GET /email/schema."
                  },
                  "button": {
                    "type": "object",
                    "description": "background_color, text_color, border_color, border_radius, padding_x, padding_y, font_size, font_weight."
                  },
                  "presets": {
                    "type": "object",
                    "description": "Your own named text styles, or overrides of the built-in ones such as eyebrow."
                  },
                  "dark_mode": {
                    "type": "string",
                    "description": "\"auto\" (default) or \"off\" to keep your colours in dark mode."
                  },
                  "header_blocks": {
                    "type": "object",
                    "description": "Blocks placed at the top of every email that has no header of its own. Defaults to your logo."
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteOrganizationBrandKit",
        "tags": [
          "Email design"
        ],
        "summary": "Remove a brand kit.",
        "description": "Remove a brand kit. Emails already saved keep their rendered HTML; new ones use the account default, or the built-in defaults. Pass domain_id to remove only the kit of one sending domain.\n\nRequired API key scope: organization:write.\n\nAuthentication: Owner or Admin; session or API key.",
        "parameters": [
          {
            "name": "domain_id",
            "in": "query",
            "required": false,
            "description": "Work with the kit of one sending domain instead of the account default. A domain without its own kit uses the account default.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "removed is false when there was no kit.",
            "content": {
              "application/json": {
                "example": {
                  "removed": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/email/starter-templates": {
      "get": {
        "operationId": "getEmailStarterTemplates",
        "tags": [
          "Email design"
        ],
        "summary": "SaaS starter templates: product update, welcome, onboarding sequence (four emails over ten days) and changelog digest.",
        "description": "SaaS starter templates: product update, welcome, onboarding sequence (four emails over ten days) and changelog digest. They use brand colours, so they follow your brand kit.\n\nRequired API key scope: templates:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "The list. Sequences carry their steps with a suggested delay in days.",
            "content": {
              "application/json": {
                "example": {
                  "templates": [
                    {
                      "slug": "saas-welcome",
                      "name": "Welcome",
                      "category": "saas",
                      "kind": "single",
                      "description": "...",
                      "preview_subject": "Welcome to [Product], {{first_name|there}}"
                    },
                    {
                      "slug": "saas-onboarding-sequence",
                      "kind": "sequence",
                      "steps": [
                        {
                          "day": 0,
                          "name": "Day 0 · Welcome",
                          "subject": "..."
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/email/starter-templates/{slug}": {
      "get": {
        "operationId": "getEmailStarterTemplatesSlug",
        "tags": [
          "Email design"
        ],
        "summary": "One starter template with its full builder JSON (a sequence has builder_json per step).",
        "description": "One starter template with its full builder JSON (a sequence has builder_json per step).\n\nRequired API key scope: templates:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The template. Responds 404 for an unknown slug.",
            "content": {
              "application/json": {
                "example": {
                  "template": {
                    "slug": "saas-welcome",
                    "name": "Welcome",
                    "builder_json": {
                      "blocks": [
                        "..."
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/email/starter-templates/{slug}/use": {
      "post": {
        "operationId": "postEmailStarterTemplatesSlugUse",
        "tags": [
          "Email design"
        ],
        "summary": "Save a starter template to your template library (a sequence is saved as one template per email).",
        "description": "Save a starter template to your template library (a sequence is saved as one template per email). Edit it afterwards, or use it for a campaign or an automation email.\n\nRequired API key scope: templates:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The saved templates and, for sequences, the suggested delay (day) of each.",
            "content": {
              "application/json": {
                "example": {
                  "templates": [
                    {
                      "template_id": 11,
                      "name": "Onboarding · Day 0 · Welcome",
                      "subject": "Welcome to [Product], {{first_name|there}}",
                      "day": 0
                    }
                  ],
                  "message": "Sequence saved as templates. Create an automation with a delay between the emails and pick each template."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Name for the saved template. Defaults to the starter name."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/email/starter-templates/{slug}/automation": {
      "post": {
        "operationId": "postEmailStarterTemplatesSlugAutomation",
        "tags": [
          "Email design"
        ],
        "summary": "Create a draft automation from a sequence starter such as saas-onboarding-sequence: one email step per email, with the waiting time between them (for example 2,",
        "description": "Create a draft automation from a sequence starter such as saas-onboarding-sequence: one email step per email, with the waiting time between them (for example 2, 3 and 5 days). The emails are rendered on the server with your brand kit. The automation stays a draft: open it in the app to check the trigger and activate it. Only owners and admins can create automations, and your plan limits for automations, steps and triggers apply. Limited to 10 requests per minute.\n\nRequired API key scope: automations:write.\n\nAuthentication: Owner or Admin; session or API key.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The new automation ID. Responds 400 for a single-email starter (use /use instead) or missing fields, 404 for an unknown starter or domain, and 402 or 403 when a plan limit or role stops it.",
            "content": {
              "application/json": {
                "example": {
                  "automation_id": 21,
                  "status": "draft",
                  "steps": [
                    {
                      "day": 0,
                      "name": "Day 0 · Welcome",
                      "subject": "Welcome to [Product], {{first_name|there}}"
                    },
                    {
                      "day": 2,
                      "name": "Day 2 · First success",
                      "subject": "Did you get [the key first action] done?"
                    }
                  ],
                  "message": "Draft automation created. Open it in the app to choose the trigger details and activate it."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain_id": {
                    "type": "integer",
                    "description": "Sending domain of the emails."
                  },
                  "from_email": {
                    "type": "string",
                    "description": "Sender address of the emails."
                  },
                  "from_name": {
                    "type": "string",
                    "description": "Sender name."
                  },
                  "name": {
                    "type": "string",
                    "description": "Name of the automation. Defaults to the starter name."
                  },
                  "trigger_type": {
                    "type": "string",
                    "description": "Default contact_created."
                  },
                  "trigger_config": {
                    "type": "object",
                    "description": "Settings for the trigger, for example the list."
                  }
                },
                "required": [
                  "domain_id",
                  "from_email"
                ]
              }
            }
          }
        }
      }
    },
    "/organization/media": {
      "get": {
        "operationId": "getOrganizationMedia",
        "tags": [
          "Email design"
        ],
        "summary": "List the images in your media library, newest first, with their size so image blocks can set width and height (Outlook needs both).",
        "description": "List the images in your media library, newest first, with their size so image blocks can set width and height (Outlook needs both).\n\nRequired API key scope: templates:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of files with url, mime, bytes, width and height.",
            "content": {
              "application/json": {
                "example": {
                  "files": [
                    {
                      "filename": "5_ab12cd.png",
                      "url": "https://app.example.com/uploads/5_ab12cd.png",
                      "mime": "image/png",
                      "bytes": 48213,
                      "width": 1200,
                      "height": 630,
                      "uploaded_at": "2026-10-14T09:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postOrganizationMedia",
        "tags": [
          "Email design"
        ],
        "summary": "Upload an image (JPEG, PNG, GIF or WebP, up to 10 MB) as multipart form data in the field \"file\".",
        "description": "Upload an image (JPEG, PNG, GIF or WebP, up to 10 MB) as multipart form data in the field \"file\". The result has the public url and the pixel size: use them in an image or logo block (url, natural_width, natural_height). Limited to 60 uploads per minute.\n\nRequired API key scope: templates:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The url, filename and pixel size of the stored image. Responds 415 for unsupported files.",
            "content": {
              "application/json": {
                "example": {
                  "url": "https://app.example.com/uploads/5_ab12cd.png",
                  "filename": "5_ab12cd.png",
                  "width": 600,
                  "height": 160
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/template-library": {
      "get": {
        "operationId": "getOrganizationTemplateLibrary",
        "tags": [
          "Templates"
        ],
        "summary": "List saved email templates.",
        "description": "List saved email templates.\n\nRequired API key scope: templates:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of template objects.",
            "content": {
              "application/json": {
                "example": {
                  "templates": [
                    {
                      "id": 1,
                      "name": "Monthly newsletter",
                      "subject": "Monthly update",
                      "created_at": "2025-03-01T00:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postOrganizationTemplateLibrary",
        "tags": [
          "Templates"
        ],
        "summary": "Save a new email template.",
        "description": "Save a new email template.\n\nRequired API key scope: templates:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new template object.",
            "content": {
              "application/json": {
                "example": {
                  "template": {
                    "id": 1,
                    "name": "Monthly newsletter"
                  },
                  "message": "Template saved"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Template name. Max 120 chars."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Default subject. Max 500 chars."
                  },
                  "preheader": {
                    "type": "string",
                    "description": "Default preheader. Max 500 chars."
                  },
                  "builder_json": {
                    "type": "object",
                    "description": "Visual builder state object."
                  }
                },
                "required": [
                  "name",
                  "builder_json"
                ]
              }
            }
          }
        }
      }
    },
    "/organization/template-library/{id}": {
      "get": {
        "operationId": "getOrganizationTemplateLibraryId",
        "tags": [
          "Templates"
        ],
        "summary": "Fetch a single template with full builder JSON.",
        "description": "Fetch a single template with full builder JSON.\n\nRequired API key scope: templates:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full template object."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "delete": {
        "operationId": "deleteOrganizationTemplateLibraryId",
        "tags": [
          "Templates"
        ],
        "summary": "Delete a saved template.",
        "description": "Delete a saved template.\n\nRequired API key scope: templates:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation of removal.",
            "content": {
              "application/json": {
                "example": {
                  "removed": true,
                  "message": "Template removed"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/organization/block-library": {
      "get": {
        "operationId": "getOrganizationBlockLibrary",
        "tags": [
          "Templates"
        ],
        "summary": "List saved email blocks (reusable content sections).",
        "description": "List saved email blocks (reusable content sections).\n\nRequired API key scope: templates:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of saved block objects."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postOrganizationBlockLibrary",
        "tags": [
          "Templates"
        ],
        "summary": "Save a new email block.",
        "description": "Save a new email block.\n\nRequired API key scope: templates:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "The new block object.",
            "content": {
              "application/json": {
                "example": {
                  "block": {
                    "id": 1,
                    "name": "CTA button section"
                  },
                  "message": "Block saved"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Block name. Max 120 chars."
                  },
                  "block": {
                    "type": "object",
                    "description": "Block content object from the visual builder."
                  }
                },
                "required": [
                  "name",
                  "block"
                ]
              }
            }
          }
        }
      }
    },
    "/organization/block-library/{id}": {
      "delete": {
        "operationId": "deleteOrganizationBlockLibraryId",
        "tags": [
          "Templates"
        ],
        "summary": "Delete a saved block.",
        "description": "Delete a saved block.\n\nRequired API key scope: templates:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation of removal.",
            "content": {
              "application/json": {
                "example": {
                  "removed": true,
                  "message": "Block removed"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automation-templates": {
      "get": {
        "operationId": "getAutomationTemplates",
        "tags": [
          "Templates"
        ],
        "summary": "List pre-built automation templates.",
        "description": "List pre-built automation templates.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Array of automation template objects.",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": 1,
                      "name": "Welcome series",
                      "description": "3-email onboarding flow",
                      "trigger_type": "tag_added"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automation-templates/{id}": {
      "get": {
        "operationId": "getAutomationTemplatesId",
        "tags": [
          "Templates"
        ],
        "summary": "Get a single automation template with the full flow graph.",
        "description": "Get a single automation template with the full flow graph.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full automation template object.",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": 1,
                    "name": "Welcome series",
                    "graph": {
                      "nodes": [],
                      "edges": []
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/predictive/contacts/{id}": {
      "get": {
        "operationId": "getPredictiveContactsId",
        "tags": [
          "Predictive"
        ],
        "summary": "Get engagement predictions for a specific contact.",
        "description": "Get engagement predictions for a specific contact.\n\nRequired API key scope: contacts:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contact-level engagement predictions.",
            "content": {
              "application/json": {
                "example": {
                  "predictions": {
                    "churn_risk": 0.15,
                    "engagement_trend": "rising",
                    "predicted_open_rate": 0.45,
                    "recommended_frequency": "weekly"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/predictive/campaigns/{id}": {
      "get": {
        "operationId": "getPredictiveCampaignsId",
        "tags": [
          "Predictive"
        ],
        "summary": "Get performance predictions for a campaign before sending.",
        "description": "Get performance predictions for a campaign before sending.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign performance predictions.",
            "content": {
              "application/json": {
                "example": {
                  "predictions": {
                    "estimated_open_rate": 0.32,
                    "estimated_click_rate": 0.08,
                    "estimated_unsubscribe_rate": 0.002,
                    "send_time_suggestion": "2025-06-16T10:00:00Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/predictive/insights": {
      "get": {
        "operationId": "getPredictiveInsights",
        "tags": [
          "Predictive"
        ],
        "summary": "Get organization-wide predictive insights and trends.",
        "description": "Get organization-wide predictive insights and trends.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Organization-level predictive insights. Churn risk covers only active contacts with at least min_sends campaign sends; the rest are counted in not_enough_data. High plus critical equals at_risk_count.",
            "content": {
              "application/json": {
                "example": {
                  "insights": {
                    "send_time_heatmap": [
                      {
                        "hour_utc": 14,
                        "day_of_week": 2,
                        "opens": 310
                      }
                    ],
                    "churn_risk_distribution": {
                      "low": 820,
                      "medium": 244,
                      "high": 56,
                      "critical": 16
                    },
                    "churn_risk": {
                      "scored_contacts": 1136,
                      "total_active": 3228,
                      "not_enough_data": 2092,
                      "min_sends": 3,
                      "at_risk_threshold": 0.5,
                      "at_risk_count": 72,
                      "at_risk_pct_of_scored": 6.3
                    },
                    "engagement_trend": {
                      "trend": "stable",
                      "current_open_rate": 0.31,
                      "previous_open_rate": 0.3
                    },
                    "predicted_next_campaign": {
                      "estimated_audience": 3228,
                      "predicted_unsubscribes": 18,
                      "unsubscribe_rate": 0.0054,
                      "basis_days": 90,
                      "basis_sent": 6333,
                      "basis_unsubscribes": 34
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/predictive/contacts/{id}/send-time": {
      "get": {
        "operationId": "getPredictiveContactsIdSendTime",
        "tags": [
          "Predictive"
        ],
        "summary": "Get the optimal send time for a specific contact based on their engagement history.",
        "description": "Get the optimal send time for a specific contact based on their engagement history.\n\nRequired API key scope: contacts:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Optimal send time prediction with confidence.",
            "content": {
              "application/json": {
                "example": {
                  "send_time": {
                    "optimal_hour_utc": 14,
                    "optimal_day": "tuesday",
                    "timezone": "Europe/Copenhagen",
                    "confidence": 0.82
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/dashboard/overview": {
      "get": {
        "operationId": "getDashboardOverview",
        "tags": [
          "Dashboard"
        ],
        "summary": "Get dashboard KPI summary including contacts, campaigns, and deliverability metrics.",
        "description": "Get dashboard KPI summary including contacts, campaigns, and deliverability metrics.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Dashboard overview metrics.",
            "content": {
              "application/json": {
                "example": {
                  "overview": {
                    "total_contacts": 5200,
                    "subscribed": 4800,
                    "campaigns_sent": 24,
                    "open_rate_avg": 0.32,
                    "click_rate_avg": 0.08
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/onboarding/checklist": {
      "get": {
        "operationId": "getOnboardingChecklist",
        "tags": [
          "Dashboard"
        ],
        "summary": "Get onboarding checklist state for guiding new users.",
        "description": "Get onboarding checklist state for guiding new users.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Onboarding checklist state.",
            "content": {
              "application/json": {
                "example": {
                  "checklist": {
                    "domain_verified": true,
                    "contact_added": true,
                    "list_created": true,
                    "campaign_sent": false
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/labels": {
      "get": {
        "operationId": "getLabels",
        "tags": [
          "Workflow"
        ],
        "summary": "List labels with the number of campaigns and automations that use each.",
        "description": "List labels with the number of campaigns and automations that use each.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "labels: id, name, color, campaign_count, automation_count.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postLabels",
        "tags": [
          "Workflow"
        ],
        "summary": "Create a label (name up to 60 characters, optional #rrggbb color).",
        "description": "Create a label (name up to 60 characters, optional #rrggbb color).\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "201 with the label. 400 INVALID_NAME, INVALID_COLOR or LIMIT, 409 DUPLICATE.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/labels/{id}": {
      "patch": {
        "operationId": "patchLabelsId",
        "tags": [
          "Workflow"
        ],
        "summary": "Rename or recolour a label.",
        "description": "Rename or recolour a label.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The label. 404 NOT_FOUND, 409 DUPLICATE.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "delete": {
        "operationId": "deleteLabelsId",
        "tags": [
          "Workflow"
        ],
        "summary": "Delete a label and remove it from every campaign and automation.",
        "description": "Delete a label and remove it from every campaign and automation.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/labels": {
      "put": {
        "operationId": "putCampaignsIdLabels",
        "tags": [
          "Workflow"
        ],
        "summary": "Replace the labels of a campaign (up to 20).",
        "description": "Replace the labels of a campaign (up to 20).\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "labels. 422 UNKNOWN_LABEL, 400 TOO_MANY.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/labels/bulk": {
      "post": {
        "operationId": "postCampaignsLabelsBulk",
        "tags": [
          "Workflow"
        ],
        "summary": "Add or remove labels on up to 100 campaigns.",
        "description": "Add or remove labels on up to 100 campaigns.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "updated and skipped counts.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/{id}/labels": {
      "put": {
        "operationId": "putAutomationsIdLabels",
        "tags": [
          "Workflow"
        ],
        "summary": "Replace the labels of an automation (owner and admin only).",
        "description": "Replace the labels of an automation (owner and admin only).\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "labels.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/labels/bulk": {
      "post": {
        "operationId": "postAutomationsLabelsBulk",
        "tags": [
          "Workflow"
        ],
        "summary": "Add or remove labels on up to 100 automations (owner and admin only).",
        "description": "Add or remove labels on up to 100 automations (owner and admin only).\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "updated and skipped counts.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/pause": {
      "post": {
        "operationId": "postCampaignsIdPause",
        "tags": [
          "Workflow"
        ],
        "summary": "Pause a queued or sending campaign.",
        "description": "Pause a queued or sending campaign. Repeating the call answers 200 with changed: false.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "{ campaign_id, status, changed }. 409 INVALID_STATE with current_status. Fires the campaign.paused webhook.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/resume": {
      "post": {
        "operationId": "postCampaignsIdResume",
        "tags": [
          "Workflow"
        ],
        "summary": "Resume a paused campaign.",
        "description": "Resume a paused campaign.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "{ campaign_id, status, changed }. Fires the campaign.resumed webhook.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/cancel": {
      "post": {
        "operationId": "postCampaignsIdCancel",
        "tags": [
          "Workflow"
        ],
        "summary": "Cancel a paused campaign.",
        "description": "Cancel a paused campaign. Pending recipients are archived.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "{ campaign_id, status, changed }. 409 INVALID_STATE.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/resend/preview": {
      "get": {
        "operationId": "getCampaignsIdResendPreview",
        "tags": [
          "Workflow"
        ],
        "summary": "Check whether a sent campaign can be resent to non-openers or non-clickers and how many contacts that is.",
        "description": "Check whether a sent campaign can be resent to non-openers or non-clickers and how many contacts that is.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ eligible, code, audience, audience_size, eligible_at, existing_campaign_id }. Only human opens count as opened.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/resend": {
      "post": {
        "operationId": "postCampaignsIdResend",
        "tags": [
          "Workflow"
        ],
        "summary": "Create a resend to non-openers (default) or non-clickers of a sent campaign.",
        "description": "Create a resend to non-openers (default) or non-clickers of a sent campaign.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "201 { campaign_id, resend_of_campaign_id, audience, recipients, status, scheduled_at }. Errors: 409 CAMPAIGN_NOT_SENT, WAIT_NOT_ELAPSED (eligible_at), ALREADY_RESENT (existing_campaign_id), 422 EMPTY_AUDIENCE.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/versions": {
      "get": {
        "operationId": "getCampaignsIdVersions",
        "tags": [
          "Workflow"
        ],
        "summary": "List saved versions of a campaign.",
        "description": "List saved versions of a campaign.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "versions: id, subject, size_bytes, reason, created_by_name, created_at.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/versions/{versionId}": {
      "get": {
        "operationId": "getCampaignsIdVersionsVersionid",
        "tags": [
          "Workflow"
        ],
        "summary": "One version including its snapshot.",
        "description": "One version including its snapshot.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "versionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "version with snapshot.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/versions/{versionId}/restore": {
      "post": {
        "operationId": "postCampaignsIdVersionsVersionidRestore",
        "tags": [
          "Workflow"
        ],
        "summary": "Restore a version.",
        "description": "Restore a version. Only draft or scheduled campaigns; the current content is saved as a backup version first.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "versionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "{ campaign_id, restored_version_id, backup_version_id }. 409 CAMPAIGN_NOT_EDITABLE.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/variants": {
      "get": {
        "operationId": "getCampaignsIdVariants",
        "tags": [
          "Workflow"
        ],
        "summary": "Language variants of a campaign and its default locale.",
        "description": "Language variants of a campaign and its default locale.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ default_locale, variants }.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/variants/{locale}": {
      "put": {
        "operationId": "putCampaignsIdVariantsLocale",
        "tags": [
          "Workflow"
        ],
        "summary": "Create or replace a language variant (subject, preheader, content).",
        "description": "Create or replace a language variant (subject, preheader, content). Editable campaigns only.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "locale",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "201 when created, 200 when updated.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "delete": {
        "operationId": "deleteCampaignsIdVariantsLocale",
        "tags": [
          "Workflow"
        ],
        "summary": "Remove a language variant.",
        "description": "Remove a language variant.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "locale",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmation.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/default-locale": {
      "put": {
        "operationId": "putCampaignsIdDefaultLocale",
        "tags": [
          "Workflow"
        ],
        "summary": "Set the locale of the campaign content itself.",
        "description": "Set the locale of the campaign content itself.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "default_locale.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/comments": {
      "get": {
        "operationId": "getCampaignsIdComments",
        "tags": [
          "Workflow"
        ],
        "summary": "Comments on a campaign.",
        "description": "Comments on a campaign.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "comments with author and time.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postCampaignsIdComments",
        "tags": [
          "Workflow"
        ],
        "summary": "Add a comment (up to 2000 characters).",
        "description": "Add a comment (up to 2000 characters).\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The comment.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaign-approvals": {
      "get": {
        "operationId": "getCampaignApprovals",
        "tags": [
          "Workflow"
        ],
        "summary": "List approval requests.",
        "description": "List approval requests. Owners and admins see all, members their own.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "Paginated approvals with status pending, approved, rejected or cancelled.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaign-approvals/{id}/approve": {
      "post": {
        "operationId": "postCampaignApprovalsIdApprove",
        "tags": [
          "Workflow"
        ],
        "summary": "Approve and run the stored send or schedule request.",
        "description": "Approve and run the stored send or schedule request.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The approval. A refused send leaves it pending and returns the error. 409 NOT_PENDING.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaign-approvals/{id}/reject": {
      "post": {
        "operationId": "postCampaignApprovalsIdReject",
        "tags": [
          "Workflow"
        ],
        "summary": "Reject a request.",
        "description": "Reject a request. A note is required.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The approval. 400 NOTE_REQUIRED.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaign-approvals/{id}/cancel": {
      "post": {
        "operationId": "postCampaignApprovalsIdCancel",
        "tags": [
          "Workflow"
        ],
        "summary": "The requester withdraws a pending request.",
        "description": "The requester withdraws a pending request.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The approval.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/trash": {
      "get": {
        "operationId": "getTrash",
        "tags": [
          "Workflow"
        ],
        "summary": "Deleted campaigns, automations, segments and lists that can still be restored.",
        "description": "Deleted campaigns, automations, segments and lists that can still be restored.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "items: type, id, name, deleted_at, purge_at; total; retention_days (30).",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/{id}/restore": {
      "post": {
        "operationId": "postCampaignsIdRestore",
        "tags": [
          "Workflow"
        ],
        "summary": "Restore a deleted campaign (never back to sending or scheduled).",
        "description": "Restore a deleted campaign (never back to sending or scheduled). The same route exists for /automations, /lists and /segments (automations return paused).\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "{ id, type, name, restored }.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/campaigns/bulk": {
      "post": {
        "operationId": "postCampaignsBulk",
        "tags": [
          "Workflow"
        ],
        "summary": "Delete, restore, duplicate, archive or unarchive up to 100 campaigns.",
        "description": "Delete, restore, duplicate, archive or unarchive up to 100 campaigns. The same route exists for /automations, /lists and /segments.\n\nRequired API key scope: campaigns:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "results: id, ok, code, new_id per id, and a summary.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/analytics/send-time-comparison": {
      "get": {
        "operationId": "getAnalyticsSendTimeComparison",
        "tags": [
          "Workflow"
        ],
        "summary": "Open rate of campaigns with send-time optimisation against campaigns sent at a fixed time, with a two-proportion z-test.",
        "description": "Open rate of campaigns with send-time optimisation against campaigns sent at a fixed time, with a two-proportion z-test. Indicative only.\n\nRequired API key scope: campaigns:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "{ optimised, fixed, comparison }.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/automations/{id}/holdout": {
      "put": {
        "operationId": "putAutomationsIdHoldout",
        "tags": [
          "Workflow"
        ],
        "summary": "Keep 0 to 50 percent of new contacts out of an automation to measure its effect.",
        "description": "Keep 0 to 50 percent of new contacts out of an automation to measure its effect.\n\nRequired API key scope: automations:write.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "holdout_percent.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "get": {
        "operationId": "getAutomationsIdHoldout",
        "tags": [
          "Workflow"
        ],
        "summary": "Treated against holdout: conversion, orders, revenue per contact, sample sizes and significance.",
        "description": "Treated against holdout: conversion, orders, revenue per contact, sample sizes and significance.\n\nRequired API key scope: automations:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ holdout_percent, window_days, treated, holdout, comparison }.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/import/mappings": {
      "get": {
        "operationId": "getContactsImportMappings",
        "tags": [
          "Workflow"
        ],
        "summary": "Saved import column mappings and the platform presets.",
        "description": "Saved import column mappings and the platform presets.\n\nRequired API key scope: contacts:read.\n\nAuthentication: Session or API key.",
        "responses": {
          "200": {
            "description": "mappings and presets.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      },
      "post": {
        "operationId": "postContactsImportMappings",
        "tags": [
          "Workflow"
        ],
        "summary": "Save a column mapping.",
        "description": "Save a column mapping. It needs an email column; up to 50 per organization.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "201 { id }. 409 DUPLICATE.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/import/suggest-mapping": {
      "post": {
        "operationId": "postContactsImportSuggestMapping",
        "tags": [
          "Workflow"
        ],
        "summary": "Suggest a mapping from CSV headers: a saved mapping with the same header layout first, then a Mailchimp, Klaviyo or Brevo preset.",
        "description": "Suggest a mapping from CSV headers: a saved mapping with the same header layout first, then a Mailchimp, Klaviyo or Brevo preset.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "{ fingerprint, source, preset, suggested_mapping, tag_column }.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/import/validate": {
      "post": {
        "operationId": "postContactsImportValidate",
        "tags": [
          "Workflow"
        ],
        "summary": "Dry run of an import: counts of new, existing, invalid, not subscribed, duplicate and suppressed rows with samples.",
        "description": "Dry run of an import: counts of new, existing, invalid, not subscribed, duplicate and suppressed rows with samples. Nothing is written.\n\nRequired API key scope: contacts:write.\n\nAuthentication: Session or API key.",
        "responses": {
          "201": {
            "description": "Validation summary plus preview.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/contacts/import/jobs/{jobId}/errors": {
      "get": {
        "operationId": "getContactsImportJobsJobidErrors",
        "tags": [
          "Workflow"
        ],
        "summary": "Rows that were not imported, with the reason (also as /errors.csv).",
        "description": "Rows that were not imported, with the reason (also as /errors.csv).\n\nRequired API key scope: contacts:read.\n\nAuthentication: Session or API key.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "summary, errors, next_after_id.",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key (mnpk_...)",
        "description": "An API key sent as Authorization: Bearer <key>."
      }
    }
  }
}
