{
  "openapi": "3.1.0",
  "info": {
    "title": "sending.ac Partner API",
    "version": "1.0.0",
    "summary": "Provision and manage cold email infrastructure for your customers.",
    "description": "> **Internal testing — not generally available.**\n> The Provisioning API is still in internal testing. Endpoints and payloads may\n> change without notice, and access is granted case by case. Treat this reference\n> as a preview rather than a contract, and talk to us before building against it.\n\nThe sending.ac Partner API lets integration partners white-label mailbox provisioning for their end customers. You create senders, connect domains, and the platform handles Microsoft 365 tenant setup, DNS configuration, and mailbox creation automatically.\n\n## Core concepts\n\n- **User** — an end customer on your platform.\n- **Sender** — a logical grouping of domains and mailboxes belonging to a user.\n- **Domain** — a domain connected to the platform. After you connect a domain, the platform assigns nameservers. Update the registrar, wait for propagation (up to 48 h), and the platform provisions M365 automatically.\n- **Mailbox** — an individual email account with IMAP/SMTP credentials.\n- **Operation** — every write request returns an `operation_id` you can poll or receive via webhook.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer sac_live_xxxxx\n```\n\nTokens are scoped. A request that requires a scope your token does not have will return `403 auth.insufficient_scope`.\n\n## Pagination\n\nList endpoints use cursor-based pagination. Pass `page[size]` (max 100, default 25) and `page[after]` (an opaque cursor from a previous response).\n\n## Async provisioning\n\nAll provisioning is asynchronous. A `POST` that triggers infrastructure changes returns immediately with `status: \"pending\"` and an `operation_id`. Poll `GET /v1/operations/{id}` to track progress.\n\n## Rate limits\n\nThe API enforces 120 requests per minute per token. Exceeding this returns `429 rate.quota_exceeded` with a `Retry-After` header.",
    "termsOfService": "https://sending.ac/legal/terms",
    "contact": {
      "name": "sending.ac Partner Support",
      "url": "https://sending.ac/support",
      "email": "partners@sending.ac"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://sending.ac/legal/api-license"
    }
  },
  "servers": [
    {
      "url": "https://live-api.customers.ac/v1",
      "description": "Production"
    },
    {
      "url": "https://sandbox-api.customers.ac/v1",
      "description": "Sandbox — no real infrastructure is provisioned; operations complete instantly."
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Users",
      "description": "Manage end customers on your platform."
    },
    {
      "name": "Senders",
      "description": "Group domains and mailboxes under a logical sender identity."
    },
    {
      "name": "Domains",
      "description": "Domains are specified when a sender is created and cannot be added afterwards. After creation, poll this endpoint or listen for webhooks to track nameserver assignments and provisioning status."
    },
    {
      "name": "Mailboxes",
      "description": "List mailboxes and retrieve IMAP/SMTP credentials."
    },
    {
      "name": "Operations",
      "description": "Track the progress of asynchronous provisioning workflows."
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "operationId": "listUsers",
        "tags": [
          "Users"
        ],
        "summary": "List users",
        "description": "Returns a paginated list of users belonging to your partner account.",
        "security": [
          {
            "BearerAuth": [
              "users:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "name": "filter[email]",
            "in": "query",
            "description": "Filter by exact email address.",
            "schema": {
              "type": "string",
              "format": "email"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of users.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "createUser",
        "tags": [
          "Users"
        ],
        "summary": "Create a user",
        "description": "Creates a new end customer. The `external_id` field is optional and can be used to store your platform's internal identifier for this customer.",
        "security": [
          {
            "BearerAuth": [
              "users:write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserRequest"
              },
              "example": {
                "email": "jane@acme.com",
                "company": "Acme Corp",
                "name": "Jane Doe",
                "external_id": "cust_8hTk2mN"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/users/{user_id}": {
      "get": {
        "operationId": "getUser",
        "tags": [
          "Users"
        ],
        "summary": "Retrieve a user",
        "description": "Returns a single user by ID.",
        "security": [
          {
            "BearerAuth": [
              "users:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/UserId"
          }
        ],
        "responses": {
          "200": {
            "description": "The requested user.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "updateUser",
        "tags": [
          "Users"
        ],
        "summary": "Update a user",
        "description": "Updates one or more fields on a user. Only the fields you include in the request body are changed.",
        "security": [
          {
            "BearerAuth": [
              "users:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/UserId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserRequest"
              },
              "example": {
                "company": "Acme International"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/senders": {
      "get": {
        "operationId": "listSenders",
        "tags": [
          "Senders"
        ],
        "summary": "List senders",
        "description": "Returns a paginated list of senders. You can filter by user or status.",
        "security": [
          {
            "BearerAuth": [
              "senders:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "name": "filter[user_id]",
            "in": "query",
            "description": "Return only senders belonging to this user.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "filter[status]",
            "in": "query",
            "description": "Return only senders with this status.",
            "schema": {
              "$ref": "#/components/schemas/SenderStatus"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of senders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Sender"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "createSender",
        "tags": [
          "Senders"
        ],
        "summary": "Create a sender",
        "description": "Creates a new sender with all its domains. **Domains must be specified at creation time and cannot be added afterwards.** The platform immediately begins processing each domain: assigning nameservers (asynchronous — usually within a few minutes), then waiting for DNS propagation (up to 48 hours per domain), then provisioning mailboxes automatically.\n\nAfter creation, call `GET /v1/senders/{id}/domains` to retrieve the nameserver values assigned to each domain.",
        "security": [
          {
            "BearerAuth": [
              "senders:write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSenderRequest"
              },
              "example": {
                "user_id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "name": "Acme Outbound Q1",
                "domains": [
                  "outbound.acme.com",
                  "cold.acme.com",
                  "sales.acme.com"
                ],
                "personas": [
                  {
                    "first_name": "Jane",
                    "last_name": "Doe",
                    "title": "Head of Partnerships"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sender created. Domain nameserver assignment has begun. Call `GET /v1/senders/{id}/domains` to check nameserver assignments and update your registrar.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "operation_id"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Sender"
                    },
                    "operation_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The ID of the provisioning operation. Poll `GET /v1/operations/{id}` to track progress.",
                      "example": "op_f47ac10b-58cc-4372-a567-0e02b2c3d479"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/senders/{sender_id}": {
      "get": {
        "operationId": "getSender",
        "tags": [
          "Senders"
        ],
        "summary": "Retrieve a sender",
        "description": "Returns a single sender by ID. To see domain details including nameserver assignments, call `GET /v1/senders/{id}/domains`.",
        "security": [
          {
            "BearerAuth": [
              "senders:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/SenderId"
          }
        ],
        "responses": {
          "200": {
            "description": "The requested sender.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Sender"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "updateSender",
        "tags": [
          "Senders"
        ],
        "summary": "Update a sender",
        "description": "Updates mutable fields on a sender (name, personas). You cannot change the user or status directly.",
        "security": [
          {
            "BearerAuth": [
              "senders:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/SenderId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSenderRequest"
              },
              "example": {
                "name": "Acme Outbound Q2"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sender updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Sender"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "deprovisionSender",
        "tags": [
          "Senders"
        ],
        "summary": "Deprovision a sender",
        "description": "Begins deprovisioning a sender and all of its domains and mailboxes. This is irreversible. The sender transitions to `deprovisioning` and eventually `deprovisioned`.\n\nReturns an `operation_id` to track progress.",
        "security": [
          {
            "BearerAuth": [
              "senders:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/SenderId"
          }
        ],
        "responses": {
          "202": {
            "description": "Deprovisioning started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "operation_id"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Sender"
                    },
                    "operation_id": {
                      "type": "string",
                      "format": "uuid",
                      "example": "op_b2c3d4e5-f6a7-8901-bcde-f23456789012"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/senders/{sender_id}/domains": {
      "get": {
        "operationId": "listDomains",
        "tags": [
          "Domains"
        ],
        "summary": "List domains for a sender",
        "description": "Returns all domains belonging to a sender, including their assigned nameservers and current provisioning status. Call this endpoint after creating a sender to retrieve the nameserver values you must configure at your domain registrar. Each domain proceeds independently through the provisioning lifecycle.",
        "security": [
          {
            "BearerAuth": [
              "domains:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/SenderId"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "name": "filter[status]",
            "in": "query",
            "description": "Return only domains with this status.",
            "schema": {
              "$ref": "#/components/schemas/DomainStatus"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of domains.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Domain"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/domains/{domain_id}": {
      "get": {
        "operationId": "getDomain",
        "tags": [
          "Domains"
        ],
        "summary": "Retrieve a domain",
        "description": "Returns a single domain by ID, including its nameserver assignments, health records, and current status.",
        "security": [
          {
            "BearerAuth": [
              "domains:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainId"
          }
        ],
        "responses": {
          "200": {
            "description": "The requested domain.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Domain"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "deprovisionDomain",
        "tags": [
          "Domains"
        ],
        "summary": "Deprovision a domain",
        "description": "Begins deprovisioning a single domain and its mailboxes. The domain transitions to `deprovisioning` and eventually `deprovisioned`. This does not affect other domains on the same sender.",
        "security": [
          {
            "BearerAuth": [
              "domains:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainId"
          }
        ],
        "responses": {
          "202": {
            "description": "Deprovisioning started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "operation_id"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Domain"
                    },
                    "operation_id": {
                      "type": "string",
                      "format": "uuid",
                      "example": "op_e5f6a7b8-c9d0-1234-ef56-789012345678"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/senders/{sender_id}/mailboxes": {
      "get": {
        "operationId": "listMailboxes",
        "tags": [
          "Mailboxes"
        ],
        "summary": "List mailboxes for a sender",
        "description": "Returns all mailboxes belonging to a sender. By default, credentials are **not** included. Pass `include=credentials` to include IMAP and SMTP credentials in the response.\n\n> **Security note:** Only request credentials when you need them. Credential responses are logged separately for audit purposes.",
        "security": [
          {
            "BearerAuth": [
              "mailboxes:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/SenderId"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "name": "filter[status]",
            "in": "query",
            "description": "Return only mailboxes with this status.",
            "schema": {
              "$ref": "#/components/schemas/MailboxStatus"
            }
          },
          {
            "name": "filter[domain_id]",
            "in": "query",
            "description": "Return only mailboxes on this domain.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "Comma-separated list of related resources to include. Supported values: `credentials`.",
            "schema": {
              "type": "string",
              "enum": [
                "credentials"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of mailboxes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Mailbox"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/mailboxes/{mailbox_id}": {
      "get": {
        "operationId": "getMailbox",
        "tags": [
          "Mailboxes"
        ],
        "summary": "Retrieve a mailbox",
        "description": "Returns a single mailbox by ID. Credentials are not included — use the dedicated credentials endpoint.",
        "security": [
          {
            "BearerAuth": [
              "mailboxes:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/MailboxId"
          }
        ],
        "responses": {
          "200": {
            "description": "The requested mailbox.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Mailbox"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/mailboxes/{mailbox_id}/credentials": {
      "get": {
        "operationId": "getMailboxCredentials",
        "tags": [
          "Mailboxes"
        ],
        "summary": "Retrieve mailbox credentials",
        "description": "Returns the IMAP and SMTP credentials for a single mailbox. This endpoint is logged separately for audit purposes.\n\nCredentials are only available when the mailbox status is `active`.",
        "security": [
          {
            "BearerAuth": [
              "mailboxes:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/MailboxId"
          }
        ],
        "responses": {
          "200": {
            "description": "The mailbox credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MailboxCredentials"
                    }
                  }
                },
                "example": {
                  "data": {
                    "mailbox_id": "mbx_f6a7b8c9-d0e1-2345-f678-901234567890",
                    "email": "jane@outbound.acme.com",
                    "imap": {
                      "host": "outlook.office365.com",
                      "port": 993,
                      "username": "jane@outbound.acme.com",
                      "password": "xK9#mP2$vL5nQ8wR",
                      "encryption": "SSL/TLS"
                    },
                    "smtp": {
                      "host": "smtp.office365.com",
                      "port": 587,
                      "username": "jane@outbound.acme.com",
                      "password": "xK9#mP2$vL5nQ8wR",
                      "encryption": "STARTTLS"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "Credentials not yet available. The mailbox must be in `active` status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "resource.not_ready",
                    "message": "Credentials are not available until the mailbox is active. Current status: provisioning.",
                    "doc_url": "https://docs.sending.ac/errors/resource-not-ready"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/operations": {
      "get": {
        "operationId": "listOperations",
        "tags": [
          "Operations"
        ],
        "summary": "List operations",
        "description": "Returns a paginated list of operations. Use filters to narrow results by type or status.",
        "security": [
          {
            "BearerAuth": [
              "senders:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "name": "filter[type]",
            "in": "query",
            "description": "Return only operations of this type.",
            "schema": {
              "$ref": "#/components/schemas/OperationType"
            }
          },
          {
            "name": "filter[status]",
            "in": "query",
            "description": "Return only operations with this status.",
            "schema": {
              "$ref": "#/components/schemas/OperationStatus"
            }
          },
          {
            "name": "filter[sender_id]",
            "in": "query",
            "description": "Return only operations for this sender.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of operations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Operation"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/operations/{operation_id}": {
      "get": {
        "operationId": "getOperation",
        "tags": [
          "Operations"
        ],
        "summary": "Retrieve an operation",
        "description": "Returns a single operation by ID, including its individual steps and their statuses. Poll this endpoint to track the progress of an asynchronous provisioning workflow.",
        "security": [
          {
            "BearerAuth": [
              "senders:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/OperationId"
          }
        ],
        "responses": {
          "200": {
            "description": "The requested operation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Operation"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "op_f47ac10b-58cc-4372-a567-0e02b2c3d479",
                    "type": "provision_sender",
                    "status": "in_progress",
                    "sender_id": "snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "created_at": "2026-03-24T10:00:00Z",
                    "updated_at": "2026-03-24T10:15:00Z",
                    "steps": [
                      {
                        "name": "assign_nameservers",
                        "status": "completed",
                        "started_at": "2026-03-24T10:00:01Z",
                        "completed_at": "2026-03-24T10:00:03Z",
                        "message": "Nameservers ns1.sending.ac and ns2.sending.ac assigned to outbound.acme.com."
                      },
                      {
                        "name": "detect_propagation",
                        "status": "in_progress",
                        "started_at": "2026-03-24T10:00:03Z",
                        "completed_at": null,
                        "message": "Waiting for DNS propagation. Last check: 2026-03-24T10:15:00Z."
                      },
                      {
                        "name": "provision_m365",
                        "status": "pending",
                        "started_at": null,
                        "completed_at": null,
                        "message": null
                      },
                      {
                        "name": "create_mailboxes",
                        "status": "pending",
                        "started_at": null,
                        "completed_at": null,
                        "message": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sac_live_xxxxx or sac_test_xxxxx",
        "description": "API key issued from the sending.ac partner dashboard. Live keys begin with `sac_live_`, sandbox keys with `sac_test_`."
      }
    },
    "parameters": {
      "PageSize": {
        "name": "page[size]",
        "in": "query",
        "description": "Maximum number of records to return. Default: 25, maximum: 100.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 25
        }
      },
      "PageAfter": {
        "name": "page[after]",
        "in": "query",
        "description": "Opaque cursor returned by a previous list response. Pass this to fetch the next page.",
        "schema": {
          "type": "string"
        }
      },
      "UserId": {
        "name": "user_id",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the user.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      },
      "SenderId": {
        "name": "sender_id",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the sender.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      },
      "DomainId": {
        "name": "domain_id",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the domain.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "dom_d4e5f6a7-b8c9-0123-def4-567890123456"
        }
      },
      "MailboxId": {
        "name": "mailbox_id",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the mailbox.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "mbx_f6a7b8c9-d0e1-2345-f678-901234567890"
        }
      },
      "OperationId": {
        "name": "operation_id",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the operation.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "op_f47ac10b-58cc-4372-a567-0e02b2c3d479"
        }
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "required": [
          "id",
          "email",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the user.",
            "example": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The user's email address. Must be unique across your partner account.",
            "example": "jane@acme.com"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The user's full name.",
            "example": "Jane Doe"
          },
          "company": {
            "type": [
              "string",
              "null"
            ],
            "description": "The user's company or organization name.",
            "example": "Acme Corp"
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "An optional identifier from your system. Useful for correlating sending.ac users with your own customer records.",
            "example": "cust_8hTk2mN"
          },
          "senders_count": {
            "type": "integer",
            "description": "Number of senders belonging to this user.",
            "example": 2
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the user was created.",
            "example": "2026-03-20T09:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the user was last updated.",
            "example": "2026-03-20T09:00:00Z"
          }
        }
      },
      "CreateUserRequest": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "The user's email address. Must be unique across your partner account."
          },
          "name": {
            "type": "string",
            "description": "The user's full name."
          },
          "company": {
            "type": "string",
            "description": "The user's company or organization name."
          },
          "external_id": {
            "type": "string",
            "description": "An optional identifier from your system.",
            "maxLength": 255
          }
        }
      },
      "UpdateUserRequest": {
        "type": "object",
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string",
            "description": "The user's full name."
          },
          "company": {
            "type": "string",
            "description": "The user's company or organization name."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "An optional identifier from your system. Pass `null` to clear.",
            "maxLength": 255
          }
        }
      },
      "SenderStatus": {
        "type": "string",
        "enum": [
          "pending",
          "provisioning",
          "active",
          "deprovisioning",
          "deprovisioned"
        ],
        "description": "The current lifecycle status of a sender."
      },
      "Sender": {
        "type": "object",
        "required": [
          "id",
          "user_id",
          "name",
          "status",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the sender.",
            "example": "snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "user_id": {
            "type": "string",
            "format": "uuid",
            "description": "The user this sender belongs to.",
            "example": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "name": {
            "type": "string",
            "description": "A human-readable name for this sender, chosen by the partner.",
            "example": "Acme Outbound Q1"
          },
          "status": {
            "$ref": "#/components/schemas/SenderStatus"
          },
          "personas": {
            "type": "array",
            "description": "Templates used to generate mailbox usernames on each domain.",
            "items": {
              "$ref": "#/components/schemas/Persona"
            }
          },
          "domains_count": {
            "type": "integer",
            "description": "Number of domains connected to this sender.",
            "example": 3
          },
          "mailboxes_count": {
            "type": "integer",
            "description": "Total number of mailboxes across all domains.",
            "example": 9
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-20T09:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-20T12:30:00Z"
          }
        }
      },
      "Persona": {
        "type": "object",
        "required": [
          "first_name",
          "last_name"
        ],
        "description": "A persona template. One mailbox is created per persona per domain (e.g., 3 personas x 3 domains = 9 mailboxes).",
        "properties": {
          "first_name": {
            "type": "string",
            "description": "First name used in the mailbox address.",
            "example": "Jane"
          },
          "last_name": {
            "type": "string",
            "description": "Last name used in the mailbox address.",
            "example": "Doe"
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "Job title, used for display name in the mailbox.",
            "example": "Head of Partnerships"
          }
        }
      },
      "CreateSenderRequest": {
        "type": "object",
        "required": [
          "user_id",
          "name",
          "domains"
        ],
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid",
            "description": "The user this sender belongs to."
          },
          "name": {
            "type": "string",
            "description": "A human-readable name for this sender.",
            "maxLength": 255
          },
          "domains": {
            "type": "array",
            "description": "The domains to connect to this sender. All domains must be specified at creation time. Minimum 1, maximum 50.",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "type": "string",
              "format": "hostname",
              "example": "outbound.acme.com"
            },
            "example": [
              "outbound.acme.com",
              "cold.acme.com",
              "sales.acme.com"
            ]
          },
          "personas": {
            "type": "array",
            "description": "Persona templates for generating mailboxes. You can also add these later.",
            "items": {
              "$ref": "#/components/schemas/Persona"
            }
          }
        }
      },
      "UpdateSenderRequest": {
        "type": "object",
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string",
            "description": "A human-readable name for this sender.",
            "maxLength": 255
          },
          "personas": {
            "type": "array",
            "description": "Replace all personas. This does not affect already-provisioned mailboxes.",
            "items": {
              "$ref": "#/components/schemas/Persona"
            }
          }
        }
      },
      "DomainStatus": {
        "type": "string",
        "enum": [
          "pending_nameservers",
          "awaiting_propagation",
          "connecting",
          "active",
          "failed",
          "deprovisioning",
          "deprovisioned"
        ],
        "description": "The current lifecycle status of a domain."
      },
      "Domain": {
        "type": "object",
        "required": [
          "id",
          "sender_id",
          "domain",
          "status",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the domain.",
            "example": "dom_d4e5f6a7-b8c9-0123-def4-567890123456"
          },
          "sender_id": {
            "type": "string",
            "format": "uuid",
            "description": "The sender this domain belongs to.",
            "example": "snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "domain": {
            "type": "string",
            "description": "The fully qualified domain name.",
            "example": "outbound.acme.com"
          },
          "status": {
            "$ref": "#/components/schemas/DomainStatus"
          },
          "nameservers": {
            "type": "array",
            "description": "The nameservers assigned to this domain by the platform. **Configure these at your domain registrar to proceed with provisioning.** This field is null until nameservers have been assigned (usually within a few minutes of sender creation). Poll `GET /v1/senders/{id}/domains` to check.",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "example": [
              "ns1.sending.ac",
              "ns2.sending.ac"
            ]
          },
          "health": {
            "$ref": "#/components/schemas/DomainHealth"
          },
          "mailboxes_count": {
            "type": "integer",
            "description": "Number of mailboxes on this domain.",
            "example": 3
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-20T09:05:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-21T14:30:00Z"
          }
        }
      },
      "DomainHealth": {
        "type": [
          "object",
          "null"
        ],
        "description": "DNS health check results. `null` until the domain reaches `active` status.",
        "properties": {
          "spf": {
            "type": "string",
            "enum": [
              "pass",
              "fail",
              "missing"
            ],
            "description": "SPF record status.",
            "example": "pass"
          },
          "dkim": {
            "type": "string",
            "enum": [
              "pass",
              "fail",
              "missing"
            ],
            "description": "DKIM record status.",
            "example": "pass"
          },
          "mx": {
            "type": "string",
            "enum": [
              "pass",
              "fail",
              "missing"
            ],
            "description": "MX record status.",
            "example": "pass"
          },
          "last_checked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the last health check was performed.",
            "example": "2026-03-24T08:00:00Z"
          }
        }
      },
      "ConnectDomainRequest": {
        "type": "object",
        "required": [
          "domain"
        ],
        "properties": {
          "domain": {
            "type": "string",
            "description": "The fully qualified domain name to connect. Must not already be connected to any sender on the platform.",
            "example": "outbound.acme.com",
            "pattern": "^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,}$"
          }
        }
      },
      "MailboxStatus": {
        "type": "string",
        "enum": [
          "pending",
          "provisioning",
          "active",
          "suspended",
          "deprovisioned"
        ],
        "description": "The current lifecycle status of a mailbox."
      },
      "Mailbox": {
        "type": "object",
        "required": [
          "id",
          "domain_id",
          "sender_id",
          "email",
          "status",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the mailbox.",
            "example": "mbx_f6a7b8c9-d0e1-2345-f678-901234567890"
          },
          "domain_id": {
            "type": "string",
            "format": "uuid",
            "description": "The domain this mailbox belongs to.",
            "example": "dom_d4e5f6a7-b8c9-0123-def4-567890123456"
          },
          "sender_id": {
            "type": "string",
            "format": "uuid",
            "description": "The sender this mailbox belongs to (denormalized for convenience).",
            "example": "snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The full email address of this mailbox.",
            "example": "jane@outbound.acme.com"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The display name configured on this mailbox.",
            "example": "Jane Doe"
          },
          "status": {
            "$ref": "#/components/schemas/MailboxStatus"
          },
          "credentials": {
            "description": "IMAP and SMTP credentials. Only included when `?include=credentials` is passed. Omitted by default for security.",
            "$ref": "#/components/schemas/MailboxCredentials"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-21T14:30:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-21T14:35:00Z"
          }
        }
      },
      "MailboxCredentials": {
        "type": "object",
        "description": "IMAP and SMTP connection details for a mailbox.",
        "required": [
          "mailbox_id",
          "email",
          "imap",
          "smtp"
        ],
        "properties": {
          "mailbox_id": {
            "type": "string",
            "format": "uuid",
            "example": "mbx_f6a7b8c9-d0e1-2345-f678-901234567890"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "jane@outbound.acme.com"
          },
          "imap": {
            "type": "object",
            "required": [
              "host",
              "port",
              "username",
              "password",
              "encryption"
            ],
            "properties": {
              "host": {
                "type": "string",
                "description": "IMAP server hostname.",
                "example": "outlook.office365.com"
              },
              "port": {
                "type": "integer",
                "description": "IMAP server port.",
                "example": 993
              },
              "username": {
                "type": "string",
                "description": "IMAP login username (typically the email address).",
                "example": "jane@outbound.acme.com"
              },
              "password": {
                "type": "string",
                "description": "IMAP login password.",
                "example": "xK9#mP2$vL5nQ8wR"
              },
              "encryption": {
                "type": "string",
                "enum": [
                  "SSL/TLS",
                  "STARTTLS",
                  "none"
                ],
                "description": "Connection encryption method.",
                "example": "SSL/TLS"
              }
            }
          },
          "smtp": {
            "type": "object",
            "required": [
              "host",
              "port",
              "username",
              "password",
              "encryption"
            ],
            "properties": {
              "host": {
                "type": "string",
                "description": "SMTP server hostname.",
                "example": "smtp.office365.com"
              },
              "port": {
                "type": "integer",
                "description": "SMTP server port.",
                "example": 587
              },
              "username": {
                "type": "string",
                "description": "SMTP login username (typically the email address).",
                "example": "jane@outbound.acme.com"
              },
              "password": {
                "type": "string",
                "description": "SMTP login password.",
                "example": "xK9#mP2$vL5nQ8wR"
              },
              "encryption": {
                "type": "string",
                "enum": [
                  "SSL/TLS",
                  "STARTTLS",
                  "none"
                ],
                "description": "Connection encryption method.",
                "example": "STARTTLS"
              }
            }
          }
        }
      },
      "OperationType": {
        "type": "string",
        "enum": [
          "provision_sender",
          "connect_domain",
          "deprovision_sender",
          "deprovision_domain"
        ],
        "description": "The type of async operation."
      },
      "OperationStatus": {
        "type": "string",
        "enum": [
          "pending",
          "in_progress",
          "completed",
          "failed",
          "cancelled"
        ],
        "description": "The current status of an operation."
      },
      "Operation": {
        "type": "object",
        "required": [
          "id",
          "type",
          "status",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the operation.",
            "example": "op_f47ac10b-58cc-4372-a567-0e02b2c3d479"
          },
          "type": {
            "$ref": "#/components/schemas/OperationType"
          },
          "status": {
            "$ref": "#/components/schemas/OperationStatus"
          },
          "sender_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The sender associated with this operation, if applicable.",
            "example": "snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "domain_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The domain associated with this operation, if applicable.",
            "example": "dom_d4e5f6a7-b8c9-0123-def4-567890123456"
          },
          "steps": {
            "type": "array",
            "description": "Ordered list of steps within the operation.",
            "items": {
              "$ref": "#/components/schemas/OperationStep"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-24T10:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-24T10:15:00Z"
          }
        }
      },
      "OperationStep": {
        "type": "object",
        "required": [
          "name",
          "status"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Machine-readable step identifier.",
            "example": "detect_propagation"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "in_progress",
              "completed",
              "failed",
              "skipped"
            ],
            "description": "The current status of this step."
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this step started. `null` if not yet started."
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this step completed. `null` if not yet completed."
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "A human-readable explanation of the step's current state.",
            "example": "Waiting for DNS propagation. Last check: 2026-03-24T10:15:00Z."
          }
        }
      },
      "Pagination": {
        "type": "object",
        "required": [
          "has_more"
        ],
        "description": "Cursor-based pagination metadata.",
        "properties": {
          "has_more": {
            "type": "boolean",
            "description": "`true` if there are more records after this page."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass this value as `page[after]` to fetch the next page. `null` when there are no more records.",
            "example": "eyJpZCI6InVzcl96OXk4eDd3NiJ9"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "A machine-readable error code.",
                "enum": [
                  "auth.missing_key",
                  "auth.invalid_key",
                  "auth.insufficient_scope",
                  "rate.quota_exceeded",
                  "validation.required_field",
                  "validation.invalid_value",
                  "resource.not_found",
                  "resource.already_exists",
                  "resource.not_ready",
                  "server.error"
                ]
              },
              "message": {
                "type": "string",
                "description": "A human-readable explanation of the error."
              },
              "doc_url": {
                "type": "string",
                "format": "uri",
                "description": "A link to the documentation page for this error code."
              },
              "details": {
                "type": [
                  "array",
                  "null"
                ],
                "description": "For validation errors, a list of individual field-level problems.",
                "items": {
                  "type": "object",
                  "required": [
                    "field",
                    "message"
                  ],
                  "properties": {
                    "field": {
                      "type": "string",
                      "description": "The field that caused the error, in dot notation.",
                      "example": "email"
                    },
                    "code": {
                      "type": "string",
                      "description": "A machine-readable code for this specific validation issue.",
                      "example": "validation.required_field"
                    },
                    "message": {
                      "type": "string",
                      "description": "A human-readable explanation.",
                      "example": "This field is required."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Authentication failed. The API key is missing or invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "missing_key": {
                "summary": "No API key provided",
                "value": {
                  "error": {
                    "code": "auth.missing_key",
                    "message": "No API key was provided. Include your key in the Authorization header: Bearer sac_live_xxxxx.",
                    "doc_url": "https://docs.sending.ac/errors/auth-missing-key"
                  }
                }
              },
              "invalid_key": {
                "summary": "Invalid API key",
                "value": {
                  "error": {
                    "code": "auth.invalid_key",
                    "message": "The API key provided is invalid or has been revoked.",
                    "doc_url": "https://docs.sending.ac/errors/auth-invalid-key"
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API key does not have the required scope for this operation.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "auth.insufficient_scope",
                "message": "Your API key does not have the 'senders:write' scope required for this operation.",
                "doc_url": "https://docs.sending.ac/errors/auth-insufficient-scope"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested resource does not exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "resource.not_found",
                "message": "No sender found with ID snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890.",
                "doc_url": "https://docs.sending.ac/errors/resource-not-found"
              }
            }
          }
        }
      },
      "Conflict": {
        "description": "The resource already exists.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "resource.already_exists",
                "message": "A user with email jane@acme.com already exists.",
                "doc_url": "https://docs.sending.ac/errors/resource-already-exists"
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "The request body failed validation.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation.required_field",
                "message": "The request body is missing required fields.",
                "doc_url": "https://docs.sending.ac/errors/validation-required-field",
                "details": [
                  {
                    "field": "email",
                    "code": "validation.required_field",
                    "message": "This field is required."
                  }
                ]
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "You have exceeded the rate limit. Wait and retry.",
        "headers": {
          "Retry-After": {
            "description": "Number of seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "example": 30
            }
          },
          "X-RateLimit-Limit": {
            "description": "The maximum number of requests allowed per minute.",
            "schema": {
              "type": "integer",
              "example": 120
            }
          },
          "X-RateLimit-Remaining": {
            "description": "The number of requests remaining in the current window.",
            "schema": {
              "type": "integer",
              "example": 0
            }
          },
          "X-RateLimit-Reset": {
            "description": "Unix timestamp when the rate limit window resets.",
            "schema": {
              "type": "integer",
              "example": 1711267260
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate.quota_exceeded",
                "message": "Rate limit exceeded. You may make 120 requests per minute. Retry after 30 seconds.",
                "doc_url": "https://docs.sending.ac/errors/rate-quota-exceeded"
              }
            }
          }
        }
      },
      "ServerError": {
        "description": "An unexpected error occurred on the server.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "server.error",
                "message": "An unexpected error occurred. If this persists, contact partners@sending.ac with the request ID from the X-Request-Id header.",
                "doc_url": "https://docs.sending.ac/errors/server-error"
              }
            }
          }
        }
      }
    }
  }
}