openapi: 3.0.3
info:
  contact:
    email: hi@ory.sh
  description: 'Documentation for all of Ory Hydra''s APIs.

    '
  license:
    name: Apache 2.0
  title: Ory Hydra api courier API
  version: ''
tags:
- description: APIs for managing email and SMS message delivery.
  name: courier
paths:
  /admin/courier/messages:
    get:
      description: Lists all messages by given status and recipient.
      operationId: listCourierMessages
      parameters:
      - description: 'Items per Page


          This is the number of items per page to return.

          For details on pagination please head over to the [pagination documentation](https://www.ory.com/docs/ecosystem/api-design#pagination).'
        in: query
        name: page_size
        schema:
          default: 250
          format: int64
          maximum: 1000
          minimum: 1
          type: integer
      - description: 'Next Page Token


          The next page token.

          For details on pagination please head over to the [pagination documentation](https://www.ory.com/docs/ecosystem/api-design#pagination).'
        in: query
        name: page_token
        schema:
          type: string
      - description: 'Status filters out messages based on status.

          If no value is provided, it doesn''t take effect on filter.'
        in: query
        name: status
        schema:
          $ref: '#/components/schemas/courierMessageStatus'
      - description: 'Recipient filters out messages based on recipient.

          If no value is provided, it doesn''t take effect on filter.'
        in: query
        name: recipient
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/listCourierMessages'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
      security:
      - oryAccessToken: []
      summary: List Messages
      tags:
      - courier
      x-ory-ratelimit-bucket: kratos-admin-low
  /admin/courier/messages/{id}:
    get:
      description: Gets a specific messages by the given ID.
      operationId: getCourierMessage
      parameters:
      - description: MessageID is the ID of the message.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message'
          description: message
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorGeneric'
          description: errorGeneric
      security:
      - oryAccessToken: []
      summary: Get a Message
      tags:
      - courier
      x-ory-ratelimit-bucket: kratos-admin-medium
components:
  schemas:
    genericError:
      properties:
        code:
          description: The status code
          example: 404
          format: int64
          type: integer
        debug:
          description: 'Debug information


            This field is often not exposed to protect against leaking

            sensitive information.'
          example: SQL field "foo" is not a bool.
          type: string
        details:
          additionalProperties: false
          description: Further error details
          type: object
        id:
          description: 'The error ID


            Useful when trying to identify various errors in application logic.'
          type: string
        message:
          description: 'Error message


            The error''s message.'
          example: The resource could not be found
          type: string
        reason:
          description: A human-readable reason for the error
          example: User with ID 1234 does not exist.
          type: string
        request:
          description: 'The request ID


            The request ID is often exposed internally in order to trace

            errors across service architectures. This is often a UUID.'
          example: d7ef54b1-ec15-46e6-bccb-524b82c035e6
          type: string
        status:
          description: The status description
          example: Not Found
          type: string
      required:
      - message
      type: object
    errorGeneric:
      description: The standard Ory JSON API error format.
      properties:
        error:
          $ref: '#/components/schemas/genericError'
      required:
      - error
      title: JSON API Error Response
      type: object
    courierMessageStatus:
      description: A Message's Status
      enum:
      - queued
      - sent
      - processing
      - abandoned
      type: string
    messageDispatch:
      description: 'MessageDispatch represents an attempt of sending a courier message

        It contains the status of the attempt (failed or successful) and the error if any occured'
      properties:
        created_at:
          description: CreatedAt is a helper struct field for gobuffalo.pop.
          format: date-time
          type: string
        error:
          $ref: '#/components/schemas/JSONRawMessage'
        id:
          description: The ID of this message dispatch
          format: uuid
          type: string
        message_id:
          description: The ID of the message being dispatched
          format: uuid
          type: string
        status:
          description: 'The status of this dispatch

            Either "failed" or "success"

            failed CourierMessageDispatchStatusFailed

            success CourierMessageDispatchStatusSuccess'
          enum:
          - failed
          - success
          type: string
          x-go-enum-desc: 'failed CourierMessageDispatchStatusFailed

            success CourierMessageDispatchStatusSuccess'
        updated_at:
          description: UpdatedAt is a helper struct field for gobuffalo.pop.
          format: date-time
          type: string
      required:
      - id
      - message_id
      - status
      - created_at
      - updated_at
      type: object
    courierMessageType:
      description: It can either be `email` or `phone`
      enum:
      - email
      - phone
      title: A Message's Type
      type: string
    message:
      properties:
        body:
          type: string
        channel:
          type: string
        created_at:
          description: CreatedAt is a helper struct field for gobuffalo.pop.
          format: date-time
          type: string
        dispatches:
          description: 'Dispatches store information about the attempts of delivering a message

            May contain an error if any happened, or just the `success` state.'
          items:
            $ref: '#/components/schemas/messageDispatch'
          type: array
        id:
          format: uuid
          type: string
        recipient:
          type: string
        send_count:
          format: int64
          type: integer
        status:
          $ref: '#/components/schemas/courierMessageStatus'
        subject:
          type: string
        template_type:
          description: '

            recovery_invalid TypeRecoveryInvalid

            recovery_valid TypeRecoveryValid

            recovery_code_invalid TypeRecoveryCodeInvalid

            recovery_code_valid TypeRecoveryCodeValid

            verification_invalid TypeVerificationInvalid

            verification_valid TypeVerificationValid

            verification_code_invalid TypeVerificationCodeInvalid

            verification_code_valid TypeVerificationCodeValid

            stub TypeTestStub

            login_code_valid TypeLoginCodeValid

            registration_code_valid TypeRegistrationCodeValid'
          enum:
          - recovery_invalid
          - recovery_valid
          - recovery_code_invalid
          - recovery_code_valid
          - verification_invalid
          - verification_valid
          - verification_code_invalid
          - verification_code_valid
          - stub
          - login_code_valid
          - registration_code_valid
          type: string
          x-go-enum-desc: 'recovery_invalid TypeRecoveryInvalid

            recovery_valid TypeRecoveryValid

            recovery_code_invalid TypeRecoveryCodeInvalid

            recovery_code_valid TypeRecoveryCodeValid

            verification_invalid TypeVerificationInvalid

            verification_valid TypeVerificationValid

            verification_code_invalid TypeVerificationCodeInvalid

            verification_code_valid TypeVerificationCodeValid

            stub TypeTestStub

            login_code_valid TypeLoginCodeValid

            registration_code_valid TypeRegistrationCodeValid'
        type:
          $ref: '#/components/schemas/courierMessageType'
        updated_at:
          description: UpdatedAt is a helper struct field for gobuffalo.pop.
          format: date-time
          type: string
      required:
      - id
      - status
      - type
      - recipient
      - body
      - subject
      - template_type
      - send_count
      - created_at
      - updated_at
      type: object
    JSONRawMessage:
      title: JSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger.
      type: object
  responses:
    listCourierMessages:
      content:
        application/json:
          schema:
            items:
              $ref: '#/components/schemas/message'
            type: array
      description: Paginated Courier Message List Response
  securitySchemes:
    basic:
      scheme: basic
      type: http
    bearer:
      scheme: bearer
      type: http
    oauth2:
      flows:
        authorizationCode:
          authorizationUrl: https://hydra.demo.ory.sh/oauth2/auth
          scopes:
            offline: A scope required when requesting refresh tokens (alias for `offline_access`)
            offline_access: A scope required when requesting refresh tokens
            openid: Request an OpenID Connect ID Token
          tokenUrl: https://hydra.demo.ory.sh/oauth2/token
      type: oauth2
x-forwarded-proto: string
x-request-id: string