openapi: 3.0.0
info:
  description: |
    This API offers three functionalities: 
    - User management
    - Emailing

    User management can be used to add, get and modify user information. This can be done be a user with customer admin rights, without 2FA.Emailing can be used without authorization. The mail functionality can be used to sent registered emails with attachment without 2FA. Mail management, XML, can be seen by webservice users. It can be used to retrieve ticket information once the ticket id is known.

    ### Key highlights

    - **Sandbox:** Full-fledged capabilities.

    - **Security:**  HTTPS, OAuth, Rate limit

    - **Versioning:** Supports version-less API, version tight. If no version
    is provided (in header) it defaults to latest version. 


    ## [Source view](https://app.swaggerhub.com/apis/kpn/registeredemail-registeredemail/)<br/>
    [Documentation view](https://app.swaggerhub.com/apis-docs/kpn/registeredemail-registeredemail/)
    
    ---
    
    ## [KPN API Store](https://developer.kpn.com/)<br/>
    [Getting Started](https://developer.kpn.com/getting-started)

     ---
    
  version: "v.1.1.1"
  title: Registered E-mail - Registered E-mail
  contact:
    name: API Support
    email: api_developer@kpn.com
    url: 'https://developer.kpn.com/support'
  termsOfService: 'https://developer.kpn.com/legal'
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/kpn/registeredemail-registeredemail/v.1.1.1
  - url: 'https://api-prd.kpn.com/data/registeredemail/registeredemail'
externalDocs:
  description: HTTP response headers
  url: https://developer.kpn.com/documentation-response-headers

paths:
  /api/user/:
    post:
      tags:
      - 'User Management'
      description: "This endpoint creates a new user (with role user)."
      security:
        - oauth2: []
      parameters:
      - $ref: '#/components/parameters/api_version'
      requestBody:
        $ref: '#/components/requestBodies/CreateUser'
      responses:
        201:
          $ref: '#/components/responses/UserCreated'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        429:
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  /webservice/mailsender/send:
    post:
      tags:
      - 'Emailing'
      description: "With this endpoint a user can send registered emails."
      security:
        - oauth2: []
      parameters:
      - $ref: '#/components/parameters/api_version'
      requestBody:
        $ref: '#/components/requestBodies/SentEmail'
      responses:
        200:
          $ref: '#/components/responses/SentEmailResponse'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        429:
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
  parameters:
    api_version:
      in: header
      name: api-version
      schema:
        type: string
      description: API Version. If no version is provided it defaults to latest version.
      required: false
    api_version_query:
      in: query
      name: api-version
      schema:
        type: string
      description: API Version. If no version is provided it defaults to latest version.
      required: false
  requestBodies:
    CreateUser:
      required: true
      content:
        'application/json':
          schema:
            type: object
            properties:
              email_address:
                type: string
                format: email
            required:
              - email_address
    UpdateTabel:
      required: true
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/TabelInformation'
    SentEmail:
      required: true
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/email'
  responses:
    UserCreated:
      description: Created
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/UserInfo'
    UpdatedTabel:
      description: Ok
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/TabelInformation'
    CreateRowInTabel:
      description: Created
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/TabelInformation'
    SentEmailResponse:
      description: A successful delivery
      content:
        'application/json':
          schema:
            type: object
            properties:
              ticket_token:
                type: string
                example: K.SF1m-w
              ticket_url:
                type: string
                example: https://environment.aangetekendmailen.nl/webservice/dashboard/?ticket_token=K.SF1m-w&action=ticket_html&lang=nl
              message:
                type: string
                example: OK
    XMLresponse:
      description: xml body
      content:
        'application/xml':
          schema:
            $ref: '#/components/schemas/biljetten'
    BadRequestError:
      description: Bad request
      # content:
      #   'application/json':
      #     schema:
      #       $ref: '#/components/schemas/Error'
    UnauthorizedError:
      description: Authentication information is missing or invalid
      # headers:
      #   WWW_Authenticate:
      #     schema:
      #       type: string
    ForbiddenError:
      description: Forbidden
      # content:
      #   'application/json':
      #     schema:
      #       $ref: '#/components/schemas/Error'
    NotFoundError:
      description: Not found
      # content:
      #   'application/json':
      #     schema:
      #       $ref: '#/components/schemas/Error'
    MethodNotAllowedError:
      description: Method not allowed
    UnsupportedMediaTypeError:
      description: Unsupported Media Type
      # content:
      #   'application/json':
      #     schema:
      #       $ref: '#/components/schemas/Error'
    UnexpectedError:
      description: Serverside error
      # content:
      #   'application/json':
      #     schema:
      #       $ref: '#/components/schemas/Error'
  schemas:
    UserInfo:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/id'
      required:
        - id
    id:
      type: integer
      example: 154
    error:
      type: object
      properties:
        transactionId:
          type: string
          description: Transaction id of the the request
          title: Transaction ID
        status:
          type: string
          description: Status
          title: Status
        name:
          type: string
          description: Error name
          title: Error name
        message:
          type: string
          description: Error message
          title: Error message
        info:
          type: string
          description: Additional information about error
          title: Info
  
    TabelInformation:
      type: object
      properties:
        real_name:
          $ref: '#/components/schemas/real_name'
        username:
          $ref: '#/components/schemas/username'
        phone_number:
          $ref: '#/components/schemas/phone_number'
        email_address:
          $ref: '#/components/schemas/email_address'
        date_of_birth:
          $ref: '#/components/schemas/date_of_birth'
        sender_allowed:
          $ref: '#/components/schemas/sender_allowed'
      required:
        - username
        - email_address
    real_name:
      type: string
      example: "Jane Doe"
    username:
      type: string
      example: "janedoe"
    phone_number:
      type: string
      example: "0612345678"
    email_address:
      type: string
      example: "janedoe@emailaddress.com"
    date_of_birth:
      type: string
      example: "2000-12-31"
    sender_allowed:
      type: boolean
    email:
      type: object
      properties:
        message_body:
          type: string
          example: this is the email body
        sender_email:
          type: string
          example: sender@email.com
        sender_real_name:
          type: string
          example: Jane Doe
        subject:
          type: string
          example: this is the subject
        x-own-id:
          type: string
          example: id
        x-own-guid:
          type: string
          example: guid
        x-own-campaign:
          type: string
          example: campaign
        recipient_email:
          type: string
          example: recipient@email.com
        recipient_language:
          type: string
          example: en
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/attachment'
      required: 
      - message_body
      - sender_email
      - sender_real_name
      - subject
      - recipient_email
      - attachments
    attachment:
      type: object
      description: 'The attachment is Base64 encoded, the MIME type should be corresponding with the format of the actual file and the name should be correct.'
      properties:
        attachment:
          type: string
          example: BAse64E=
        attachment_name:
          type: string
          example: attachment.pdf
        attachment_type:
          type: string
          example: application/pdf
      required: 
      - attachment
      - attachment_name
      - attachment_type
    biljetten:
      type: object
      description: list of biljets
      properties:
        biljet:
          $ref: '#/components/schemas/biljet'
    biljet:
      type: object
      description: list of statusses and attachments
      properties:
        id:
          type: string
          example: K.SF1m-w
          xml:
            attribute: true
        afzender:
          type: string
          example: janedoe@xmlservice.com
          xml:
            attribute: true
        ontvanger:
          type: string
          example: johndoe@xmlservice.com
          xml:
            attribute: true
        onderwerp:
          type: string
          example: emailSubject
          xml:
            attribute: true
        customer_id:
          type: string
          example: 123456
          xml:
            attribute: true
        taal:
          type: string
          example: nl
          xml:
            attribute: true
        handtekening_nodig:
          type: string
          example: 1
          xml:
            attribute: true
        bijlagen:
          $ref: '#/components/schemas/bijlagen'
        statussen: 
          $ref: '#/components/schemas/statussen'
    bijlagen:
      type: object
      description: list of attachments
      properties:
        bijlage:
          $ref: '#/components/schemas/bijlage'
    statussen:
      type: object
      description: list of attachments
      properties:
        status:
          $ref: '#/components/schemas/status'
    bijlage:
      type: object
      description: list of attachments
      properties:
        bijlage:
          type: string
          example: example.pdf
          xml:
            attribute: true
        hash:
          type: string
          example: 'abCdeFg8hI/JLabcDEFGH8iJ86KLMNopQR0/stU6vwX='
          xml:
            attribute: true
        geaccepteerd:
          type: string
          example: 1
          xml:
            attribute: true
    status:
      type: object
      description: list of attachments
      properties:
        statusdatumtijd:
          type: string
          example: '2020-03-03 15:43:20'
          xml:
            attribute: true
        statusomschrijving:
          type: string
          example: Herinnering aangetekende mail verstuurd
          xml:
            attribute: true
        statuscode:
          type: string
          example: 95
          xml:
            attribute: true
        statusdetail:
          type: string
          example: " "
          xml:
            attribute: true