openapi: '3.0.1'
info:
  description: >-
    Use this API to manage the Notification Service related operations viz.
    publishing the messages, templating the request, selecting the communication
    channel and then sending the message to the specified recipient using
    notification's recipient service (one of the services from the NS module).

    ## Limitations
      - The service may decide to throttle API requests temporarily returning a 429 status code.
    
    ## Generic Errors
      The following generic error codes might occur at any of the specified operation.Generic errors are prefixed with 'mdsp.core.generic.'.
      - 204: noContent
      - 400: invalidParameter
      - 400: invalidRequestBodyProperty
      - 400: missingParameter
      - 400: missingRequestBodyProperty
      - 401: unauthorized
      - 403: forbidden
      - 404: noMatch
      - 409: conflict
      - 429: tooManyRequests
      - 500: internalServerError
    See the MindSphere API documentation generic errors page for more information.

  version: '3.4.1'
  x-visibility: external
  title: Notification API

servers:
  - url: https://api.eu1.siemens.app/api/notification-1000001700/v3
    description: Xcelerator compliant URL

tags:
  - name: Publish Operations
    description: >-
      <b>Operations focussed on publishing the messages for several channels like Email , SMS and Push Notification
  - name: Recipient Management Operations
    description: >-
      <b>Operations focussed on managing the recipients.
  - name: Address Type Operations
    description: >-
      <b>Operations focussed on fetching the types of the address.
  - name: Template Management Operations
    description: >-
      <b> Operations focussed on managing the templates and template sets.
  - name: Communication Channel Operations
    description: >-
      <b>Operation focussed on fetching the channel to be used to communicate viz. EMAIL OR SMS OR PUSH.
  - name: Parameter Type Operations
    description: >-
      <b>Operations focussed to handle all supported parameter types used in the template.
  - name: Template Parameter Operations
    description: >-
      <b>Operations focussed to retrieve template related parameters.
  - name: Communication Category Management Operations
    description: Communication Category Controller
  - name: Audit Operations
    description: >-
      <b> Operations focussed on tracking the message and its completion status.
  - name: Certificate Store Operations
    description: >-
      <b>Operations focussed on managing the public certificates of the users
      for the provided email id
  - name: Bounced Email Management Operations
    description: >-
      <b>Operations focussed on managing the invalid emails, which were blacklisted by notification service on account of causing bounce event in SES.
  - name: Recipient Group Management Operations
    description: >-
      <b>Operations focussed on managing the recipient groups

paths:
  /audit/searchauditstatus:
    post:
      tags:
        - Audit Operations
      security:
        - nose:
          - nose.ac
      summary: search the audit status from Database.
      description: Search audit status in Database based on AuditRequest object input
      operationId: searchAuditStatusUsingPOST_2
      requestBody:
        description: Object to provide filter condition for the searching audit status."startTimeRange" and "endTimeRange" are mandatory and the format for the input is "yyyy-MM-dd HH:mm:ss".
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuditResponse'
        'default':
          description: Other error with any status code and response body format.

  /communicationcategories/:
    get:
      tags:
        - Communication Category Management Operations
      security:
        - nose:
          - nose.ac
      summary: Get all communication categories
      description: 'To get all communication categories '
      operationId: getAllCommunicationMessageCategoriesUsingGET_2
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CommunicationCategory'
    post:
      tags:
        - Communication Category Management Operations
      security:
        - nose:
          - nose.ac
      summary: Creating communication category
      description: To create communication category
      operationId: createCommunicationMessageCategoryUsingPOST_2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCommunicationCategory'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: integer
                format: int64
                description: category id
        'default':
          description: Other error with any status code and response body format.
    delete:
      tags:
        - Communication Category Management Operations
      security:
        - nose:
          - nose.ac
      summary: Deleting communication category
      description: Delete categories by category id's
      operationId: deleteCommunicationMessageCategoryUsingDELETE_2
      parameters:
        - name: categoryIds
          in: query
          description: Accepted comma seperated category ids
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: integer
                format: int64
        'default':
          description: Other error with any status code and response body format.

  /communicationcategories/unsubscribe/recipients:
    post:
      tags:
        - Communication Category Management Operations
      security:
        - nose:
          - nose.ac
      summary: Unsubscribe the recipients from category
      description: To unsubscribe the recipients under category
      operationId: unsubscribeRecipientsUsingPOST_2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnsubscribeRecipientsCategory'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        'default':
          description: Other error with any status code and response body format.

  '/communicationcategories/{id}':
    get:
      tags:
        - Communication Category Management Operations
      security:
        - nose:
          - nose.se
          - nose.ac
      summary: Get communication category by category ID
      description: To get communication category by category ID
      operationId: getCommunicationMessageCategoryUsingGET_2
      parameters:
        - name: id
          in: path
          description: Communication category ID
          required: true
          schema:
            type: integer
            format: int64
        - name: recGroup
          in: query
          description: To fetch recipient group's. Accecpted values are true/false (optional parameter)
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCommunicationCategory'
        'default':
          description: Other error with any status code and response body format.
    put:
      tags:
        - Communication Category Management Operations
      security:
        - nose:
          - nose.ac
      summary: Updating communication category
      description: To update category by category id
      operationId: updateCommunicationMessageCategoryUsingPATCH_2
      parameters:
        - name: id
          in: path
          description: Communication category ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCommunicationCategory'
      responses:
        '204':
          description: Updated
          content:
            application/json:
              schema:
                type: object
        'default':
          description: Other error with any status code and response body format.

  '/communicationcategories/search/':
    get:
      tags:
        - Communication Category Management Operations
      security:
        - nose:
          - nose.ac
      summary: Listing CommunicationCategories with specific fields
      description: To get all categories with the specific field information
      operationId: getListing CommunicationCategories with specific fields
      parameters:
        - name: fields
          in: query
          description: supported fields (recipient_count,channels). Comma seperated fields are accepted
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCommunicationCategories'
        'default':
          description: Other error with any status code and response body format.

  '/communicationcategories/bouncedEmailIds':
    get:
      tags:
        - Bounced Email Management Operations
      security:
        - nose:
          - nose.se
          - nose.ac
      summary: Lists the blacklisted email addresses of the tenant, which were bounced by SES since they were invalid ones.
      description: To get all blacklisted email addresses of the tenant
      operationId: get Lists of blacklisted email addresses of the tenant.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BounceEmailObj'
        'default':
          description: Other error with any status code and response body format.
    delete:
      tags:
        - Bounced Email Management Operations
      security:
        - nose:
          - nose.ac
      summary: Delete blacklisted email addresses of the tenant, which are no more invalid and can be considered as valid email addresses for sending emails.
      description: To delete  blacklisted email addresses of the tenant
      operationId: To delete  blacklisted email addresses of the tenant
      requestBody:
        required: true
        description: >-
          It's a JSON String message which need to provide in the following format
           <b>{"emailList" : ["abc@siemens.com","xyz@siemens.com"]}</b>
        content:
          application/json:
            schema:
              type: object
              properties:
                emailList:
                  type: array
                  items:
                    type: string
                    example: "example@abc.com"
                    description: invalid blacklisted email address which needs to be whitelisted
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                example: "Deleted successfully"
        'default':
          description: Other error with any status code and response body format.

  /recipient/addresstype:
    get:
      tags:
        - Address Type Operations
      security:
        - nose:
          - nose.ac
      summary: Get all address types for the recipient.
      description: Get all address types for the recipient.
      operationId: getAddressTypes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  /recipient/:
    post:
      tags:
        - Recipient Management Operations
      security:
        - nose:
          - nose.ac
      summary: Create a recipient.
      description: >-
        API to create a recipient with recipient details like email,
        telephone number etc.
        <p> <b>Note:</b> Due to regulatory restrictions, sending <b>SMS</b> using the MindSphere notification service is <b>suspended</b> if at least one of the target recipients is from the <b>India</b> region. Recipients from the India region shall use other notification options (e-mail or push notification). </p>
      operationId: createRecipient
      requestBody:
        description: It contains the recipient name and address details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecipient'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: integer
                format: int64
                description: Id of created recipient
                example: 806
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RestrictedRegion'
        'default':
          description: Other error with any status code and response body format.
    put:
      tags:
        - Recipient Management Operations
      security:
        - nose:
          - nose.ac
      summary: Update a recipient.
      description: Update recipient details like email/phone
        <p> <b>Note:</b> Due to regulatory restrictions, sending <b>SMS</b> using the MindSphere notification service is <b>suspended</b> if at least one of the target recipients is from the <b>India</b> region. Recipients from the India region shall use other notification options (e-mail or push notification). </p>
      operationId: updateRecipientDetail
      requestBody:
        description: <b>It contains the recipient details to be updated.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRecipientDetails'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RestrictedRegion'
        'default':
          description: Other error with any status code and response body format.

  /recipient/search:
    post:
      tags:
        - Recipient Management Operations
      security:
        - nose:
          - nose.ac
      summary: Search a recipient.
      description: Search a recipient based on the recipient name.
      operationId: searchRecipient
      requestBody:
        description: <b>it contains the recipient name.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  '/recipient/{id}':
    get:
      tags:
        - Recipient Management Operations
      security:
        - nose:
          - nose.ac
      summary: Get a recipient details based on the recipient ID.
      description: Gets a recipient details based on the recipient ID.
      operationId: Get Recipient
      parameters:
        - name: id
          in: path
          description: Recipient ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.
    delete:
      tags:
        - Recipient Management Operations
      security:
        - nose:
          - nose.ac
      summary: Delete Recipient
      description: Delete a recipient by ID
      operationId: Delete Recipient
      parameters:
        - name: id
          in: path
          description: Recipient ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  /communicationchannel/:
    get:
      tags:
        - Communication Channel Operations
      security:
        - nose:
          - nose.ac
      summary: >-
        Use this api to get available communication types viz. EMAIL, SMS or
        PUSH.
      description: 'Use this api to get active communication types viz. EMAIL, SMS or PUSH.'
      operationId: getAllCommunicationTypes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'

  /paramtype/:
    get:
      tags:
        - Parameter Type Operations
      security:
        - nose:
          - nose.ac
      summary: Use this api to get all available param types.
      description: It gets list of all available param types.
      operationId: GetAllParamTypes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  /template/:
    post:
      tags:
        - Template Management Operations
      security:
        - nose:
          - nose.ac
      summary: >-
        Use this api to create templates for a new template set using
        templateFiles and templateInfo.
      description: >-
        It inserts templates to a new template set using <b>templateFiles</b>
        and <b>templateInfo</b>.
      operationId: createTemplates
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - templateFiles
                - templateInfo
              properties:
                templateFiles:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: It's a list of template files to be inserted into database.Allowed file formats are '.htm' and '.html' .Maximum allowed size per file is 16777215 bytes.
                templateInfo:
                  type: string
                  description: >-
                    It's a JSON String message which has structure of
                    TemplateProcessInfo object.It contains template params, template set
                    and communication channel related details for templates processing.
                    Please refer below sample for String message input.
                    <b>templatesetName</b> & <b>templateChannelAndFile</b> are mandatory keys in the json.
                    
                    Notes: 
                    1>'templateChannelAndFile.[].operation' key is optional and only allowed value for this key is 'ADD'.
                    2>Template creation is allowed only for a new template set.Use Template update api if addtion of new templates is required for existing templateset.
                    3>'templateParam' is optional if we do not have any dynamic parameter to replace in templates. In case of dynamic params we have to provide all four keys i.e. 'paramName','defaultValue','placeHolderName' and 'paramTypeId' for each template param.
                    4>(i)'paramName' is the reference name of a placeholder in database table.
                    (ii)'placeHolderName' is the name of variable(template param) in template file.
                    (iii) 'defaultValue' is the example value of the template param.
                    (iv) 'paramTypeId': use /paramtype/ api to chosse appropriate pram type id.

                        {"templateParam": [
                          {
                            "paramName": "Tenant Name",
                            "defaultValue": "Mindsphere User",
                            "placeHolderName": "name",
                            "paramTypeId": 4
                          },
                          {
                            "paramName": "Link",
                            "defaultValue": "URL",
                            "placeHolderName": "url",
                            "paramTypeId": 5
                          },
                          {
                            "paramName": "MailToUnsubscribe",
                            "defaultValue": "admin@mindsphere.io",
                            "placeHolderName": "mailToUnsubscribe",
                            "paramTypeId": 4
                          }
                        ],
                      
                        "templatesetName": "Hardware Activation",
                      
                        "templateChannelAndFile": [
                          {
                            "communicationChannel": 1,
                            "fileName": "hardwareActivationTemplateNew.html",
                            "operation" : "ADD"
                          },
                          {
                            "communicationChannel": 3,
                            "fileName": "URL.html",
                            "operation" : "ADD"
                          }
                        ]}
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTemplate'
        'default':
          description: Other error with any status code and response body format.

  '/template/templatecontent/{templateId}':
    get:
      tags:
        - Template Management Operations
      security:
        - nose:
          - nose.ac
      summary: Use this api to get template content for a requested template ID.
      description: It gets template content for a requested templateId.
      operationId: getTemplateContent
      parameters:
        - name: templateId
          in: path
          description: It's a Long type templateID used to fetch the template content.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  '/template/templateidlist/{templatesetId}':
    get:
      tags:
        - Template Management Operations
      security:
        - nose:
          - nose.ac
      summary: Use this api to get list of template IDs for a requested template set.
      description: It gets lists of template IDs for a requested template set Id.
      operationId: getTemplateIdList
      parameters:
        - name: templatesetId
          in: path
          description: It's a Long type templatesetID used to fetch list of template IDs.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  /template/templatelistdetails:
    get:
      tags:
        - Template Management Operations
      security:
        - nose:
          - nose.ac
      summary: >-
        Use this api to get all template sets along with associated template
        details.
      description: It gets list of all template sets and associated templates.
      operationId: getAllTemplateList
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  /template/templatesets:
    get:
      tags:
        - Template Management Operations
      security:
        - nose:
          - nose.ac
      summary: >-
        Use this api to get list of templateSetObj's for matching template set
        name.
      description: >-
        It is a search operation which gets list of Template sets for matching
        input template set name.
      operationId: GetTemplateSets
      parameters:
        - name: templatesetname
          in: query
          description: It's a String type templatesetName used to search template sets.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  '/template/templatesets/{templatesetId}':
    get:
      tags:
        - Template Management Operations
      security:
        - nose:
          - nose.ac
      summary: Use this api to get templateSetObj for a requested template set Id.
      description: It gets Template set details for a given template set Id.
      operationId: GetTemplateSetById
      parameters:
        - name: templatesetId
          in: path
          description: It's a Long type templatesetID used to fetch Template set details.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  '/template/{templatesetId}':
    delete:
      tags:
        - Template Management Operations
      security:
        - nose:
          - nose.ac
      summary: Use this api to delete a template set for a requested template set Id.
      description: It deletes Template set from the database.
      operationId: DeleteTemplateset
      parameters:
        - name: templatesetId
          in: path
          description: It's a Long type templatesetID used to delete Template set.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.
    put:
      tags:
        - Template Management Operations
      security:
        - nose:
          - nose.ac
      summary: Use this api to update details of a template set.
      description: >-
        It updates template, template param and template set details for a given
        template set.
      operationId: UpdateTemplates
      parameters:
        - name: templatesetId
          in: path
          description: It's a Long type templatesetID used for template update.
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - templateInfo
              properties:
                templateFiles:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: It's a list of template files to be inserted into database.Allowed file formats are '.htm' and '.html' .Maximum allowed size per file is 16777215 bytes.
                templateInfo:
                  type: string
                  description: >-
                    It's a JSON String message which has structure of
                    TemplateProcessInfo object. It contains template params, template set
                    and communication channel related details for templates processing.
                    Please refer below sample for String message input.
                    <b>templatesetName</b> is mandatory key in the json.
                    
                    Notes: 
                    1>'templateChannelAndFile.[].operation' key is mandatory for template file addition/deletion and allowed values for this key are 'ADD' and 'DELETE'.
                    2> 'templateChannelAndFile.[].fileName' key is mandatory for template addition and not required for template deletion.
                    3> Updating template set name is supported with this api.
                    4> Only addition operation is supported for 'templateParam'. We can delete all template parameters for a templateset using 'DeleteTemplate' api. In case of param addition we have to provide all four keys i.e. 'paramName','defaultValue','placeHolderName' and 'paramTypeId' for each template param.
                    5>(i)'paramName' is the reference name of a placeholder in database table.
                    (ii)'placeHolderName' is the name of variable(template param) in template file.
                    (iii) 'defaultValue' is the example value of the template param.
                    (iv) 'paramTypeId': use /paramtype/ api to chosse appropriate pram type id.

                        {"templateParam": [
                          {
                            "paramName": "Tenant Name",
                            "defaultValue": "Mindsphere User",
                            "placeHolderName": "name",
                            "paramTypeId": 4
                          },
                          {
                            "paramName": "Link",
                            "defaultValue": "URL",
                            "placeHolderName": "url",
                            "paramTypeId": 5
                          },
                          {
                            "paramName": "MailToUnsubscribe",
                            "defaultValue": "admin@mindsphere.io",
                            "placeHolderName": "mailToUnsubscribe",
                            "paramTypeId": 4
                          }
                        ],
                      
                        "templatesetName": "Hardware Activation",
                      
                        "templateChannelAndFile": [
                          {
                            "communicationChannel": 1,
                            "fileName": "hardwareActivationTemplateNew.html",
                            "operation" : "ADD"
                          },
                          {
                            "communicationChannel": 3,
                            "operation" : "DELETE"
                          }
                        ]}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  '/templateparam/{templatesetId}':
    get:
      tags:
        - Template Parameter Operations
      security:
        - nose:
          - nose.ac
      summary: >-
        Use this api to get available template params for a requested template
        set id.
      description: >-
        <b>It gets list of active template parameters for a requested template
        set id.
      operationId: getTemplateParams
      parameters:
        - name: templatesetId
          in: path
          description: It's a Long type templatesetID used to fetch template parameters.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  /publisher/messages:
    post:
      tags:
        - Publish Operations
      security:
        - nose:
          - nose.se
      summary: Publishes the JSON String message to Queue.
      description: >-
        It publishes the message that will trigger to send the Email ,SMS and push notification channels.
        <p> <b>Note:</b> Due to regulatory restrictions, sending <b>SMS</b> using the MindSphere notification service is <b>suspended</b> if at least one of the target recipients is from the <b>India</b> region. Recipients from the India region shall use other notification options (e-mail or push notification). </p>
      operationId: publishMessages
      requestBody:
        required: true
        description: >-
          Request body. Refer **PublishEmailContent** model definition.
          
          Following points need to be considered - 
          
          1. The "body" key is mandatory but place holders depend upon the template 
          parameter. If there is no template as part of message's Category definition, then provide the mail body content in "message" placeholder.
          
          2. The parameter **messageCategoryId** is optional. For a message without **messageCategoryId**, only the email channel is active and **recipientTo**, **from**, **subject** and **message** are mandatory.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishEmailContent'
      responses:
        '204':
          description: NO_CONTENT
          content:
            application/json:
              schema:
                type: string
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RestrictedRegion'
        'default':
          description: Other error with any status code and response body format.

  /broadcastEmails:
    post:
      tags:
        - Publish Operations
      security:
        - nose:
          - nose.se
      summary: Create a broadcast email message.
      description: Broadcasts the notification message via email to all recipients of a tenant/sub-tenant. The recipient tenant is determined from the access token claim _**ten**_, if not specified explicitly.
      operationId: broadcastEmail
      parameters:
        - $ref: '#/components/parameters/broadcastType'
        - name: tenantId
          in: query
          description: The tenant to which the broadcast email is addressed to. If not specified, the calling tenant is addressed.
          schema:
            type: string
        - name: subTenantId
          in: query
          description: The sub-tenant id which identifies a sub-tenant within the addressed tenant. This parameter should be specified if **subTenantMembersOnly** is used as broadcast type. The success of the mails sent in this case depends on the correctness of the value of the subTenantId provided in the request. The request can be discarded by the system, if an invalid subTenantId is found in the request.
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - messageData
              properties:
                messageData:
                  type: string
                  description: It contains the details required for sending broadcast emails for a tenant. Recipients configured in message category are ignored, in case this is used for an existing message category. Please refer to **BroadcastEmailContent** object in definitions.
      responses:
        '200':
          description: The notification message has been successfully queued for dispatch via email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        'default':
          description: Other error with any status code and response body format.

  /certificatestore/:
    get:
      tags:
        - Certificate Store Operations
      security:
        - nose:
          - nose.ac
      summary: Get all email ids for a specific tenant user. Tenant information will be fetched from the User token while calling through Mindsphere Gateway.
      description: Retrieves all recipient email ids for calling tenant user.
        <b>Note - Api will return list of all available email ids, if tenant value is 'siemens'. </b>
      operationId: getAllEmailIds
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.
    post:
      tags:
        - Certificate Store Operations
      security:
        - nose:
          - nose.ac
      summary: To Upload a valid recipient's public certificate into DB.
      description: <b>Uploads recipient's public certificate into the system.
      operationId: uploadCertificate
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - emailid
                - ownerid
              properties:
                file:
                  type: string
                  format: binary
                  description: Certificate file provided by the user in <b>".cer" format.
                emailid:
                  type: string
                  description: User's email id.
                ownerid:
                  type: string
                  description: User's owner id. Alphanumeric value is expected for this.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: integer
                format: int64
        'default':
          description: Other error with any status code and response body format.

  '/certificatestore/{emailid}':
    put:
      tags:
        - Certificate Store Operations
      security:
        - nose:
          - nose.ac
          - nose.se
      summary: Update the recipient's public certificate for the specified email id.
      description: <b>Updates recipient's public certificate for the provided email id.
      operationId: Update Certificate
      parameters:
        - name: emailid
          in: path
          description: <b>Tenant user's email id.
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - ownerid
              properties:
                file:
                  type: string
                  format: binary
                  description: <b>File provided by the tenant user in ".cer" format.
                ownerid:
                  type: string
                  description: <b>Tenant user's owner id. Alphanumeric value is expected for this key.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.
    delete:
      tags:
        - Certificate Store Operations
      security:
        - nose:
          - nose.ac
      summary: Delete a Certificate for the provided email id.
      description: >-
        <b>Deletes the recipient's public certificate from the system for the
        provided email id.
      operationId: Delete Certificate
      parameters:
        - name: emailid
          in: path
          description: <b>Deletes the certificate for this email id.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  /recipient/recipientgroup:
    post:
      tags:
        - Recipient Group Management Operations
      security:
        - nose:
          - nose.ac
      summary: Create a recipient group
      description: Create a recipient group
      operationId: Create Recipient Group
      requestBody:
        description: Create recipient group request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecipientGroupRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.
    put:
      tags:
        - Recipient Group Management Operations
      security:
        - nose:
          - nose.ac
      summary: Update recipient group
      description: Update a recipient group
      operationId: Update Recipient Group
      requestBody:
        description: Update recipient group request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRecipientGroupRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  /recipient/recipientgroup/search:
    post:
      tags:
        - Recipient Group Management Operations
      security:
        - nose:
          - nose.ac
      summary: Search Recipient Group
      description: Search a recipient group based on group name
      operationId: Search Recipient Group
      requestBody:
        description: Search request with group name
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

  '/recipient/recipientgroup/{id}':
    get:
      tags:
        - Recipient Group Management Operations
      security:
        - nose:
          - nose.ac
      summary: Get a recipient group
      description: Get a recipient group by ID
      operationId: Get Recipient Group
      parameters:
        - name: id
          in: path
          description: Recipient group ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.
    delete:
      tags:
        - Recipient Group Management Operations
      security:
        - nose:
          - nose.ac
      summary: Delete a recipient group
      description: Delete a recipient group by ID
      operationId: Delete Recipient Group
      parameters:
        - name: id
          in: path
          description: Recipient group ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        'default':
          description: Other error with any status code and response body format.

components:
  schemas:
    RecipientAddress:
      type: object
      properties:
        address:
          type: string
          description: This is the actual address like email ids, phone number, push notification configuration details. Email - can include alphanumeric and special characters like (_), (.) and (@).Phone number - Should conform to E.164 format Push Notification â€" Should be a valid json, with quotes/special characters properly escaped.
        addresstypeid:
          type: integer
          format: int64
          description: This number denotes the type of the address eg. 1 - Personal email, 2 - Office email. Use the List Address Types API to get a complete list of supported types. Currently, emails, phone numbers and Android/IOS push notification app details are supported.

    UpdateRecipientDetails:
      type: object
      properties:
        recipientdetail:
          type: array
          items:
            $ref: '#/components/schemas/RecipientAddress'
        recipientid:
          type: integer
          format: int64
          description: The unique identifier of the recipient to be updated
        recipientname:
          type: string
          description: The name of the recipient. Alphabets (UTF-8) with spaces are allowed for a name. Recipient names are unique within a tenant. Do not use this field if you do not want to update the name.

    SearchRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the record to be matched. If the value for this field is blank string (""), then the API lists all the records for the tenant.

    CreateRecipient:
      type: object
      properties:
        recipientdetail:
          type: array
          items:
            $ref: '#/components/schemas/RecipientAddress'
        recipientname:
          type: string
          description: The name of the recipient. Alphabets (UTF-8) with spaces are allowed for a name. Recipient names are unique within a tenant

    CreateCategoryRecipient:
      type: object
      properties:
        position:
          type: string
          enum:
            - TO
            - CC
            - BCC
        recipientGroupId:
          type: integer
          format: int64
        recipientId:
          type: integer
          format: int64

    UpdateCategoryRecipient:
      type: object
      properties:
        position:
          description: Position of an email
          type: string
          enum:
            - TO
            - CC
            - BCC
        recipientGroupId:
          type: integer
          format: int64
        operation:
          description: ADD - Supports new/merge , DELETE - delete the record
          type: string
          enum:
            - ADD
            - DELETE
        recipientId:
          type: integer
          format: int64

    UnsubscribeCategoryRecipient:
      type: object
      properties:
        recipientId:
          type: integer
          format: int64
          description: Recipient id

    ChannelNames:
      type: string

    GetCategoryRecipient:
      type: object
      properties:
        position:
          type: string
          description: Position of an email
          enum:
            - TO
            - CC
            - BCC
        recipientDetails:
          type: array
          items:
            $ref: '#/components/schemas/GetCategoryRecipientDetails'
        recipientId:
          type: integer
          format: int64
          description: Recipient id
        recipientName:
          type: string
          description: Recipient name

    GetCategoryRecipientGroup:
      type: object
      properties:
        position:
          description: Position of an email
          type: string
          enum:
            - TO
            - CC
            - BCC
        recipientGroupId:
          type: integer
          format: int64
          description: Recipient group id
        recipientGroupName:
          type: string
          description: Recipient group name

    GetCategoryRecipientDetails:
      type: object
      properties:
        address:
          type: string
          description: email id /mobile number / push notification id
        commChannelName:
          type: string
          enum:
            - Email
            - SMS
            - Push Notification
        recipientAddressTypeName:
          type: string
          description: Type of email or mobile (Personal email or personal number or official number)
        recipientId:
          type: integer
          format: int64

    CommunicationCategory:
      type: object
      properties:
        msgCategoryId:
          type: integer
          format: int64
          description: Message category id
        msgCategoryName:
          type: string
          description: Message category name
        priority:
          type: integer
          description: Priority of the category

    CreateCommunicationCategory:
      type: object
      properties:
        from:
          type: string
          description: Accepted only Application Name. In back end from email will be generated in a form of ApplicationName.tenantid@mindsphere.io
        msgCategoryName:
          type: string
          description: Accepted alphanumeric characters only
        priority:
          type: integer
          enum:
            - 1
            - 3
            - 5
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/CreateCategoryRecipient'
        subject:
          type: string
          description: Accepted alphanumeric characters only
        templates:
          type: array
          items:
            $ref: '#/components/schemas/CreateCategoryTemplate'

    UpdateCommunicationCategory:
      type: object
      properties:
        from:
          type: string
          description: Accepted only Application Name. In back end from email will be generated in a form of ApplicationName.tenantid@mindsphere.io
        msgCategoryName:
          type: string
          description: Accepted alphanumeric characters only
        priority:
          type: integer
          enum:
            - 1
            - 3
            - 5
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/UpdateCategoryRecipient'
        subject:
          type: string
          description: Accepted alphanumeric characters only
        templates:
          type: array
          items:
            $ref: '#/components/schemas/UpdateCategoryTemplate'

    SearchCommunicationCategories:
      type: object
      properties:
        msgCategoryName:
          type: string
          description: Default value
        msgCategoryId:
          type: integer
          format: int64
          description: Default value
        recipientCount:
          type: integer
          format: int64
          description: Number of recipients for category
        recipientGroupCount:
          type: integer
          format: int64
          description: Number of recipient groups for category
        channelNames:
          type: array
          description: Channel name list for category like email,SMS,Push notificaiton
          items:
            $ref: '#/components/schemas/ChannelNames'

    UnsubscribeRecipientsCategory:
      type: object
      properties:
        msgCategoryId:
          type: integer
          format: int64
          description: Message category id
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/UnsubscribeCategoryRecipient'

    GetCommunicationCategory:
      type: object
      properties:
        createdby:
          type: string
          description: Tenant id
        from:
          type: string
          description: ApplicationName.TenantName@Mindsphere.io
        msgCategoryId:
          type: integer
          format: int64
          description: Category id
        msgCategoryName:
          type: string
          description: Category Name
        priority:
          type: integer
          format: int32
          enum:
            - 1
            - 3
            - 5
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/GetCategoryRecipient'
        recipientGroups:
          type: array
          items:
            $ref: '#/components/schemas/GetCategoryRecipientGroup'
        subject:
          type: string
          description: Email subject
        templates:
          type: array
          items:
            $ref: '#/components/schemas/GetCategoryTemplate'

    GetCategoryTemplate:
      type: object
      properties:
        commChannelName:
          type: string
          enum:
            - Email
            - SMS
            - Push Notification
        templateId:
          type: integer
          format: int64
          description: Template id
        templatesetId:
          type: integer
          format: int64
          description: Template set id
        templatesetName:
          type: string
          description: Template set name

    CreateCategoryTemplate:
      type: object
      properties:
        commChannelName:
          type: string
          enum:
            - Email
            - SMS
            - Push Notification
        templateId:
          type: integer
          format: int64
        templatesetId:
          type: integer
          format: int64

    UpdateCategoryTemplate:
      type: object
      properties:
        commChannelName:
          type: string
          enum:
            - Email
            - SMS
            - Push Notification
        templateId:
          type: integer
          format: int64
        templatesetId:
          type: integer
          format: int64
        operation:
          description: ADD - Supports new/merge , DELETE - delete the record
          type: string
          enum:
            - ADD
            - DELETE

    ErrorMessage:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
          format: int32

    AuditResponse:
      type: object
      properties:
        messageCategoryId:
          type: integer
          format: int64
          example: 1
        startTime:
          type: string
          example: "2017-05-30 16:40:05"
        endTime:
          type: string
          example: "2017-05-30 16:40:05"
        status:
          type: string
          example: "PROGRESS"
        fromUser:
          type: string
          example: "user@mindspher.com"
        fromApp:
          type: string
          example: "App1"
        emails:
          type: array
          items:
            type: string
            example: "admin@siemens.com"
        smses:
          type: array
          items:
            type: string
            example: "+1234567890"
        pushNotifications:
          type: array
          items:
            type: string
            example: fTEGb-trcxI:APA91bF8T5eJzD1Olaq5cCquydfsuqtgdkhxkjvsnzdhsgfkug"
        bouncedEmails:
          type: array
          items:
            type: string
            example: "admin@siemens.com"
        tenant:
          type: string
          example: "testtenant"

    AuditRequest:
      type: object
      properties:
        startTimeRange:
          type: string
        endTimeRange:
          type: string
        fromApp:
          type: string
        fromUser:
          type: string
        messageCategoryId:
          type: integer
          format: int64
        status:
          type: string

    UpdateRecipientGroupRequest:
      type: object
      properties:
        groupId:
          type: integer
          format: int64
          description: Unique identifier of the group to be updated.
        groupName:
          type: string
          description: New group name to be updated. Alphanumeric with special characters are allowed. Do not use this field  if you donâ€™t want to update the group name.
        recipientIds:
          type: array
          items:
            $ref: '#/components/schemas/UpdateRecipientGroupRecipientInfo'

    UpdateRecipientGroupRecipientInfo:
      type: object
      properties:
        operation:
          type: string
          description: The operation type to be performed with recipient - ADD/DELETE.
          enum:
            - ADD
            - DELETE
        recipientId:
          type: integer
          format: int64
          description: The unique identifier of the recipient to be added/deleted from the group.

    CreateRecipientGroupRecipientInfo:
      type: object
      properties:
        recipientId:
          type: integer
          format: int64
          description: The recipient ID to be added. This recipient ID should belong to the tenant of the recipient group.

    CreateRecipientGroupRequest:
      type: object
      properties:
        groupName:
          type: string
          description: Name of the recipient group. This name is unique within a tenant. Alphanumeric with special characters are allowed.
        recipientIds:
          type: array
          items:
            $ref: '#/components/schemas/CreateRecipientGroupRecipientInfo'

    BounceEmailObj:
      type: object
      properties:
        emailId:
          type: string
          description: Blacklisted invalid email address
          example: "example@abc.com"
        blackListedDate:
          type: string
          description: Date in format (dd-MM-yyyy HH:mm:ss)
          example: "10-08-2018 10:01:37"

    CreateTemplate:
      type: object
      properties:
        templatesetId:
          type: integer
          format: int64
          description: Id of created Template set
          example: 111
        templatesetName:
          type: string
          description: Name of the template set
          example: "TestTemplateForEmail"
        templateList:
          type: array
          items:
            $ref: '#/components/schemas/Template'

    Template:
      type: object
      properties:
        templateId:
          type: integer
          format: int64
          description: Id of created Template
          example: 412
        commChannelId:
          type: integer
          format: int64
          description: Id of communication channel
          example: 1
        commChannelName:
          type: string
          description: Name of communication channel
          example: "Email"

    SendResponse:
      type: object
      properties:
        startTime:
          type: string
          example: '09:00:00-17-01-2017'
        status:
          type: string
          enum:
            - queued
            - sending
            - sent
            - failed
          example: queued

    # Implicit use. Ignore 'unused' warning
    BroadcastEmailContent:
      type: object
      properties:
        body:
          type: object
          properties:
            message:
              type: string
              example: Sample email body
              description: Simple email content to be defined here
            name:
              type: string
              example: Operator
              description: This is the placeholders defined for parameters defined in templates. (key, value)
        messageCategoryId:
          type: integer
          example: 1023
          description: If the category id is non-zero, the "from" and "body.message" attributes are ignored and picked from the category instead. The body may contain optional template placeholders specified as key-value pairs.
        from:
          type: string
          example: siemens
          description: sender id which will be prefixed with -noreply@mindsphere.io. Alpha Numeric with ["_" , "." , "-"] characters allowed
        subject:
          type: string
          example: Subject of email
          description: Alpha Numeric Characters allowed.The subject provided here will take preference over the subject mentioned in category (If category Id is provided)
        priority:
          type: integer
          description: High(1) or Normal(3) while sending email. Optional.
          example: 3

    PublishEmailContent:
      type: object
      properties:
        body:
          type: object
          properties:
            message:
              type: string
              example: Sample email body
              description: Simple email content to be defined here
            name:
              type: string
              example: Operator
              description: This is the placeholders defined for parameters defined in templates. (key, value)
        messageCategoryId:
          type: integer
          example: 1023
          description: If the category id is non-zero, the "from" and "body.message" attributes are ignored and picked from the category instead. The body may contain optional template placeholders specified as key-value pairs.
        recipientsTo:
          type: string
          example: admin@siemens.com;user@siemens.com
          description: semicolon(;) separated Valid Mail Ids allowed. In case of category id as non zero, additional recipients can be added from here.
        from:
          type: string
          example: siemens
          description: sender id which will be prefixed with -noreply@mindsphere.io. Alpha Numeric with ["_" , "." , "-"] characters allowed
        subject:
          type: string
          example: Subject of email
          description: Alpha Numeric Characters allowed.The subject provided here will take preference over the subject mentioned in category (If category Id is provided)
        priority:
          type: integer
          description: High(1) or Normal(3) while sending email. Optional.
          example: 3

    RestrictedRegion:
      type: object
      properties:
        status:
          example: 400
        message:
          example: Recipients from restricted region are not allowed. Please refer documentation.

  parameters:
    broadcastType:
      name: broadcastType
      in: query
      required: true
      schema:
        type: string
        enum:
          - tenantMembersOnly
          - tenantAdminsOnly
          - subTenantMembersOnly
          - all
      description: Type of broadcast -
      
        1. **tenantMembersOnly** - all members (including admins) under a tenant; sub-tenant members are not included.
        
        2. **tenantAdminsOnly** - all admins under a tenant;
            
        3. **subTenantMembersOnly** - all members (including admins) under a sub-tenant specified by the parameter 'subTenantId'. The sub-tenant id is mandatory if this broadcast type is selected.
        
        4. **all** - all members under a tenant and associated sub-tenants.

  securitySchemes:
    nose:
      type: oauth2
      description: |
        For **Xcelerator** compliance, please use **authorizationUrl** = https://1000001700.eu1.sws.siemens.com/oauth/authorize and **tokenUrl** = https://1000001700.eu1.sws.siemens.com/oauth/token
      flows:
        authorizationCode:
          authorizationUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/authorize'
          tokenUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/token'
          scopes:
            nose.se: Grants user to (s)end (e)-mail message
            nose.ac: Grants access (a)dministration (c)onsole
