{
  "openapi": "3.1.1",
  "info": {
    "title": "FlowPrime newsletter",
    "description": "Subscriber capture and lifecycle for a FlowPrime organization. Tenant is resolved from the {org}.newsletter.* subdomain, ?tenant=, or the X-Org-Slug header. Browser embeds authenticate with a license JWT (Authorization: Bearer); trusted platform callers use X-Api-Key.",
    "version": "1.1.3-8f4320d"
  },
  "servers": [
    {
      "url": "https://{org}.newsletter.fastflow.tech",
      "description": "Tenant host. The org slug is also accepted as ?tenant= or the X-Org-Slug header.",
      "variables": {
        "org": {
          "default": "your-org",
          "description": "Your FlowPrime organization slug"
        }
      }
    }
  ],
  "paths": {
    "/api/subscribe": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "summary": "Subscribe an email address to this tenant's newsletter",
        "description": "Auth is either a license JWT (Authorization: Bearer, bound to the request Origin and to this tenant) for browser embeds, or X-Api-Key with the platform provision key for trusted callers. `fields` is an optional bag of extra subscriber data: keys match ^[a-z][a-z0-9_]{0,31}$ (lowercased first), at most 10, values trimmed to 200 chars, and the names of stored columns are reserved. Browser-submitted fields for an address that already exists are STAGED behind a confirm-your-details email rather than written, and the response says status=details_pending; a trusted caller writes them directly. status is subscribed | pending | details_pending | unsubscribed. An address that unsubscribed comes back only through a browser sign-up and its confirmation email (pending), whatever the double opt-in setting; a trusted caller gets status=unsubscribed and the row is left as it is.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "required": [
                  "email"
                ],
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "source": {
                    "type": [
                      "null",
                      "string"
                    ]
                  },
                  "hp": {
                    "type": [
                      "null",
                      "string"
                    ]
                  },
                  "ts": {
                    "pattern": "^-?(?:0|[1-9]\\d*)$",
                    "type": [
                      "integer",
                      "string"
                    ],
                    "format": "int64",
                    "default": 0
                  },
                  "consent": {
                    "type": [
                      "null",
                      "boolean"
                    ]
                  },
                  "fields": {
                    "type": [
                      "null",
                      "object"
                    ],
                    "additionalProperties": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscribeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests"
          }
        }
      }
    },
    "/api/unsubscribe/one-click": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/settings": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "put": {
        "tags": [
          "Newsletter"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SettingsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/embed-config": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/subscribers/export": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/subscribers": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/api/subscribers/{id}": {
      "delete": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/stats/growth": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/import": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImportRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                }
              }
            }
          }
        }
      }
    },
    "/api/import/history": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/admin/databases": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/health/live": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/health/ready": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/auth/login": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "returnUrl",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "login_hint",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "prompt",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/auth/callback": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/my-accounts": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/switch-account": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/auth/logout": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/editions": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "post": {
        "tags": [
          "Newsletter"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/editions/{id}": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "put": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "delete": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/editions/{id}/checks": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/editions/{id}/preview": {
      "get": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/editions/{id}/test": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/editions/{id}/send": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/SendRequest"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/editions/{id}/unschedule": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/tenants/provision": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/tenants/activate": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/tenants/deactivate": {
      "post": {
        "tags": [
          "Newsletter"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/tenants/{orgSlug}": {
      "delete": {
        "tags": [
          "Newsletter"
        ],
        "parameters": [
          {
            "name": "orgSlug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EditionRequest": {
        "required": [
          "subject",
          "previewText",
          "body"
        ],
        "type": "object",
        "properties": {
          "subject": {
            "type": [
              "null",
              "string"
            ]
          },
          "previewText": {
            "type": [
              "null",
              "string"
            ]
          },
          "body": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "ErrorResponse": {
        "required": [
          "error"
        ],
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "detail": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "ImportRequest": {
        "required": [
          "csv",
          "fileName",
          "dryRun",
          "keepAsTyped"
        ],
        "type": "object",
        "properties": {
          "csv": {
            "type": [
              "null",
              "string"
            ]
          },
          "fileName": {
            "type": [
              "null",
              "string"
            ]
          },
          "dryRun": {
            "type": [
              "null",
              "boolean"
            ]
          },
          "keepAsTyped": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Report": {
        "required": [
          "source",
          "rows",
          "toImport",
          "alreadyOnList",
          "imported",
          "skipped",
          "typosFixed",
          "typosFixedCount",
          "mailChecked",
          "domainsNotChecked"
        ],
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "rows": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "toImport": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "alreadyOnList": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "imported": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "skipped": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Skip"
            }
          },
          "typosFixed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Typo"
            }
          },
          "typosFixedCount": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "mailChecked": {
            "type": "boolean"
          },
          "domainsNotChecked": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          }
        }
      },
      "SendRequest": {
        "required": [
          "scheduledAt"
        ],
        "type": "object",
        "properties": {
          "scheduledAt": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          }
        }
      },
      "SettingsRequest": {
        "type": "object",
        "properties": {
          "doubleOptIn": {
            "type": "boolean",
            "default": false
          },
          "consentRequired": {
            "type": "boolean",
            "default": false
          },
          "consentText": {
            "type": [
              "null",
              "string"
            ]
          },
          "termsUrl": {
            "type": [
              "null",
              "string"
            ]
          },
          "privacyUrl": {
            "type": [
              "null",
              "string"
            ]
          },
          "locale": {
            "type": [
              "null",
              "string"
            ],
            "default": "en"
          },
          "fromName": {
            "type": [
              "null",
              "string"
            ]
          },
          "senderEmail": {
            "type": [
              "null",
              "string"
            ]
          },
          "postalAddress": {
            "type": [
              "null",
              "string"
            ]
          },
          "warmupEnabled": {
            "type": [
              "null",
              "boolean"
            ]
          },
          "warmupGapMinutes": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "trackOpensClicks": {
            "type": [
              "null",
              "boolean"
            ]
          }
        }
      },
      "Skip": {
        "required": [
          "reason",
          "count",
          "samples"
        ],
        "type": "object",
        "properties": {
          "reason": {
            "type": "string"
          },
          "count": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "samples": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "SubscribeResponse": {
        "required": [
          "message",
          "status"
        ],
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "TestRequest": {
        "required": [
          "to"
        ],
        "type": "object",
        "properties": {
          "to": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "Typo": {
        "required": [
          "from",
          "to"
        ],
        "type": "object",
        "properties": {
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Newsletter"
    }
  ]
}