openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys ServerEmail API
  version: v1
  description: "# Introduction\n\nThe BTCPay Server Greenfield API is a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Authentication\n\nYou can authenticate either via Basic Auth or an API key. It's recommended to use an API key for better security. You can create an API key in the BTCPay Server UI under `Account` -> `Manage Account` -> `API keys`. You can restrict the API key for one or multiple stores and for specific permissions. For testing purposes, you can give it the 'Unrestricted access' permission. On production you should limit the permissions to the actual endpoints you use, you can see the required permission on the API docs at the top of each endpoint under `AUTHORIZATIONS`.\n\nIf you want to simplify the process of creating API keys for your users, you can use the [Authorization endpoint](https://docs.btcpayserver.org/API/Greenfield/v1/#tag/Authorization) to predefine permissions and redirect your users to the BTCPay Server Authorization UI. You can find more information about this on the [API Authorization Flow docs](https://docs.btcpayserver.org/BTCPayServer/greenfield-authorization/) page.\n\n# Usage examples\n\nUse **Basic Auth** to read store information with cURL:\n```bash\nBTCPAY_INSTANCE=\"https://mainnet.demo.btcpayserver.org\"\nUSER=\"MyTestUser@gmail.com\"\nPASSWORD=\"notverysecurepassword\"\nPERMISSION=\"btcpay.store.canmodifystoresettings\"\nBODY=\"$(echo \"{}\" | jq --arg \"a\" \"$PERMISSION\" '. + {permissions:[$a]}')\"\n\nAPI_KEY=\"$(curl -s \\\n     -H \"Content-Type: application/json\" \\\n     --user \"$USER:$PASSWORD\" \\\n     -X POST \\\n     -d \"$BODY\" \\\n     \"$BTCPAY_INSTANCE/api/v1/api-keys\" | jq -r .apiKey)\"\n```\n\n\nUse an **API key** to read store information with cURL:\n```bash\nSTORE_ID=\"yourStoreId\"\n\ncurl -s \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Authorization: token $API_KEY\" \\\n     -X GET \\\n     \"$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID\"\n```\n\nYou can find more examples on our docs for different programming languages:\n- [cURL](https://docs.btcpayserver.org/Development/GreenFieldExample/)\n- [Javascript/Node.Js](https://docs.btcpayserver.org/Development/GreenFieldExample-NodeJS/)\n- [PHP](https://docs.btcpayserver.org/Development/GreenFieldExample-PHP/)\n\n"
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: https://{btcpay-host}
  description: Your BTCPay Server instance
  variables:
    btcpay-host:
      default: mainnet.demo.btcpayserver.org
      description: The hostname of your BTCPay Server instance
security:
- API_Key: []
  Basic: []
tags:
- name: ServerEmail
  description: Server Email Settings operations
paths:
  /api/v1/server/email:
    get:
      tags:
      - ServerEmail
      summary: Get server email settings
      description: Retrieve the email settings configured for the server. The password field will be masked if present.
      operationId: ServerEmail_GetSettings
      responses:
        '200':
          description: Server email settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerEmailSettings'
        '403':
          description: Forbidden - Insufficient permissions
      security:
      - API_Key:
        - btcpay.server.canmodifyserversettings
        Basic: []
    put:
      tags:
      - ServerEmail
      summary: Update server email settings
      description: Update server's email settings.
      operationId: ServerEmail_UpdateSettings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServerEmailSettings'
      responses:
        '200':
          description: Server email settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerEmailSettings'
        '400':
          description: Invalid request or email format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden - Insufficient permissions
      security:
      - API_Key:
        - btcpay.server.canmodifyserversettings
        Basic: []
components:
  schemas:
    UpdateEmailSettings:
      allOf:
      - $ref: '#/components/schemas/EmailSettingsBase'
      - type: object
        properties:
          password:
            type: string
            description: SMTP password. Keep null or empty to not update it.
            nullable: true
            example: MyS3cr3t
    GetEmailSettings:
      allOf:
      - $ref: '#/components/schemas/EmailSettingsBase'
      - type: object
        properties:
          passwordSet:
            type: boolean
            description: '`true` if the password has been set.'
    ProblemDetails:
      type: object
      description: Description of an error happening during processing of the request
      properties:
        code:
          type: string
          nullable: false
          description: An error code describing the error
        message:
          type: string
          nullable: false
          description: User friendly error message about the error
    EmailSettingsBase:
      type: object
      properties:
        from:
          type: string
          description: The sender email address
          example: sender@gmail.com
        server:
          type: string
          description: SMTP server host
          example: smtp.gmail.com
        port:
          type: integer
          description: SMTP server port
          example: 587
        login:
          type: string
          description: SMTP username
          example: John.Smith
        disableCertificateCheck:
          type: boolean
          description: Disable TLS certificate security checks
          example: false
    UpdateServerEmailSettings:
      allOf:
      - $ref: '#/components/schemas/UpdateEmailSettings'
      - type: object
        properties:
          enableStoresToUseServerEmailSettings:
            type: boolean
            description: Indicates if stores can use server email settings
    GetServerEmailSettings:
      allOf:
      - $ref: '#/components/schemas/GetEmailSettings'
      - type: object
        properties:
          enableStoresToUseServerEmailSettings:
            type: boolean
            description: Indicates if stores can use server email settings
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'BTCPay Server API key. Format: ''token {apiKey}'''
    Basic:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with email and password
externalDocs:
  description: Check out our examples on how to use the API
  url: https://docs.btcpayserver.org/Development/GreenFieldExample/