Appwrite Messaging API

openapi: 3.0.0
info:
  title: Appwrite Messaging API
  description: Appwrite backend as a service cuts up to 70% of the time and costs required for building a modern application. We abstract and simplify common development tasks behind a REST APIs, to help you develop your app in a fast and secure way. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)
  version: 2.0.0
  termsOfService: https://appwrite.io/policy/terms
  contact:
    name: Appwrite Team
    url: https://appwrite.io/support
    email: team@appwrite.io
  license:
    name: BSD-3-Clause
    url: https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE
servers:
- url: https://cloud.appwrite.io/v1
  description: Appwrite Cloud endpoint.
- url: https://{region}.cloud.appwrite.io/v1
  description: Appwrite Cloud regional endpoint. Replace `{region}` with your project region.
  variables:
    region:
      default: fra
      description: Appwrite Cloud region.
tags:
- name: messaging
  description: The Messaging service allows you to send messages to any provider type (SMTP, push notification, SMS, etc.).
paths:
  /messaging/messages:
    get:
      summary: List messages
      operationId: messagingListMessages
      tags:
      - messaging
      description: Get a list of all messages from the current Appwrite project.
      responses:
        '200':
          description: Message list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messageList'
      deprecated: false
      x-appwrite:
        group: messages
        demo: messaging/list-messages.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: messages.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: scheduledAt, deliveredAt, deliveredTotal, status, description, providerType'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
      - name: search
        description: 'Search term to filter your list results. Max length: 256 chars.'
        required: false
        schema:
          type: string
          example: <SEARCH>
          default: ''
        in: query
      - name: total
        description: When set to false, the total count returned will be 0 and will not be calculated.
        required: false
        schema:
          type: boolean
          example: false
          default: true
        in: query
  /messaging/messages/email:
    post:
      summary: Create email
      operationId: messagingCreateEmail
      tags:
      - messaging
      description: Create a new email message.
      responses:
        '201':
          description: Message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message'
      deprecated: false
      x-appwrite:
        group: messages
        demo: messaging/create-email.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: messages.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                messageId:
                  description: Message ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
                  type: string
                  example: <MESSAGE_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                subject:
                  description: Email Subject.
                  type: string
                  example: <SUBJECT>
                content:
                  description: Email Content.
                  type: string
                  example: <CONTENT>
                topics:
                  description: List of Topic IDs.
                  type: array
                  default: []
                  items:
                    type: string
                users:
                  description: List of User IDs.
                  type: array
                  default: []
                  items:
                    type: string
                targets:
                  description: List of Targets IDs.
                  type: array
                  default: []
                  items:
                    type: string
                cc:
                  description: Array of target IDs to be added as CC.
                  type: array
                  default: []
                  items:
                    type: string
                bcc:
                  description: Array of target IDs to be added as BCC.
                  type: array
                  default: []
                  items:
                    type: string
                attachments:
                  description: Array of compound ID strings of bucket IDs and file IDs to be attached to the email. They should be formatted as <BUCKET_ID>:<FILE_ID>.
                  type: array
                  default: []
                  items:
                    type: string
                draft:
                  description: Is message a draft
                  type: boolean
                  default: false
                  example: false
                html:
                  description: Is content of type HTML
                  type: boolean
                  default: false
                  example: false
                scheduledAt:
                  description: Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future.
                  type: string
                  example: '2020-10-15T06:38:00.000+00:00'
                  format: datetime
                  nullable: true
              required:
              - messageId
              - subject
              - content
  /messaging/messages/email/{messageId}:
    patch:
      summary: Update email
      operationId: messagingUpdateEmail
      tags:
      - messaging
      description: 'Update an email message by its unique ID. This endpoint only works on messages that are in draft status. Messages that are already processing, sent, or failed cannot be updated.

        '
      responses:
        '200':
          description: Message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message'
      deprecated: false
      x-appwrite:
        group: messages
        demo: messaging/update-email.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: messages.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: messageId
        description: Message ID.
        required: true
        schema:
          type: string
          example: <MESSAGE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                topics:
                  description: List of Topic IDs.
                  type: array
                  items:
                    type: string
                  nullable: true
                users:
                  description: List of User IDs.
                  type: array
                  items:
                    type: string
                  nullable: true
                targets:
                  description: List of Targets IDs.
                  type: array
                  items:
                    type: string
                  nullable: true
                subject:
                  description: Email Subject.
                  type: string
                  example: <SUBJECT>
                  nullable: true
                content:
                  description: Email Content.
                  type: string
                  example: <CONTENT>
                  nullable: true
                draft:
                  description: Is message a draft
                  type: boolean
                  example: false
                  nullable: true
                html:
                  description: Is content of type HTML
                  type: boolean
                  example: false
                  nullable: true
                cc:
                  description: Array of target IDs to be added as CC.
                  type: array
                  items:
                    type: string
                  nullable: true
                bcc:
                  description: Array of target IDs to be added as BCC.
                  type: array
                  items:
                    type: string
                  nullable: true
                scheduledAt:
                  description: Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future.
                  type: string
                  example: '2020-10-15T06:38:00.000+00:00'
                  format: datetime
                  nullable: true
                attachments:
                  description: Array of compound ID strings of bucket IDs and file IDs to be attached to the email. They should be formatted as <BUCKET_ID>:<FILE_ID>.
                  type: array
                  items:
                    type: string
                  nullable: true
  /messaging/messages/push:
    post:
      summary: Create push notification
      operationId: messagingCreatePush
      tags:
      - messaging
      description: Create a new push notification.
      responses:
        '201':
          description: Message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message'
      deprecated: false
      x-appwrite:
        group: messages
        demo: messaging/create-push.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: messages.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                messageId:
                  description: Message ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
                  type: string
                  example: <MESSAGE_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                title:
                  description: Title for push notification.
                  type: string
                  default: ''
                  example: <TITLE>
                body:
                  description: Body for push notification.
                  type: string
                  default: ''
                  example: <BODY>
                topics:
                  description: List of Topic IDs.
                  type: array
                  default: []
                  items:
                    type: string
                users:
                  description: List of User IDs.
                  type: array
                  default: []
                  items:
                    type: string
                targets:
                  description: List of Targets IDs.
                  type: array
                  default: []
                  items:
                    type: string
                data:
                  description: Additional key-value pair data for push notification.
                  type: object
                  default: {}
                  example: {}
                  nullable: true
                action:
                  description: Action for push notification.
                  type: string
                  default: ''
                  example: <ACTION>
                image:
                  description: Image for push notification. Must be a compound bucket ID to file ID of a jpeg, png, or bmp image in Appwrite Storage. It should be formatted as <BUCKET_ID>:<FILE_ID>.
                  type: string
                  default: ''
                  example: <ID1:ID2>
                icon:
                  description: Icon for push notification. Available only for Android and Web Platform.
                  type: string
                  default: ''
                  example: <ICON>
                sound:
                  description: Sound for push notification. Available only for Android and iOS Platform.
                  type: string
                  default: ''
                  example: <SOUND>
                color:
                  description: Color for push notification. Available only for Android Platform.
                  type: string
                  default: ''
                  example: <COLOR>
                tag:
                  description: Tag for push notification. Available only for Android Platform.
                  type: string
                  default: ''
                  example: <TAG>
                badge:
                  description: Badge for push notification. Available only for iOS Platform.
                  type: integer
                  default: -1
                  example: 1
                  format: int32
                draft:
                  description: Is message a draft
                  type: boolean
                  default: false
                  example: false
                scheduledAt:
                  description: Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future.
                  type: string
                  example: '2020-10-15T06:38:00.000+00:00'
                  format: datetime
                  nullable: true
                contentAvailable:
                  description: If set to true, the notification will be delivered in the background. Available only for iOS Platform.
                  type: boolean
                  default: false
                  example: false
                critical:
                  description: If set to true, the notification will be marked as critical. This requires the app to have the critical notification entitlement. Available only for iOS Platform.
                  type: boolean
                  default: false
                  example: false
                priority:
                  description: Set the notification priority. "normal" will consider device state and may not deliver notifications immediately. "high" will always attempt to immediately deliver the notification.
                  type: string
                  default: high
                  example: normal
                  title: MessagePriority
                  oneOf:
                  - type: string
                    enum:
                    - normal
                    title: normal
                  - type: string
                    enum:
                    - high
                    title: high
              required:
              - messageId
  /messaging/messages/push/{messageId}:
    patch:
      summary: Update push notification
      operationId: messagingUpdatePush
      tags:
      - messaging
      description: 'Update a push notification by its unique ID. This endpoint only works on messages that are in draft status. Messages that are already processing, sent, or failed cannot be updated.

        '
      responses:
        '200':
          description: Message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message'
      deprecated: false
      x-appwrite:
        group: messages
        demo: messaging/update-push.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: messages.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: messageId
        description: Message ID.
        required: true
        schema:
          type: string
          example: <MESSAGE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                topics:
                  description: List of Topic IDs.
                  type: array
                  items:
                    type: string
                  nullable: true
                users:
                  description: List of User IDs.
                  type: array
                  items:
                    type: string
                  nullable: true
                targets:
                  description: List of Targets IDs.
                  type: array
                  items:
                    type: string
                  nullable: true
                title:
                  description: Title for push notification.
                  type: string
                  example: <TITLE>
                  nullable: true
                body:
                  description: Body for push notification.
                  type: string
                  example: <BODY>
                  nullable: true
                data:
                  description: Additional Data for push notification.
                  type: object
                  default: {}
                  example: {}
                  nullable: true
                action:
                  description: Action for push notification.
                  type: string
                  example: <ACTION>
                  nullable: true
                image:
                  description: Image for push notification. Must be a compound bucket ID to file ID of a jpeg, png, or bmp image in Appwrite Storage. It should be formatted as <BUCKET_ID>:<FILE_ID>.
                  type: string
                  example: <ID1:ID2>
                  nullable: true
                icon:
                  description: Icon for push notification. Available only for Android and Web platforms.
                  type: string
                  example: <ICON>
                  nullable: true
                sound:
                  description: Sound for push notification. Available only for Android and iOS platforms.
                  type: string
                  example: <SOUND>
                  nullable: true
                color:
                  description: Color for push notification. Available only for Android platforms.
                  type: string
                  example: <COLOR>
                  nullable: true
                tag:
                  description: Tag for push notification. Available only for Android platforms.
                  type: string
                  example: <TAG>
                  nullable: true
                badge:
                  description: Badge for push notification. Available only for iOS platforms.
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
                draft:
                  description: Is message a draft
                  type: boolean
                  example: false
                  nullable: true
                scheduledAt:
                  description: Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future.
                  type: string
                  example: '2020-10-15T06:38:00.000+00:00'
                  format: datetime
                  nullable: true
                contentAvailable:
                  description: If set to true, the notification will be delivered in the background. Available only for iOS Platform.
                  type: boolean
                  example: false
                  nullable: true
                critical:
                  description: If set to true, the notification will be marked as critical. This requires the app to have the critical notification entitlement. Available only for iOS Platform.
                  type: boolean
                  example: false
                  nullable: true
                priority:
                  description: Set the notification priority. "normal" will consider device battery state and may send notifications later. "high" will always attempt to immediately deliver the notification.
                  type: string
                  example: normal
                  title: MessagePriority
                  oneOf:
                  - type: string
                    enum:
                    - normal
                    title: normal
                  - type: string
                    enum:
                    - high
                    title: high
                  nullable: true
  /messaging/messages/sms:
    post:
      summary: Create SMS
      operationId: messagingCreateSms
      tags:
      - messaging
      description: Create a new SMS message.
      responses:
        '201':
          description: Message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message'
      deprecated: true
      x-appwrite:
        group: messages
        demo: messaging/create-sms.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: messages.write
        platforms:
        - console
        - server
        packaging: false
        public: false
        deprecated:
          since: 1.8.0
          replaceWith: messaging.createSMS
        methods:
        - name: createSms
          namespace: messaging
          platforms:
          - console
          - server
          desc: ''
          auth:
            console:
              Project: []
            server:
              Project: []
              Key: []
          parameters:
          - messageId
          - content
          - topics
          - users
          - targets
          - draft
          - scheduledAt
          required:
          - messageId
          - content
          responses:
          - code: 201
            model: '#/components/schemas/message'
          description: Create a new SMS message.
          demo: messaging/create-sms.md
          public: false
          deprecated:
            since: 1.8.0
            replaceWith: messaging.createSMS
        - name: createSMS
          namespace: messaging
          platforms:
          - console
          - server
          desc: ''
          auth:
            console:
              Project: []
            server:
              Project: []
              Key: []
          parameters:
          - messageId
          - content
          - topics
          - users
          - targets
          - draft
          - scheduledAt
          required:
          - messageId
          - content
          responses:
          - code: 201
            model: '#/components/schemas/message'
          description: Create a new SMS message.
          demo: messaging/create-sms.md
          public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                messageId:
                  description: Message ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
                  type: string
                  example: <MESSAGE_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                content:
                  description: SMS Content.
                  type: string
                  example: <CONTENT>
                topics:
                  description: List of Topic IDs.
                  type: array
                  default: []
                  items:
                    type: string
                users:
                  description: List of User IDs.
                  type: array
                  default: []
                  items:
                    type: string
                targets:
                  description: List of Targets IDs.
                  type: array
                  default: []
                  items:
                    type: string
                draft:
                  description: Is message a draft
                  type: boolean
                  default: false
                  example: false
                scheduledAt:
                  description: Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future.
                  type: string
                  example: '2020-10-15T06:38:00.000+00:00'
                  format: datetime
                  nullable: true
              required:
              - messageId
              - content
  /messaging/messages/sms/{messageId}:
    patch:
      summary: Update SMS
      operationId: messagingUpdateSms
      tags:
      - messaging
      description: 'Update an SMS message by its unique ID. This endpoint only works on messages that are in draft status. Messages that are already processing, sent, or failed cannot be updated.

        '
      responses:
        '200':
          description: Message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message'
      deprecated: true
      x-appwrite:
        group: messages
        demo: messaging/update-sms.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: messages.write
        platforms:
        - console
        - server
        packaging: false
        public: false
        deprecated:
          since: 1.8.0
          replaceWith: messaging.updateSMS
        methods:
        - name: updateSms
          namespace: messaging
          platforms:
          - console
          - server
          desc: ''
          auth:
            console:
              Project: []
            server:
              Project: []
              Key: []
          parameters:
          - messageId
          - topics
          - users
          - targets
          - content
          - draft
          - scheduledAt
          required:
          - messageId
          responses:
          - code: 200
            model: '#/components/schemas/message'
          description: 'Update an SMS message by its unique ID. This endpoint only works on messages that are in draft status. Messages that are already processing, sent, or failed cannot be updated.

            '
          demo: messaging/update-sms.md
          public: false
          deprecated:
            since: 1.8.0
            replaceWith: messaging.updateSMS
        - name: updateSMS
          namespace: messaging
          platforms:
          - console
          - server
          desc: ''
          auth:
            console:
              Project: []
            server:
              Project: []
              Key: []
          parameters:
          - messageId
          - topics
          - users
          - targets
          - content
          - draft
          - scheduledAt
          required:
          - messageId
          responses:
          - code: 200
            model: '#/components/schemas/message'
          description: 'Update an SMS message by its unique ID. This endpoint only works on messages that are in draft status. Messages that are already processing, sent, or failed cannot be updated.

            '
          demo: messaging/update-sms.md
          public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: messageId
        description: Message ID.
        required: true
        schema:
          type: string
          example: <MESSAGE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                topics:
                  description: List of Topic IDs.
                  type: array
                  items:
                    type: string
                  nullable: true
                users:
                  description: List of User IDs.
                  type: array
                  items:
                    type: string
                  nullable: true
                targets:
                  description: List of Targets IDs.
                  type: array
                  items:
                    type: string
                  nullable: true
                content:
                  description: Email Content.
                  type: string
                  example: <CONTENT>
                  nullable: true
                draft:
                  description: Is message a draft
                  type: boolean
                  example: false
                  nullable: true
                scheduledAt:
                  description: Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future.
                  type: string
                  example: '2020-10-15T06:38:00.000+00:00'
                  format: datetime
                  nullable: true
  /messaging/messages/{messageId}:
    get:
      summary: Get message
      operationId: messagingGetMessage
      tags:
      - messaging
      description: 'Get a message by its unique ID.

        '
      responses:
        '200':
          description: Message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message'
      deprecated: false
      x-appwrite:
        group: messages
        demo: messaging/get-message.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: messages.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: messageId
        description: Message ID.
        required: true
        schema:
          type: string
          example: <MESSAGE_ID>
        in: path
    delete:
      summary: Delete message
      operationId: messagingDelete
      tags:
      - messaging
      description: Delete a message. If the message is not a draft or scheduled, but has been sent, this will not recall the message.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        g

# --- truncated at 32 KB (139 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appwrite/refs/heads/main/openapi/appwrite-messaging-api-openapi.yml