@epilot/sdk 2.19.3 → 2.19.4

package/definitions/email-settings.json

@@ -0,0 +1,3736 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Messaging Settings API",
+    "version": "1.5.0",
+    "description": "The Messaging Settings API provides comprehensive management of email configurations for epilot organizations.\n\n## Overview\n\nThis API enables organizations to:\n- **Email Addresses**: Configure sender email addresses, set primary addresses, and manage email aliases\n- **Email Signatures**: Create and manage HTML email signatures that can be associated with email addresses\n- **Custom Domains**: Add and verify custom email domains for professional branding\n- **Shared Inboxes**: Organize incoming emails into categorized inboxes with team assignments\n- **Microsoft 365 Integration**: Connect Outlook mailboxes for seamless email synchronization\n\n## Key Concepts\n\n### Email Addresses\nEmail addresses represent the sender identities used when composing emails. Each address can have:\n- A display name (e.g., \"Sales Team\")\n- Assigned users and groups who can send from this address\n- A default signature\n- Association with a shared inbox\n\n### Shared Inboxes\nShared inboxes help teams organize and manage incoming emails. Features include:\n- Color-coded categorization\n- Team member assignments\n- Routing rules for incoming messages\n\n### Email Signatures\nHTML signatures that are automatically appended to outgoing emails. Signatures can include:\n- Rich text formatting\n- Images and logos\n- Contact information\n\n### Custom Domains\nOrganizations can configure custom email domains to send emails from their own domain (e.g., `support@yourcompany.com`). This requires:\n1. Adding the domain\n2. Configuring DNS records\n3. Verifying domain ownership\n\n## Authentication\n\nAll endpoints require authentication via Bearer token (JWT) unless otherwise specified.\nUse the `x-epilot-org-id` header to specify the target organization when using shared tenant access.\n"
+  },
+  "tags": [
+    {
+      "name": "Email settings",
+      "description": "Legacy settings endpoints for managing various email configuration types including signatures,\ncustom domains, email addresses, and duplicate detection settings.\n"
+    },
+    {
+      "name": "Email addresses",
+      "description": "Manage email sender addresses for your organization. Email addresses define the identities\nfrom which emails can be sent. Each address can be configured with display names, user/group\nassignments, default signatures, and shared inbox associations.\n"
+    },
+    {
+      "name": "Shared inboxes",
+      "description": "Shared inboxes provide team-based email organization. They allow multiple users to collaborate\non incoming messages with features like color-coding, assignee management, and email routing.\nA default inbox is always available and does not need to be explicitly created.\n"
+    },
+    {
+      "name": "Inbox buckets",
+      "description": "Inbox buckets are internal storage containers associated with shared inboxes. Each shared inbox\nhas a corresponding bucket for message storage. The default bucket is always available.\n"
+    },
+    {
+      "name": "O365 Outlook Connection",
+      "description": "Microsoft Office 365 Outlook integration endpoints. These endpoints enable organizations to:\n- Initiate OAuth connections with Microsoft 365\n- Connect Outlook shared mailboxes\n- Manage connection status and tokens\n- Disconnect integrations when needed\n\nThe integration supports multiple Azure AD tenants and handles token refresh automatically.\n"
+    },
+    {
+      "name": "Custom SMTP",
+      "description": "Custom SMTP connection management. Lets organizations configure their own outbound\nSMTP server (e.g. Mailgun, SendGrid, a self-hosted Postfix) for sending emails\nfrom epilot via their existing provider. Credentials are encrypted at rest using\na customer-managed KMS key. Only outbound sending is supported — replies do not\ncome back into epilot.\n"
+    },
+    {
+      "name": "Channels",
+      "description": "Channel integration endpoints. Channels represent external communication providers\n(e.g., Microsoft Teams, WhatsApp) that can be connected to an epilot organization.\n\nAll channel endpoints live under `/v2/channels/{channel}`.\n"
+    },
+    {
+      "name": "Settings",
+      "description": "Generic settings management for various email configuration types:\n- **signature**: HTML email signatures\n- **email_domain**: Custom email domains\n- **email_address**: Sender email addresses\n- **whitelist_email_address**: Addresses exempt from duplicate detection\n- **restrict_duplicates_within**: Time window for duplicate email detection\n"
+    },
+    {
+      "name": "Domains",
+      "description": "Custom email domain management. Add, verify, and configure custom domains to send emails\nfrom your organization's domain. Domain verification requires proper DNS configuration\nincluding MX records and SPF/DKIM settings.\n"
+    }
+  ],
+  "security": [
+    {
+      "EpilotAuth": []
+    },
+    {
+      "AsOrganization": []
+    },
+    {
+      "EpilotOrg": []
+    }
+  ],
+  "paths": {
+    "/v2/email-settings/email-addresses/epilot:provision": {
+      "put": {
+        "operationId": "provisionEpilotEmailAddress",
+        "summary": "provisionEpilotEmailAddress",
+        "description": "Provisions or reactivates an epilot-managed email address for the organization.\n\nWhen provisioning a new epilot email address, any previously active epilot email addresses\nwill be automatically deactivated. Only one epilot email address can be active at a time.\n\nEpilot email addresses use the `@epilot.cloud` domain and are fully managed by the platform.\n",
+        "tags": [
+          "Email addresses"
+        ],
+        "requestBody": {
+          "description": "The epilot email address to provision",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProvisionEpilotEmailAddressPayload"
+              },
+              "example": {
+                "address": "mycompany@epilot.cloud"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/ProvisionEpilotEmailAddressSuccessResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/email-settings/email-addresses/primary": {
+      "post": {
+        "operationId": "setEmailAddressPrimary",
+        "summary": "setEmailAddressPrimary",
+        "description": "Sets the specified email address as the primary address for the organization.\n\nThe primary email address is used as the default sender address when composing new emails.\nOnly one email address can be primary at a time; setting a new primary will unset the previous one.\n",
+        "tags": [
+          "Email addresses"
+        ],
+        "requestBody": {
+          "description": "The email address to set as primary",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SetEmailAddressPrimaryPayload"
+              },
+              "example": {
+                "address": "sales@yourcompany.com"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/SetEmailAddressPrimarySuccessResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/email-settings/email-addresses/{id}": {
+      "get": {
+        "operationId": "getEmailAddress",
+        "summary": "getEmailAddress",
+        "description": "Retrieves the details of a specific email address by its ID.\n\nReturns the full configuration including display name, assigned users/groups,\ndefault signature, and shared inbox association.\n",
+        "tags": [
+          "Email addresses"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/EmailAddressId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetEmailAddressSuccessResponse"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteEmailAddress",
+        "summary": "deleteEmailAddress",
+        "description": "Permanently deletes an email address from the organization.\n\n**Warning**: This action cannot be undone. Users will no longer be able to send\nemails from this address after deletion.\n",
+        "tags": [
+          "Email addresses"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/EmailAddressId"
+          }
+        ],
+        "responses": {
+          "204": {
+            "$ref": "#/components/responses/NoContent"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "put": {
+        "operationId": "updateEmailAddress",
+        "summary": "updateEmailAddress",
+        "description": "Updates the configuration of an existing email address.\n\nYou can modify:\n- Display name\n- Assigned users and groups\n- Default signature\n- Shared inbox association\n- Active status\n",
+        "tags": [
+          "Email addresses"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/EmailAddressId"
+          }
+        ],
+        "requestBody": {
+          "description": "The fields to update on the email address",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateEmailAddressPayload"
+              },
+              "example": {
+                "name": "Sales Team",
+                "user_ids": [
+                  "user-123",
+                  "user-456"
+                ],
+                "default_signature_id": "sig-789",
+                "is_active": true
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/UpdateEmailAddressSuccessResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/email-settings/email-addresses": {
+      "get": {
+        "operationId": "listEmailAddresses",
+        "summary": "listEmailAddresses",
+        "description": "Retrieves all email addresses configured for the organization.\n\nReturns an array of email address configurations including their IDs, display names,\nassigned users/groups, signatures, and status flags.\n",
+        "tags": [
+          "Email addresses"
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/ListEmailAddressesSuccessResponse"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "post": {
+        "operationId": "addEmailAddress",
+        "summary": "addEmailAddress",
+        "description": "Adds a new email address to the organization.\n\nThe email address can be from a custom domain (if configured) or any external\nemail provider. Optionally assign users, groups, and a default signature.\n",
+        "tags": [
+          "Email addresses"
+        ],
+        "requestBody": {
+          "description": "The email address configuration to create",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateEmailAddressPayload"
+              },
+              "example": {
+                "address": "support@yourcompany.com",
+                "name": "Customer Support",
+                "user_ids": [
+                  "user-123"
+                ],
+                "group_ids": [
+                  "group-456"
+                ],
+                "default_signature_id": "sig-789",
+                "shared_inbox_id": "inbox-abc"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "$ref": "#/components/responses/CreateEmailAddressSuccessResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/email-settings/shared-inboxes/{id}": {
+      "get": {
+        "operationId": "getSharedInbox",
+        "summary": "getSharedInbox",
+        "description": "Retrieves the details of a specific shared inbox by its ID.\n\nReturns the inbox configuration including name, color, description, assigned team members,\nand the associated bucket ID.\n",
+        "tags": [
+          "Shared inboxes"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/SharedInboxId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetSharedInboxSuccessResponse"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteSharedInbox",
+        "summary": "deleteSharedInbox",
+        "description": "Deletes a shared inbox and reroutes all associated emails to a successor inbox.\n\nWhen a shared inbox is deleted:\n- All email addresses associated with this inbox will be reassigned to the successor\n- If no successor is specified, emails are routed to the default inbox\n- The inbox's message history is preserved in the successor inbox\n\n**Note**: The default inbox cannot be deleted.\n",
+        "tags": [
+          "Shared inboxes"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/SharedInboxId"
+          },
+          {
+            "name": "successorInboxId",
+            "description": "ID of the inbox that will receive emails from the deleted inbox.\nIf not provided, the default inbox (`default`) will be used as the successor.\n",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "example": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+          }
+        ],
+        "responses": {
+          "204": {
+            "$ref": "#/components/responses/NoContent"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "put": {
+        "operationId": "updateSharedInbox",
+        "summary": "updateSharedInbox",
+        "description": "Updates the configuration of an existing shared inbox.\n\nYou can modify the inbox name, color, description, and team member assignments.\nChanges take effect immediately for all associated email addresses.\n",
+        "tags": [
+          "Shared inboxes"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/SharedInboxId"
+          }
+        ],
+        "requestBody": {
+          "description": "The fields to update on the shared inbox",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateSharedInboxPayload"
+              },
+              "example": {
+                "name": "Customer Support",
+                "color": "#4CAF50",
+                "description": "Incoming customer support requests",
+                "assignees": [
+                  "user-123",
+                  "user-456"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/UpdateSharedInboxSuccessResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/email-settings/shared-inboxes": {
+      "get": {
+        "operationId": "listSharedInboxes",
+        "summary": "listSharedInboxes",
+        "description": "Retrieves all shared inboxes configured for the organization.\n\n**Note**: The default inbox (with ID `default`) is not included in this list but is\nalways available for all organizations. You do not need to create it explicitly.\n",
+        "tags": [
+          "Shared inboxes"
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/ListSharedInboxesSuccessResponse"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "post": {
+        "operationId": "addSharedInbox",
+        "summary": "addSharedInbox",
+        "description": "Creates a new shared inbox for the organization.\n\nShared inboxes help teams organize and categorize incoming emails.\nEach inbox requires a name and color for visual identification.\n",
+        "tags": [
+          "Shared inboxes"
+        ],
+        "requestBody": {
+          "description": "The shared inbox configuration to create",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateSharedInboxPayload"
+              },
+              "example": {
+                "name": "Sales Inquiries",
+                "color": "#2196F3",
+                "description": "Inbound sales and pricing requests",
+                "assignees": [
+                  "user-123",
+                  "user-456"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "$ref": "#/components/responses/CreateSharedInboxSuccessResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/email-settings/inbox-buckets": {
+      "get": {
+        "operationId": "listInboxBuckets",
+        "summary": "listInboxBuckets",
+        "description": "Retrieves all inbox buckets for the organization.\n\nInbox buckets are internal storage containers that correspond to shared inboxes.\nEach shared inbox has an associated bucket for storing messages.\n\n**Note**: The default bucket (with ID `default`) is not included in this list but\nis always available for all organizations.\n",
+        "tags": [
+          "Inbox buckets"
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/ListInboxBucketsSuccessResponse"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/outlook/connect": {
+      "post": {
+        "operationId": "connectOutlook",
+        "summary": "connectOutlook",
+        "description": "Returns the Microsoft authorization URL for Outlook OAuth.\n\nThe request body selects which features to request scopes for. Feature\nflags are additive; Microsoft OAuth scopes are cumulative. Calling this\nendpoint again with a superset of features (e.g. `mail` already connected,\nand `calendar` added) triggers Microsoft's incremental-consent flow —\nthe user only sees a consent prompt for the new scopes.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConnectOutlookRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Authorization URL",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "authorization_url"
+                  ],
+                  "properties": {
+                    "authorization_url": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/OutlookErrorResponse"
+          },
+          "403": {
+            "$ref": "#/components/responses/OutlookErrorResponse"
+          }
+        }
+      }
+    },
+    "/v2/outlook/connection/status": {
+      "get": {
+        "operationId": "getOutlookConnectionStatus",
+        "summary": "getOutlookConnectionStatus",
+        "description": "Returns all Microsoft 365 / Outlook connections for the organization.\nSupports multiple connections (one per Azure AD tenant).\n\nEach connection includes an `action` field that tells the UI what button to show\nand what endpoint to call. All actions use GET /outlook/connect.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "responses": {
+          "200": {
+            "description": "Connection status retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "connections",
+                    "has_connections"
+                  ],
+                  "properties": {
+                    "connections": {
+                      "type": "array",
+                      "description": "List of Outlook connections (one per tenant)",
+                      "items": {
+                        "$ref": "#/components/schemas/OutlookConnectionStatus"
+                      }
+                    },
+                    "has_connections": {
+                      "type": "boolean",
+                      "description": "Whether any connections exist"
+                    },
+                    "teams_enabled": {
+                      "type": "boolean",
+                      "description": "Whether Microsoft Teams features are enabled for this organization"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - missing organization ID"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/outlook/calendar/admin-consent-status": {
+      "get": {
+        "operationId": "getCalendarAdminConsentStatus",
+        "summary": "getCalendarAdminConsentStatus",
+        "description": "Reports whether the caller's organization can connect personal Outlook\ncalendars.\n\nConnecting a personal calendar requires the tenant admin to have\nconsented to epilot's Microsoft 365 app. That consent is tenant-wide,\none-time, and granted for the full scope set (mail + calendar), so the\norg-level Outlook connection set up during onboarding is the gate.\n\nWhen consent is missing the response includes `admin_consent_url` for\nthe admin to open, and the UI should ask the user to involve their IT\ninstead of starting an OAuth flow that would fail.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "responses": {
+          "200": {
+            "description": "Admin consent status for the organization",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CalendarAdminConsentStatus"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/outlook/calendar/me": {
+      "get": {
+        "operationId": "getMyCalendarConnection",
+        "summary": "getMyCalendarConnection",
+        "description": "Returns the calling user's personal Outlook calendar connection,\nor null when the user hasn't connected yet.\n\nPer-user calendar connections are distinct from the org-level\nshared-mailbox connection (`/v2/outlook/connection/status`): each\nuser connects their own delegated token because reading user A's\ncalendar requires user A's consent.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "responses": {
+          "200": {
+            "description": "Calendar connection (or null if absent)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MyCalendarConnectionResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "disconnectMyCalendar",
+        "summary": "disconnectMyCalendar",
+        "description": "Removes the calling user's personal calendar connection.",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "responses": {
+          "204": {
+            "description": "Disconnected"
+          },
+          "404": {
+            "description": "No connection to disconnect"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/outlook/connection/disconnect": {
+      "post": {
+        "operationId": "disconnectOutlook",
+        "summary": "disconnectOutlook",
+        "description": "Removes the Microsoft 365 / Outlook connection for a specific tenant.\nThis deletes the stored tokens and disconnects the integration.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "tenant_id"
+                ],
+                "properties": {
+                  "tenant_id": {
+                    "type": "string",
+                    "description": "Azure AD Tenant ID of the connection to disconnect"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successfully disconnected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "tenant_id": {
+                      "type": "string",
+                      "description": "The tenant ID that was disconnected"
+                    },
+                    "affected_shared_inboxes": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "List of shared inbox IDs that were affected by the disconnection"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - missing tenant_id or organization ID"
+          },
+          "404": {
+            "description": "Connection not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/channels/msteams/connect": {
+      "post": {
+        "operationId": "connectMsTeams",
+        "summary": "connectMsTeams",
+        "description": "Connects Microsoft Teams channel (click-to-call deep links, meetings) for the organization.\nRequires an active Microsoft 365 / Outlook connection.\n",
+        "tags": [
+          "Channels"
+        ],
+        "responses": {
+          "200": {
+            "description": "Teams channel connected successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "connected": {
+                      "type": "boolean"
+                    },
+                    "connected_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "No active Outlook connection found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v2/channels/msteams/disconnect": {
+      "post": {
+        "operationId": "disconnectMsTeams",
+        "summary": "disconnectMsTeams",
+        "description": "Disconnects Microsoft Teams channel for the organization.\n",
+        "tags": [
+          "Channels"
+        ],
+        "responses": {
+          "200": {
+            "description": "Teams channel disconnected successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "connected": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v2/channels/msteams/status": {
+      "get": {
+        "operationId": "getMsTeamsStatus",
+        "summary": "getMsTeamsStatus",
+        "description": "Returns the connection status of the Microsoft Teams channel for the organization.\n",
+        "tags": [
+          "Channels"
+        ],
+        "responses": {
+          "200": {
+            "description": "Teams channel status retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "connected": {
+                      "type": "boolean",
+                      "description": "Whether the Teams channel is connected"
+                    },
+                    "connected_at": {
+                      "type": "string",
+                      "format": "date-time",
+                      "description": "When the Teams channel was connected"
+                    },
+                    "connected_by_user_id": {
+                      "type": "string",
+                      "description": "User ID who connected the Teams channel"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v2/outlook/mailbox/connect": {
+      "post": {
+        "operationId": "connectOutlookMailbox",
+        "summary": "connectOutlookMailbox",
+        "description": "Connects an Outlook mailbox:\n  1. Validates the user has access to the mailbox via Microsoft Graph API\n  2. Creates a mapping between the email address of the mailbox and the outlook connection\n  3. Enables the user to send emails as the mailbox's email address\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "email"
+                ],
+                "properties": {
+                  "email": {
+                    "type": "string",
+                    "format": "email",
+                    "description": "Email address of the Outlook mailbox to connect"
+                  },
+                  "shared_inbox_id": {
+                    "type": "string",
+                    "description": "Shared inbox ID to associate with the mailbox. Defaults to the default shared inbox.",
+                    "default": "default"
+                  },
+                  "name": {
+                    "type": "string",
+                    "description": "Sender name to use for the Outlook mailbox email address."
+                  },
+                  "user_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "User IDs for which this email address should be available by default."
+                  },
+                  "group_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Group IDs for which this email address should be available by default."
+                  },
+                  "default_signature_id": {
+                    "type": "string",
+                    "description": "Default signature ID to use for this Outlook mailbox email address."
+                  },
+                  "mailboxSyncTimeframe": {
+                    "type": "string",
+                    "enum": [
+                      "5m",
+                      "1w",
+                      "2w",
+                      "1m"
+                    ],
+                    "description": "Optional timeframe for initial mailbox sync. When provided, triggers an automatic\nmailbox sync after connecting the mailbox, syncing emails from the specified period.\n"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Mailbox connected successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "email_address",
+                    "outlook_email",
+                    "tenant_id",
+                    "provider"
+                  ],
+                  "properties": {
+                    "email_address": {
+                      "$ref": "#/components/schemas/EmailAddressResponse"
+                    },
+                    "outlook_email": {
+                      "type": "string",
+                      "format": "email",
+                      "description": "The email of the connected mailbox"
+                    },
+                    "tenant_id": {
+                      "type": "string",
+                      "description": "Azure AD Tenant ID that provisions this mailbox"
+                    },
+                    "provider": {
+                      "type": "string",
+                      "enum": [
+                        "outlook"
+                      ],
+                      "description": "The provider type"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - missing email parameter"
+          },
+          "401": {
+            "description": "Not connected to Microsoft 365"
+          },
+          "403": {
+            "description": "Access denied - user does not have access to the mailbox"
+          },
+          "409": {
+            "description": "A mailbox email already connected to an Outlook connection"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/outlook/mailbox/{email}/disconnect": {
+      "post": {
+        "operationId": "disconnectOutlookMailbox",
+        "summary": "Disconnect Outlook Mailbox",
+        "description": "Disconnects a single Outlook mailbox by email address.\nDeletes the email address entity, Outlook email mapping, and Graph API subscriptions.\nDoes not affect the tenant-level Outlook connection.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "parameters": [
+          {
+            "name": "email",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "email"
+            },
+            "description": "Email address of the Outlook mailbox to disconnect"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Mailbox disconnected successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "success",
+                    "email"
+                  ],
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "email": {
+                      "type": "string",
+                      "format": "email",
+                      "description": "The email address that was disconnected"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No Outlook mapping found for this email address"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/outlook/mailbox/{email}/sync": {
+      "post": {
+        "operationId": "startMailboxSync",
+        "summary": "Start Mailbox Sync",
+        "description": "Triggers an Outlook mailbox sync for the specified email address.\nSyncs existing emails (inbox + sent items) for the specified timeframe.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "parameters": [
+          {
+            "name": "email",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "email"
+            },
+            "description": "Email address of the Outlook mailbox to sync"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "timeframe"
+                ],
+                "properties": {
+                  "timeframe": {
+                    "allOf": [
+                      {
+                        "$ref": "#/components/schemas/MailboxSyncTimeframePeriods"
+                      }
+                    ],
+                    "description": "Sync period:\n- 5m: last 5 minutes (quick sync)\n- 1w: 1 week\n- 2w: 2 weeks\n- 1m: 1 month\n"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Sync started successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "execution_id",
+                    "status",
+                    "timeframe"
+                  ],
+                  "properties": {
+                    "execution_id": {
+                      "type": "string",
+                      "description": "The execution ID"
+                    },
+                    "status": {
+                      "$ref": "#/components/schemas/MailboxSyncStatuses"
+                    },
+                    "timeframe": {
+                      "$ref": "#/components/schemas/MailboxSyncTimeframePeriods"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid input provided"
+          },
+          "404": {
+            "description": "Mailbox not connected for the provided email address"
+          },
+          "409": {
+            "description": "A sync in progress for the provided mailbox"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/outlook/mailbox/{email}/sync/status": {
+      "get": {
+        "operationId": "getMailboxSyncStatus",
+        "summary": "Get Mailbox Sync Status",
+        "description": "Returns the current or latest sync status for the specified mailbox.\nPoll this endpoint to track sync progress.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "parameters": [
+          {
+            "name": "email",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "email"
+            },
+            "description": "Email address of the Outlook mailbox"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Sync status retrieved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MailboxSyncStatus"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No sync found for this mailbox"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/outlook/mailbox/{email}/sync/retry": {
+      "post": {
+        "operationId": "retryMailboxSync",
+        "summary": "Retry Failed Messages",
+        "description": "Retries failed messages from a previous sync execution.\nOnly retries messages with status FAILED (not PERMANENTLY_FAILED).\nMessages that fail 3+ retries become PERMANENTLY_FAILED.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "parameters": [
+          {
+            "name": "email",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "email"
+            },
+            "description": "Email address of the Outlook mailbox"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "sync_id"
+                ],
+                "properties": {
+                  "sync_id": {
+                    "type": "string",
+                    "description": "Execution ID of the sync to retry"
+                  },
+                  "scope": {
+                    "type": "string",
+                    "enum": [
+                      "all_failed"
+                    ],
+                    "description": "Retry scope. Use 'all_failed' to retry all retryable failed messages."
+                  },
+                  "message_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Specific Graph message IDs to retry (alternative to scope)"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Retry started",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "retry_execution_id",
+                    "messages_queued"
+                  ],
+                  "properties": {
+                    "retry_execution_id": {
+                      "type": "string",
+                      "description": "Execution ID for the retry sync"
+                    },
+                    "messages_queued": {
+                      "type": "integer",
+                      "description": "Number of messages queued for retry"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No sync found or no retryable messages"
+          },
+          "409": {
+            "description": "A sync is already running for this mailbox"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/outlook/mailbox/mappings": {
+      "get": {
+        "operationId": "getConnectedOutlookEmails",
+        "summary": "getConnectedOutlookEmails",
+        "description": "Returns all Outlook email addresses connected to the organization.\n",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "responses": {
+          "200": {
+            "description": "Outlook emails retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "outlook_emails",
+                    "count"
+                  ],
+                  "properties": {
+                    "outlook_emails": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/ConnectedOutlookEmail"
+                      }
+                    },
+                    "count": {
+                      "type": "integer",
+                      "description": "Number of Outlook emails"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - missing organization ID"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/smtp/connections": {
+      "get": {
+        "operationId": "listSmtpConnections",
+        "summary": "listSmtpConnections",
+        "description": "Returns all custom SMTP connections configured for the organization.\nPasswords are never returned.\n",
+        "tags": [
+          "Custom SMTP"
+        ],
+        "responses": {
+          "200": {
+            "description": "SMTP connections listed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "connections",
+                    "has_connections"
+                  ],
+                  "properties": {
+                    "connections": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/SmtpConnection"
+                      }
+                    },
+                    "has_connections": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "post": {
+        "operationId": "createSmtpConnection",
+        "summary": "createSmtpConnection",
+        "description": "Creates a new custom SMTP connection. Runs a live verify against the SMTP server\nbefore persisting; on failure the request is rejected and nothing is saved. Pass\n`skip_test=true` to store the configuration untested instead.\n",
+        "tags": [
+          "Custom SMTP"
+        ],
+        "parameters": [
+          {
+            "name": "skip_test",
+            "in": "query",
+            "required": false,
+            "description": "Save without running the live verify. Use when the server is not reachable from\nepilot yet, or when a referenced `{{ env.* }}` secret has not been set. The\nconnection is stored untested — `last_test_status` is left unset rather than\nclaimed as `ok` — and env references are not resolved either, since an\nunresolvable one is expected in this case.\n",
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateSmtpConnectionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "SMTP connection created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SmtpConnection"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error, SMTP test failed, or refused for security reasons\n(private IP, plaintext on non-localhost host, invalid TLS).\n"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/smtp/connections/{connectionId}": {
+      "parameters": [
+        {
+          "name": "connectionId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "get": {
+        "operationId": "getSmtpConnection",
+        "summary": "getSmtpConnection",
+        "description": "Returns a single custom SMTP connection by id. The password is never returned.",
+        "tags": [
+          "Custom SMTP"
+        ],
+        "responses": {
+          "200": {
+            "description": "SMTP connection retrieved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SmtpConnection"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "put": {
+        "operationId": "updateSmtpConnection",
+        "summary": "updateSmtpConnection",
+        "description": "Partial update; omitted fields keep their existing values. The merged\nconfiguration is verified against the SMTP server before persisting. Pass\n`skip_test=true` to store it untested instead, which also clears any previous\ntest result — it described a configuration that no longer applies.\n",
+        "tags": [
+          "Custom SMTP"
+        ],
+        "parameters": [
+          {
+            "name": "skip_test",
+            "in": "query",
+            "required": false,
+            "description": "Save without running the live verify. Use when the server is not reachable from\nepilot yet, or when a referenced `{{ env.* }}` secret has not been set. The\nconnection is stored untested — `last_test_status` is left unset rather than\nclaimed as `ok` — and env references are not resolved either, since an\nunresolvable one is expected in this case.\n",
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateSmtpConnectionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "SMTP connection updated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SmtpConnection"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error or SMTP test failed"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteSmtpConnection",
+        "summary": "deleteSmtpConnection",
+        "description": "Deletes a custom SMTP connection. Messages already sent are unaffected.",
+        "tags": [
+          "Custom SMTP"
+        ],
+        "responses": {
+          "200": {
+            "description": "SMTP connection deleted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "connection_id": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v2/smtp/connections/{connectionId}/test": {
+      "parameters": [
+        {
+          "name": "connectionId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "post": {
+        "operationId": "testSmtpConnection",
+        "summary": "testSmtpConnection",
+        "description": "Re-runs a live SMTP verify against the saved configuration (EHLO + AUTH + NOOP + QUIT)\nand updates `last_test_status` / `last_tested_at` on the connection.\n",
+        "tags": [
+          "Custom SMTP"
+        ],
+        "responses": {
+          "200": {
+            "description": "SMTP test executed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SmtpTestResult"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v2/smtp/senders": {
+      "get": {
+        "operationId": "listSmtpSenders",
+        "summary": "listSmtpSenders",
+        "description": "Returns every address registered to send through a custom SMTP connection.",
+        "tags": [
+          "Custom SMTP"
+        ],
+        "responses": {
+          "200": {
+            "description": "SMTP senders listed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "senders"
+                  ],
+                  "properties": {
+                    "senders": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/SmtpSender"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "post": {
+        "operationId": "connectSmtpSender",
+        "summary": "connectSmtpSender",
+        "description": "Registers an address as a sender on a custom SMTP connection:\n  1. Creates the email address so it can be picked in the composer\n  2. Binds it to the connection, so outgoing mail from it is routed there\nThe SMTP server still has the final say on which From addresses it accepts.\n",
+        "tags": [
+          "Custom SMTP"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConnectSmtpSenderRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Sender connected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "email_address",
+                    "sender"
+                  ],
+                  "properties": {
+                    "email_address": {
+                      "$ref": "#/components/schemas/EmailAddressResponse"
+                    },
+                    "sender": {
+                      "$ref": "#/components/schemas/SmtpSender"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "description": "The referenced SMTP connection does not exist"
+          },
+          "409": {
+            "description": "The address is already registered, here or in another organization"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/smtp/senders/{email}": {
+      "parameters": [
+        {
+          "name": "email",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "format": "email"
+          }
+        }
+      ],
+      "delete": {
+        "operationId": "disconnectSmtpSender",
+        "summary": "disconnectSmtpSender",
+        "description": "Removes a sender address: deletes the email address and its binding to the SMTP\nconnection. The connection itself and messages already sent are unaffected.\n",
+        "tags": [
+          "Custom SMTP"
+        ],
+        "responses": {
+          "200": {
+            "description": "Sender disconnected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "success",
+                    "email"
+                  ],
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "email": {
+                      "type": "string",
+                      "format": "email"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/outlook/oauth/callback": {
+      "get": {
+        "operationId": "outlookOAuthCallback",
+        "summary": "outlookOAuthCallback",
+        "description": "Exchanges authorization code for tokens and stores them.",
+        "tags": [
+          "O365 Outlook Connection"
+        ],
+        "security": [],
+        "parameters": [
+          {
+            "name": "code",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "state",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "session_state",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "error",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "error_description",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "error_subcode",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "client_info",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "error_uri",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "admin_consent",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "tenant",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "clientdata",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Stored",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "connected": {
+                      "type": "boolean"
+                    },
+                    "expires_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "scope": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/email-settings": {
+      "get": {
+        "operationId": "getSettings",
+        "summary": "getSettings",
+        "description": "Retrieves settings of a specific type for the organization.\n\nIf an `id` is provided, returns only that specific setting.\nOtherwise, returns all settings of the specified type.\n\n## Setting Types\n\n| Type | Description |\n|------|-------------|\n| `signature` | HTML email signatures |\n| `email_domain` | Custom email domains |\n| `email_address` | Sender email addresses |\n| `whitelist_email_address` | Addresses exempt from duplicate detection |\n| `restrict_duplicates_within` | Time window for duplicate email detection |\n",
+        "tags": [
+          "Settings"
+        ],
+        "parameters": [
+          {
+            "name": "type",
+            "description": "The type of settings to retrieve. Determines which category of\nemail settings will be returned.\n",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/SettingType"
+            },
+            "example": "signature"
+          },
+          {
+            "name": "id",
+            "description": "Optional ID to retrieve a specific setting. If omitted, all settings\nof the specified type are returned.\n",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "example": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully retrieved settings. Returns either a single setting object\n(when `id` is provided) or an array of settings.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SettingsResponse"
+                },
+                "examples": {
+                  "signature_list": {
+                    "summary": "List of email signatures",
+                    "value": [
+                      {
+                        "id": "sig-123",
+                        "type": "signature",
+                        "name": "Default Signature",
+                        "value": "Best regards",
+                        "html": "<p>Best regards,<br/>The Team</p>",
+                        "created_at": "2024-01-15T10:30:00Z"
+                      }
+                    ]
+                  },
+                  "single_signature": {
+                    "summary": "Single signature by ID",
+                    "value": {
+                      "id": "sig-123",
+                      "type": "signature",
+                      "name": "Default Signature",
+                      "value": "Best regards",
+                      "html": "<p>Best regards,<br/>The Team</p>",
+                      "created_at": "2024-01-15T10:30:00Z"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "post": {
+        "operationId": "addSetting",
+        "summary": "addSetting",
+        "description": "Creates a new setting of the specified type.\n\nThe setting type determines which fields are applicable:\n- **signature**: Requires `name`, `value` (plain text), and `html` (HTML content)\n- **email_domain**: Requires `value` (domain name)\n- **whitelist_email_address**: Requires `value` (email address)\n- **restrict_duplicates_within**: Requires `value` (time duration like \"5m\", \"1d\")\n",
+        "tags": [
+          "Settings"
+        ],
+        "requestBody": {
+          "description": "The setting to create",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Setting"
+              },
+              "examples": {
+                "create_signature": {
+                  "summary": "Create an email signature",
+                  "value": {
+                    "type": "signature",
+                    "name": "Sales Signature",
+                    "value": "Best regards, Sales Team",
+                    "html": "<p>Best regards,<br/><strong>Sales Team</strong></p>"
+                  }
+                },
+                "create_whitelist": {
+                  "summary": "Whitelist an email address from duplicate detection",
+                  "value": {
+                    "type": "whitelist_email_address",
+                    "value": "noreply@automated-system.com"
+                  }
+                },
+                "set_duplicate_window": {
+                  "summary": "Set duplicate detection time window",
+                  "value": {
+                    "type": "restrict_duplicates_within",
+                    "value": "5m"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Setting created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SettingsResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteSetting",
+        "summary": "deleteSetting",
+        "description": "Deletes a setting by its ID and type.\n\nBoth the `id` and `type` are required to uniquely identify the setting to delete.\n\n**Warning**: This action cannot be undone.\n",
+        "tags": [
+          "Settings"
+        ],
+        "requestBody": {
+          "description": "The setting identifier to delete",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "id",
+                  "type"
+                ],
+                "properties": {
+                  "type": {
+                    "$ref": "#/components/schemas/SettingType"
+                  },
+                  "id": {
+                    "type": "string",
+                    "description": "The unique identifier of the setting to delete",
+                    "example": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+                  }
+                }
+              },
+              "example": {
+                "type": "signature",
+                "id": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Setting deleted successfully. Returns the deleted setting.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Setting"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/email-settings/{id}": {
+      "post": {
+        "operationId": "updateSetting",
+        "summary": "updateSetting",
+        "description": "Updates an existing setting identified by its ID.\n\nInclude the `type` field in the request body to specify which setting type\nis being updated. Only the fields provided will be updated.\n",
+        "tags": [
+          "Settings"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "description": "The unique identifier of the setting to update",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "example": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+          }
+        ],
+        "requestBody": {
+          "description": "The setting fields to update",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Setting"
+              },
+              "example": {
+                "type": "signature",
+                "name": "Updated Signature Name",
+                "html": "<p>Updated signature content</p>"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Setting updated successfully. Returns the updated setting.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Setting"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/email-settings/domain": {
+      "post": {
+        "operationId": "addDomain",
+        "summary": "addDomain",
+        "description": "Adds a custom email domain to the organization.\n\nAfter adding the domain, you must:\n1. Configure the required DNS records (provided in the response)\n2. Verify the domain using the verification endpoint\n\nUntil verification is complete, the domain cannot be used for sending emails.\n",
+        "tags": [
+          "Domains"
+        ],
+        "requestBody": {
+          "description": "The domain to add",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Domain"
+              },
+              "example": {
+                "domain": "mail.yourcompany.com"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Domain added successfully. The response includes DNS records that must be\nconfigured before verification.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SettingsResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteDomain",
+        "summary": "deleteDomain",
+        "description": "Removes a custom email domain from the organization.\n\n**Warning**: Deleting a domain will prevent sending emails from any addresses\nusing this domain. Existing email addresses on this domain should be removed\nor reassigned before deleting the domain.\n",
+        "tags": [
+          "Domains"
+        ],
+        "requestBody": {
+          "description": "The domain to delete",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Domain"
+              },
+              "example": {
+                "domain": "mail.yourcompany.com"
+              }
+            }
+          }
+        },
+        "responses": {
+          "204": {
+            "description": "Domain deleted successfully"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "get": {
+        "operationId": "getDomains",
+        "summary": "getDomains",
+        "description": "Retrieves all custom email domains for the organization.\n",
+        "tags": [
+          "Domains"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully retrieved domains.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/email-settings/domain/name-servers:verify": {
+      "post": {
+        "operationId": "verifyNameServers",
+        "summary": "verifyNameServers",
+        "description": "Verifies that the domain's name server (NS) records are correctly configured.\n\nThis check ensures that DNS resolution is properly set up for the domain\nbefore proceeding with full domain verification.\n\nRun this verification after configuring NS records in your DNS provider.\n\n**Deprecated**: Use `/domain/dns-records:verify` for new integrations.\n",
+        "tags": [
+          "Domains"
+        ],
+        "requestBody": {
+          "description": "The domain to verify name servers for",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Domain"
+              },
+              "example": {
+                "domain": "mail.yourcompany.com"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Name server verification result. Check the response to see if\nverification passed or if additional DNS configuration is needed.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SettingsResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/email-settings/domain/dns-records:verify": {
+      "post": {
+        "operationId": "verifyDnsRecords",
+        "summary": "verifyDnsRecords",
+        "description": "Verifies that the domain's DNS records (MX, TXT, CNAME) are correctly configured\nin the customer's DNS provider.\n\nThis check performs DNS lookups to confirm each required record is present\nbefore proceeding with full domain identity verification.\n\nRun this verification after configuring all DNS records in your DNS provider.\n",
+        "tags": [
+          "Domains"
+        ],
+        "requestBody": {
+          "description": "The domain to verify DNS records for",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Domain"
+              },
+              "example": {
+                "domain": "mail.yourcompany.com"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "DNS record verification result. Check the response to see if all records\nare verified or if additional DNS configuration is needed.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SettingsResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/email-settings/domain:verify": {
+      "post": {
+        "operationId": "verifyDomain",
+        "summary": "verifyDomain",
+        "description": "Verifies ownership and configuration of a custom email domain.\n\nDomain verification checks:\n- DNS TXT records for domain ownership\n- MX records for email routing\n- SPF records for sender authentication\n- DKIM records for email signing\n\nOnce verified, the domain can be used to create email addresses and send emails.\n",
+        "tags": [
+          "Domains"
+        ],
+        "requestBody": {
+          "description": "The domain to verify",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Domain"
+              },
+              "example": {
+                "domain": "mail.yourcompany.com"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Domain verification result. The response indicates whether verification\npassed and which DNS records (if any) still need configuration.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SettingsResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "responses": {
+      "ListInboxBucketsSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/InboxBucketResponse"
+              }
+            }
+          }
+        }
+      },
+      "ProvisionEpilotEmailAddressSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/EmailAddressResponse"
+            }
+          }
+        }
+      },
+      "SetEmailAddressPrimarySuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/EmailAddressResponse"
+            }
+          }
+        }
+      },
+      "CreateEmailAddressSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/EmailAddressResponse"
+            }
+          }
+        }
+      },
+      "UpdateEmailAddressSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/EmailAddressResponse"
+            }
+          }
+        }
+      },
+      "GetEmailAddressSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/EmailAddressResponse"
+            }
+          }
+        }
+      },
+      "ListEmailAddressesSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/EmailAddressResponse"
+              }
+            }
+          }
+        }
+      },
+      "NoContent": {
+        "description": "Success"
+      },
+      "CreateSharedInboxSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/SharedInboxResponse"
+            }
+          }
+        }
+      },
+      "UpdateSharedInboxSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/SharedInboxResponse"
+            }
+          }
+        }
+      },
+      "GetSharedInboxSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/SharedInboxResponse"
+            }
+          }
+        }
+      },
+      "ListSharedInboxesSuccessResponse": {
+        "description": "Success",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/SharedInboxResponse"
+              }
+            }
+          }
+        }
+      },
+      "BadRequest": {
+        "description": "The request was malformed or contains invalid data.\nCheck the error message for details on which fields are invalid.\n",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            },
+            "example": {
+              "error": "Invalid email address format",
+              "status": 400
+            }
+          }
+        }
+      },
+      "Forbidden": {
+        "description": "Access denied. The authenticated user does not have permission to perform\nthis operation. This may occur if:\n- The user lacks the required role or permissions\n- The resource belongs to a different organization\n",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            },
+            "example": {
+              "error": "Insufficient permissions to access this resource",
+              "status": 403
+            }
+          }
+        }
+      },
+      "NotFound": {
+        "description": "The requested resource was not found. Verify that:\n- The resource ID is correct\n- The resource exists in your organization\n- The resource has not been deleted\n",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            },
+            "example": {
+              "error": "Email address not found",
+              "status": 404
+            }
+          }
+        }
+      },
+      "Conflict": {
+        "description": "The request conflicts with the current state of the resource.\nCommon causes include:\n- Attempting to create a resource that already exists\n- Concurrent modification conflicts\n- Business rule violations (e.g., duplicate email address)\n",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            },
+            "example": {
+              "error": "Email address already exists in another configuration",
+              "status": 409
+            }
+          }
+        }
+      },
+      "InternalServerError": {
+        "description": "An unexpected error occurred on the server. If this error persists,\nplease contact support with the request details and timestamp.\n",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            },
+            "example": {
+              "error": "An unexpected error occurred",
+              "status": 500
+            }
+          }
+        }
+      },
+      "OutlookErrorResponse": {
+        "description": "An error response from the Outlook OAuth flow.\nMay include an admin consent URL if admin permissions are required.\n",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/OutlookConnectionError"
+            },
+            "example": {
+              "error": "access_denied",
+              "error_description": "Access denied",
+              "admin_consent_url": "https://login.microsoftonline.com/common/adminconsent?client_id=..."
+            }
+          }
+        }
+      }
+    },
+    "parameters": {
+      "EmailAddressId": {
+        "name": "id",
+        "description": "Unique identifier of the email address. This can be either the UUID assigned\nwhen the email address was created, or the email address string itself.\n",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        },
+        "examples": {
+          "uuid": {
+            "summary": "UUID identifier",
+            "value": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+          },
+          "email": {
+            "summary": "Email address string",
+            "value": "sales@yourcompany.com"
+          }
+        }
+      },
+      "SharedInboxId": {
+        "name": "id",
+        "description": "Unique identifier (UUID) of the shared inbox.\nUse `default` to reference the organization's default inbox.\n",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        },
+        "examples": {
+          "uuid": {
+            "summary": "UUID identifier",
+            "value": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+          },
+          "default": {
+            "summary": "Default inbox",
+            "value": "default"
+          }
+        }
+      }
+    },
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Primary authentication using epilot OAuth2 bearer token.\nInclude the JWT token in the Authorization header: `Authorization: Bearer <token>`\n",
+        "bearerFormat": "JWT"
+      },
+      "AsOrganization": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "x-ivy-org-id",
+        "description": "**Internal use only.** Sets the organization context when using internal service-to-service\nauthentication. Not intended for external API consumers.\n"
+      },
+      "EpilotOrg": {
+        "type": "apiKey",
+        "name": "x-epilot-org-id",
+        "in": "header",
+        "description": "Overrides the target organization for shared tenant access.\nUse this header when you have access to multiple organizations and need to\nspecify which organization's data to access.\n"
+      }
+    },
+    "schemas": {
+      "ConnectOutlookRequest": {
+        "type": "object",
+        "description": "Feature flags selecting which Microsoft Graph scopes to request.\nAt least one flag must be true. Passing a superset of previously\ngranted features triggers incremental consent for the delta only.\n",
+        "additionalProperties": false,
+        "minProperties": 1,
+        "properties": {
+          "mail": {
+            "type": "boolean",
+            "description": "Request 'mail' specific scopes."
+          },
+          "calendar": {
+            "type": "boolean",
+            "description": "Request 'calendar' specific scopes."
+          },
+          "return_to": {
+            "type": "string",
+            "maxLength": 512,
+            "pattern": "^/[^/\\\\].*$",
+            "description": "Optional same-origin frontend path to redirect to after the OAuth\nround-trip. Must start with a single \"/\" — protocol-relative\nand absolute URLs are rejected.\n"
+          }
+        }
+      },
+      "MailboxSyncStatus": {
+        "type": "object",
+        "required": [
+          "execution_id",
+          "status",
+          "timeframe",
+          "started_at"
+        ],
+        "properties": {
+          "execution_id": {
+            "type": "string"
+          },
+          "status": {
+            "$ref": "#/components/schemas/MailboxSyncStatuses"
+          },
+          "timeframe": {
+            "$ref": "#/components/schemas/MailboxSyncTimeframePeriods"
+          },
+          "started_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "completed_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "inbox": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "$ref": "#/components/schemas/MailboxSyncFolderStatuses"
+              },
+              "total_messages": {
+                "type": "integer"
+              },
+              "processed_messages": {
+                "type": "integer"
+              },
+              "failed_messages": {
+                "type": "integer"
+              }
+            }
+          },
+          "sent_items": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "$ref": "#/components/schemas/MailboxSyncFolderStatuses"
+              },
+              "total_messages": {
+                "type": "integer"
+              },
+              "processed_messages": {
+                "type": "integer"
+              },
+              "failed_messages": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "MailboxSyncStatuses": {
+        "type": "string",
+        "enum": [
+          "RUNNING",
+          "COMPLETED",
+          "COMPLETED_WITH_ERRORS",
+          "FAILED",
+          "CANCELLED"
+        ]
+      },
+      "MailboxSyncFolderStatuses": {
+        "type": "string",
+        "enum": [
+          "PENDING",
+          "RUNNING",
+          "COMPLETED",
+          "FAILED",
+          "SKIPPED"
+        ]
+      },
+      "MailboxSyncTimeframePeriods": {
+        "type": "string",
+        "enum": [
+          "5m",
+          "1w",
+          "2w",
+          "1m"
+        ]
+      },
+      "InboxBucketResponse": {
+        "type": "object",
+        "description": "Inbox bucket representing the storage container for a shared inbox.",
+        "required": [
+          "id",
+          "inbox_id"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier of the bucket",
+            "example": "bucket-abc"
+          },
+          "inbox_id": {
+            "type": "string",
+            "description": "ID of the shared inbox associated with this bucket",
+            "example": "inbox-xyz"
+          }
+        }
+      },
+      "ProvisionEpilotEmailAddressPayload": {
+        "type": "object",
+        "description": "Request payload for provisioning an epilot-managed email address.",
+        "required": [
+          "address"
+        ],
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "The epilot email address to provision (must be on @epilot.cloud domain)",
+            "example": "mycompany@epilot.cloud"
+          }
+        }
+      },
+      "SetEmailAddressPrimaryPayload": {
+        "type": "object",
+        "description": "Request payload for setting an email address as the organization's primary address.",
+        "required": [
+          "address"
+        ],
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "The email address to set as primary",
+            "example": "sales@yourcompany.com"
+          }
+        }
+      },
+      "UpdateEmailAddressPayload": {
+        "type": "object",
+        "description": "Request payload for updating an email address configuration.\nAll fields are optional; only provided fields will be updated.\n",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Display name shown as the sender name in emails",
+            "example": "Sales Team"
+          },
+          "user_ids": {
+            "type": "array",
+            "description": "List of user IDs who can send from this address",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "user-123",
+              "user-456"
+            ]
+          },
+          "group_ids": {
+            "type": "array",
+            "description": "List of group IDs whose members can send from this address",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "group-789"
+            ]
+          },
+          "default_signature_id": {
+            "type": "string",
+            "description": "ID of the signature to use by default when sending from this address",
+            "example": "sig-abc"
+          },
+          "shared_inbox_id": {
+            "type": "string",
+            "description": "ID of the shared inbox to associate with this address",
+            "example": "inbox-xyz"
+          },
+          "is_active": {
+            "type": "boolean",
+            "description": "Whether the email address is active and can be used for sending",
+            "example": true
+          }
+        }
+      },
+      "CreateEmailAddressPayload": {
+        "type": "object",
+        "description": "Request payload for creating a new email address.",
+        "required": [
+          "address"
+        ],
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "The email address to add (e.g., from a custom domain or external provider)",
+            "example": "support@yourcompany.com"
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name shown as the sender name in emails",
+            "example": "Customer Support"
+          },
+          "user_ids": {
+            "type": "array",
+            "description": "List of user IDs who can send from this address",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "user-123"
+            ]
+          },
+          "group_ids": {
+            "type": "array",
+            "description": "List of group IDs whose members can send from this address",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "group-456"
+            ]
+          },
+          "default_signature_id": {
+            "type": "string",
+            "description": "ID of the signature to use by default when sending from this address",
+            "example": "sig-789"
+          },
+          "shared_inbox_id": {
+            "type": "string",
+            "description": "ID of the shared inbox to associate with this address",
+            "example": "inbox-abc"
+          }
+        }
+      },
+      "EmailAddressResponse": {
+        "description": "Email address configuration with all associated metadata.",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/SettingMeta"
+          },
+          {
+            "type": "object",
+            "required": [
+              "address"
+            ],
+            "properties": {
+              "address": {
+                "type": "string",
+                "description": "The email address string",
+                "example": "sales@yourcompany.com"
+              },
+              "name": {
+                "type": "string",
+                "description": "Display name shown as the sender name",
+                "example": "Sales Team"
+              },
+              "user_ids": {
+                "type": "array",
+                "description": "IDs of users who can send from this address",
+                "items": {
+                  "type": "string"
+                },
+                "example": [
+                  "user-123",
+                  "user-456"
+                ]
+              },
+              "group_ids": {
+                "type": "array",
+                "description": "IDs of groups whose members can send from this address",
+                "items": {
+                  "type": "string"
+                },
+                "example": [
+                  "group-789"
+                ]
+              },
+              "default_signature_id": {
+                "type": "string",
+                "description": "ID of the default signature for this address",
+                "example": "sig-abc"
+              },
+              "shared_inbox_id": {
+                "type": "string",
+                "description": "ID of the associated shared inbox",
+                "example": "inbox-xyz"
+              },
+              "is_active": {
+                "type": "boolean",
+                "description": "Whether the address is currently active for sending",
+                "example": true
+              },
+              "is_primary": {
+                "type": "boolean",
+                "description": "Whether this is the organization's primary email address",
+                "example": false
+              },
+              "is_epilot_email_address": {
+                "type": "boolean",
+                "description": "Whether this is an epilot-managed address (@epilot.cloud)",
+                "example": false
+              }
+            }
+          }
+        ]
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error response format for all API errors.",
+        "required": [
+          "error",
+          "status"
+        ],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Human-readable error message describing what went wrong",
+            "example": "Resource not found"
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code of the error",
+            "example": 404
+          }
+        }
+      },
+      "SettingMeta": {
+        "type": "object",
+        "description": "Common metadata fields for all settings and resources.",
+        "required": [
+          "id",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier (UUID) for the resource",
+            "example": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the resource was created",
+            "example": "2024-01-15T10:30:00Z"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the resource was last updated",
+            "example": "2024-01-20T14:45:00Z"
+          },
+          "created_by": {
+            "type": "string",
+            "description": "User ID of the user who created the resource",
+            "example": "user-123"
+          },
+          "updated_by": {
+            "type": "string",
+            "description": "User ID of the user who last updated the resource",
+            "example": "user-456"
+          }
+        }
+      },
+      "UpdateSharedInboxPayload": {
+        "type": "object",
+        "description": "Request payload for updating a shared inbox configuration.\nAll fields are optional; only provided fields will be updated.\n",
+        "properties": {
+          "color": {
+            "type": "string",
+            "description": "Hex color code for visual identification in the UI",
+            "example": "#4CAF50"
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name of the shared inbox",
+            "example": "Customer Support"
+          },
+          "assignees": {
+            "type": "array",
+            "description": "List of user IDs assigned to this inbox",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "user-123",
+              "user-456"
+            ]
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional description of the inbox purpose",
+            "example": "Incoming customer support requests"
+          }
+        }
+      },
+      "CreateSharedInboxPayload": {
+        "type": "object",
+        "description": "Request payload for creating a new shared inbox.",
+        "required": [
+          "name",
+          "color"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Optional custom ID for the inbox (auto-generated if not provided)",
+            "example": "support-inbox"
+          },
+          "color": {
+            "type": "string",
+            "description": "Hex color code for visual identification in the UI (required)",
+            "example": "#2196F3"
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name of the shared inbox (required)",
+            "example": "Sales Inquiries"
+          },
+          "assignees": {
+            "type": "array",
+            "description": "List of user IDs to assign to this inbox",
+            "default": [],
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "user-123",
+              "user-456"
+            ]
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional description of the inbox purpose",
+            "example": "Inbound sales and pricing requests"
+          }
+        }
+      },
+      "SharedInboxResponse": {
+        "description": "Shared inbox configuration with all associated metadata.",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/SettingMeta"
+          },
+          {
+            "type": "object",
+            "required": [
+              "id",
+              "name",
+              "color",
+              "assignees",
+              "bucket_id"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Unique identifier of the shared inbox",
+                "example": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+              },
+              "name": {
+                "type": "string",
+                "description": "Display name of the shared inbox",
+                "example": "Customer Support"
+              },
+              "color": {
+                "type": "string",
+                "description": "Hex color code for visual identification",
+                "example": "#4CAF50"
+              },
+              "assignees": {
+                "type": "array",
+                "description": "List of user IDs assigned to this inbox",
+                "default": [],
+                "items": {
+                  "type": "string"
+                },
+                "example": [
+                  "user-123",
+                  "user-456"
+                ]
+              },
+              "description": {
+                "type": "string",
+                "description": "Description of the inbox purpose",
+                "example": "Incoming customer support requests"
+              },
+              "bucket_id": {
+                "type": "string",
+                "description": "ID of the associated storage bucket for messages",
+                "example": "bucket-xyz"
+              }
+            }
+          }
+        ]
+      },
+      "SettingsResponse": {
+        "oneOf": [
+          {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Setting"
+            }
+          },
+          {
+            "$ref": "#/components/schemas/Setting"
+          }
+        ]
+      },
+      "ConnectedOutlookEmail": {
+        "type": "object",
+        "description": "Mapping between an Outlook email and its Outlook Connection.\nThis tracks which provider/tenant provisions each Outlook email.\n",
+        "required": [
+          "outlook_email"
+        ],
+        "properties": {
+          "outlook_email": {
+            "type": "string",
+            "format": "email",
+            "description": "The Outlook shared mailbox email address"
+          },
+          "tenant_id": {
+            "type": "string",
+            "description": "Azure AD Tenant ID that provisions this mailbox"
+          },
+          "provider": {
+            "type": "string",
+            "enum": [
+              "outlook"
+            ],
+            "description": "Provider type (for future extensibility)"
+          },
+          "connected_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the mailbox was connected"
+          },
+          "connected_by_user_id": {
+            "type": "string",
+            "description": "User who connected this mailbox"
+          }
+        }
+      },
+      "OutlookConnectionError": {
+        "type": "object",
+        "required": [
+          "error"
+        ],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Error code or message from the OAuth flow."
+          },
+          "error_description": {
+            "type": "string",
+            "description": "Human-readable description of the error."
+          },
+          "admin_consent_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL for tenant admin to grant consent, if applicable."
+          }
+        }
+      },
+      "CalendarAdminConsentStatus": {
+        "type": "object",
+        "required": [
+          "admin_consented"
+        ],
+        "properties": {
+          "admin_consented": {
+            "type": "boolean",
+            "description": "True when the tenant admin has consented to epilot's Microsoft 365\napp, so users in this organization can connect personal calendars.\n"
+          },
+          "admin_consent_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Microsoft admin-consent URL for an administrator to open. Present\nonly when `admin_consented` is false.\n"
+          }
+        }
+      },
+      "MyCalendarConnectionResponse": {
+        "type": "object",
+        "description": "Per-user calendar connection metadata, or null when the caller has\nnot connected their personal calendar yet.\n",
+        "properties": {
+          "connection": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/CalendarConnectionInfo"
+              }
+            ],
+            "nullable": true
+          }
+        }
+      },
+      "CalendarConnectionInfo": {
+        "type": "object",
+        "required": [
+          "user_id",
+          "tenant_id",
+          "status"
+        ],
+        "properties": {
+          "user_id": {
+            "type": "string",
+            "description": "Azure AD Object ID of the connected user"
+          },
+          "tenant_id": {
+            "type": "string",
+            "description": "Microsoft Azure AD tenant ID"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "connected",
+              "expired"
+            ],
+            "description": "Token health for this calendar connection"
+          },
+          "scopes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Granted permission scopes on the user's token"
+          },
+          "connected_by_display_name": {
+            "type": "string"
+          },
+          "connected_by_email": {
+            "type": "string",
+            "format": "email"
+          },
+          "connected_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "OutlookConnectionStatus": {
+        "type": "object",
+        "required": [
+          "status",
+          "action",
+          "action_label",
+          "tenant_id"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "connected",
+              "expired",
+              "pending_auth",
+              "not_connected"
+            ],
+            "description": "Current connection status:\n- pending_auth: Admin consent granted, waiting for user OAuth\n- connected: Fully connected with valid tokens\n- expired: Tokens expired, need to re-authenticate\n- not_connected: No connection, initiate OAuth\n"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "connect",
+              "authorize",
+              "reconnect",
+              "none"
+            ],
+            "description": "Action for UI to take (all call POST /outlook/connect):\n- connect: No connection, initiate OAuth\n- authorize: Admin consent done, complete OAuth\n- reconnect: Re-authenticate expired session or approve updated permissions\n- none: Fully connected, no action needed\n"
+          },
+          "action_reason": {
+            "type": "string",
+            "enum": [
+              "expired",
+              "permission_update"
+            ],
+            "description": "Discriminates the cause when `action` is `reconnect`:\n- expired: Stored tokens are no longer valid; user must re-authenticate\n- permission_update: Token is valid, but the granted scopes do not cover the\n  scopes required by the configured Outlook integrations (currently `mail`).\n  The user must reconnect to grant the additional permissions; Microsoft's\n  incremental-consent flow will only prompt for the delta.\n"
+          },
+          "connected_by_display_name": {
+            "type": "string",
+            "description": "Display name of user who connected"
+          },
+          "connected_by_email": {
+            "type": "string",
+            "format": "email",
+            "description": "Email of the user who connected"
+          },
+          "connected_by_user_id": {
+            "type": "string",
+            "description": "Azure AD Object ID of user who connected"
+          },
+          "connected_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the connection was established"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the connection was last updated"
+          },
+          "tenant_id": {
+            "type": "string",
+            "description": "Microsoft Azure AD tenant ID"
+          },
+          "scopes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Granted permission scopes"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the current access token expires"
+          },
+          "is_token_valid": {
+            "type": "boolean",
+            "description": "Whether the current token is still valid"
+          }
+        }
+      },
+      "SmtpConnection": {
+        "type": "object",
+        "required": [
+          "connection_id",
+          "smtp_host",
+          "smtp_port",
+          "smtp_secure",
+          "smtp_username"
+        ],
+        "properties": {
+          "connection_id": {
+            "type": "string",
+            "description": "Stable identifier for this SMTP connection"
+          },
+          "smtp_host": {
+            "type": "string",
+            "description": "Hostname of the SMTP server (e.g. smtp.mailgun.org)"
+          },
+          "smtp_port": {
+            "type": "string",
+            "description": "SMTP port (typically 587 for STARTTLS or 465 for TLS). A string, because it\nmay hold a `{{ env.your_key }}` reference rather than a literal port.\n"
+          },
+          "smtp_secure": {
+            "type": "string",
+            "enum": [
+              "tls",
+              "starttls"
+            ],
+            "description": "Connection security mode. Plaintext SMTP is not offered: it would put the\nSMTP password on the wire in the clear.\n- tls: Implicit TLS (port 465)\n- starttls: STARTTLS upgrade (port 587)\n"
+          },
+          "smtp_username": {
+            "type": "string",
+            "description": "SMTP auth username"
+          },
+          "smtp_password": {
+            "type": "string",
+            "description": "Only returned when the stored value is exactly one `{{ env.your_key }}`\nreference, which names a secret rather than being one — that lets the\nsettings UI edit the reference without dropping it. A literal password, or a\npartly templated one, is omitted entirely: submit an update without this\nfield to keep the stored value.\n"
+          },
+          "connected_by_display_name": {
+            "type": "string"
+          },
+          "connected_by_email": {
+            "type": "string",
+            "format": "email"
+          },
+          "connected_by_user_id": {
+            "type": "string"
+          },
+          "connected_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "last_tested_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "last_test_status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "auth_failed",
+              "tls_failed",
+              "host_unreachable",
+              "timeout",
+              "secret_missing",
+              "unknown"
+            ]
+          },
+          "last_test_error": {
+            "type": "string",
+            "description": "Latest test error message, if any"
+          }
+        }
+      },
+      "CreateSmtpConnectionRequest": {
+        "type": "object",
+        "required": [
+          "smtp_host",
+          "smtp_port",
+          "smtp_secure",
+          "smtp_username",
+          "smtp_password"
+        ],
+        "properties": {
+          "smtp_host": {
+            "type": "string"
+          },
+          "smtp_port": {
+            "description": "A port between 1 and 65535, or a `{{ env.your_key }}` template resolving to\none. An integer is still accepted, so callers predating the template support\nkeep working.\n",
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              }
+            ]
+          },
+          "smtp_secure": {
+            "type": "string",
+            "enum": [
+              "tls",
+              "starttls"
+            ]
+          },
+          "smtp_username": {
+            "type": "string"
+          },
+          "smtp_password": {
+            "type": "string",
+            "description": "May contain `{{ env.your_key }}` templates referencing the organization's\nenvironment variables (including secrets), resolved at send time. Stored as\nentered, so the settings UI edits the template rather than a resolved value.\n",
+            "example": "{{ env.smtp_password }}"
+          }
+        }
+      },
+      "UpdateSmtpConnectionRequest": {
+        "type": "object",
+        "description": "Partial update; omitted fields keep their existing values.",
+        "properties": {
+          "smtp_host": {
+            "type": "string"
+          },
+          "smtp_port": {
+            "description": "A port between 1 and 65535, or a `{{ env.your_key }}` template resolving to\none. An integer is still accepted, so callers predating the template support\nkeep working.\n",
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              }
+            ]
+          },
+          "smtp_secure": {
+            "type": "string",
+            "enum": [
+              "tls",
+              "starttls"
+            ]
+          },
+          "smtp_username": {
+            "type": "string"
+          },
+          "smtp_password": {
+            "type": "string"
+          }
+        }
+      },
+      "SmtpSender": {
+        "type": "object",
+        "description": "An address allowed to send through a custom SMTP connection. Mirrors an Outlook\nmailbox: the address, its display name and its assignees live on the shared\nemail-address record, while this row binds it to a set of SMTP credentials.\n",
+        "required": [
+          "email",
+          "connection_id"
+        ],
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "The sender address. Stored lower-cased."
+          },
+          "connection_id": {
+            "type": "string",
+            "description": "SMTP connection this address sends through"
+          },
+          "reply_to_email": {
+            "type": "string",
+            "description": "Default Reply-To for messages from this address. Custom SMTP is send-only, so\npoint this at a mailbox someone actually monitors. May contain a\n`{{ env.your_key }}` template, so this is not constrained to `format: email`.\nA per-message Reply-To still wins.\n"
+          },
+          "connected_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "connected_by_user_id": {
+            "type": "string"
+          }
+        }
+      },
+      "ConnectSmtpSenderRequest": {
+        "type": "object",
+        "required": [
+          "email",
+          "connection_id"
+        ],
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "Address to send from. Must be one the SMTP server accepts as a From."
+          },
+          "connection_id": {
+            "type": "string",
+            "description": "SMTP connection to send through"
+          },
+          "name": {
+            "type": "string",
+            "description": "Sender name shown on outgoing messages."
+          },
+          "reply_to_email": {
+            "type": "string",
+            "description": "Email address, or a `{{ env.your_key }}` template resolving to one."
+          },
+          "shared_inbox_id": {
+            "type": "string",
+            "description": "Shared inbox to associate with the address. Defaults to the default shared inbox.",
+            "default": "default"
+          },
+          "user_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "User IDs for which this address should be available by default."
+          },
+          "group_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Group IDs for which this address should be available by default."
+          },
+          "default_signature_id": {
+            "type": "string",
+            "description": "Default signature ID to use for this address."
+          }
+        }
+      },
+      "SmtpTestResult": {
+        "type": "object",
+        "required": [
+          "status",
+          "tested_at"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "auth_failed",
+              "tls_failed",
+              "host_unreachable",
+              "timeout",
+              "secret_missing",
+              "unknown"
+            ]
+          },
+          "error": {
+            "type": "string"
+          },
+          "tested_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "SignatureSetting": {
+        "type": "string",
+        "description": "Setting that allows to add a signature.",
+        "enum": [
+          "signature"
+        ]
+      },
+      "EmailDomainSetting": {
+        "type": "string",
+        "description": "Setting that allows to add a custom domain. For e.g; doe.com",
+        "enum": [
+          "email_domain"
+        ]
+      },
+      "EmailAddressSetting": {
+        "type": "string",
+        "description": "Setting that allows to add an email address on the custom domain. For e.g; john@doe.com",
+        "enum": [
+          "email_address"
+        ]
+      },
+      "WhitelistEmailAddressSetting": {
+        "type": "string",
+        "description": "- Setting that specifies a list of addresses exempt from being flagged as duplicate emails.\n- An email will be flagged as a duplicate if it has the same content and is sent to the same recipient within the time frame specified in the RestrictDuplicatesWithinSetting.\n",
+        "enum": [
+          "whitelist_email_address"
+        ]
+      },
+      "RestrictDuplicatesWithinSetting": {
+        "type": "string",
+        "description": "- Restrict duplicates within:\n  * 10s\n  * 5m\n  * 1d\n  * 5000 // It converts to 5 seconds.When expressed as a numerical value, it will be interpreted as being in milliseconds.\n- Defaults to 3 minutes\n- Negative values will be treated same as positive values\n- If not set, defaults to 3 min\n- If set as 0, then the no email will be treated as a duplicate\n- Cannot have multiple values\n",
+        "enum": [
+          "restrict_duplicates_within"
+        ]
+      },
+      "SettingType": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/SignatureSetting"
+          },
+          {
+            "$ref": "#/components/schemas/EmailDomainSetting"
+          },
+          {
+            "$ref": "#/components/schemas/EmailAddressSetting"
+          },
+          {
+            "$ref": "#/components/schemas/WhitelistEmailAddressSetting"
+          },
+          {
+            "$ref": "#/components/schemas/RestrictDuplicatesWithinSetting"
+          }
+        ]
+      },
+      "Setting": {
+        "type": "object",
+        "description": "Generic setting object used for various email configuration types.\nThe applicable fields depend on the setting type:\n- **signature**: Uses `name`, `value` (plain text), and `html` (rich text)\n- **email_domain**: Uses `value` (domain name)\n- **whitelist_email_address**: Uses `value` (email address)\n- **restrict_duplicates_within**: Uses `value` (time duration)\n",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier of the setting",
+            "example": "a10bd0ff-4391-4cfc-88ee-b19d718a9bf7"
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name of the setting (used for signatures)",
+            "example": "Default Signature"
+          },
+          "org_id": {
+            "type": "string",
+            "description": "Organization ID that owns this setting",
+            "example": "org-123"
+          },
+          "type": {
+            "$ref": "#/components/schemas/SettingType"
+          },
+          "value": {
+            "type": "string",
+            "description": "The setting value. Interpretation depends on type:\n- signature: Plain text version of the signature\n- email_domain: Domain name (e.g., \"yourcompany.com\")\n- whitelist_email_address: Email address to whitelist\n- restrict_duplicates_within: Time duration (e.g., \"5m\", \"1d\")\n",
+            "example": "Best regards, The Team"
+          },
+          "html": {
+            "type": "string",
+            "description": "HTML content (only applicable for signature type)",
+            "example": "<p>Best regards,<br/><strong>The Team</strong></p>"
+          },
+          "created_at": {
+            "type": "string",
+            "description": "ISO 8601 timestamp when the setting was created",
+            "example": "2024-01-15T10:30:00Z"
+          },
+          "updated_at": {
+            "type": "string",
+            "description": "ISO 8601 timestamp when the setting was last updated",
+            "example": "2024-01-20T14:45:00Z"
+          },
+          "created_by": {
+            "type": "string",
+            "description": "User ID of the creator",
+            "example": "user-123"
+          },
+          "updated_by": {
+            "type": "string",
+            "description": "User ID of the last editor",
+            "example": "user-456"
+          }
+        },
+        "additionalProperties": true
+      },
+      "Domain": {
+        "type": "object",
+        "description": "Custom email domain configuration.",
+        "properties": {
+          "domain": {
+            "type": "string",
+            "description": "The domain name to add or verify. Can be a root domain or subdomain.\nExamples: \"yourcompany.com\", \"mail.yourcompany.com\"\n",
+            "example": "mail.yourcompany.com"
+          }
+        }
+      }
+    }
+  },
+  "servers": [
+    {
+      "url": "https://email-settings.sls.epilot.io"
+    }
+  ]
+}