> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# List received messages

> Account-scoped metadata, ordered by received_at descending, then ID descending. Marker is the last ID of the previous page. Filters combine before pagination. No body or attachment bytes are included.

<Info>
  Requires the IAM action **`email:ListReceivedMessages`**. See [EMAIL permissions](/email/permissions) for the full list, what each one covers, and an example policy.
</Info>


## OpenAPI

````yaml /api-reference/specs/email.yaml get /v1/received-messages
openapi: 3.0.3
info:
  title: Basaltic Email API
  version: 1.0.0
  description: >
    Regional API for sending and receiving email, identities and DNS records,
    templates, configuration sets, IP pools, recipient rules, message content
    and attachments.


    Identities must be verified separately in every region. Create an identity,
    publish its dns_records, then request verification. Only verified identities
    can send or enable receiving.


    Request references accept a UUID, an account-unique name or a CRN of the
    expected resource type. Names are immutable. Malformed references or the
    wrong resource type/region return 400; missing or foreign-account references
    return 404. Resource paths use UUIDs. List filters are exact, account-scoped
    and applied before pagination; missing or foreign references return empty
    results.


    Sent and received message content expires after 30 days. Attachment objects
    follow their bucket lifecycle independently. Use Telemetry for aggregate
    metrics and the diagnostic endpoints for individual events and DMARC report
    records.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://email.{region}.basaltic.sh
    description: Regional API endpoint
    variables:
      region:
        default: sa-saopaulo-1
        description: Region code
security:
  - BearerAuth: []
tags:
  - name: Email
    description: Customer-facing email sending (regional).
paths:
  /v1/received-messages:
    get:
      tags:
        - Email
      summary: List received messages
      description: >-
        Account-scoped metadata, ordered by received_at descending, then ID
        descending. Marker is the last ID of the previous page. Filters combine
        before pagination. No body or attachment bytes are included.
      operationId: listReceivedMessages
      parameters:
        - name: identity
          in: query
          required: false
          schema:
            type: string
          description: Receiving identity UUID, CRN or name.
        - name: recipient
          in: query
          required: false
          schema:
            type: string
        - name: review_reason
          in: query
          required: false
          schema:
            type: string
            enum:
              - clear
              - spam
              - sender_unverified
              - malware
        - name: marker
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivedMessageListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Caller lacks permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found in this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflicting state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Quota or rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ReceivedMessageListResponse:
      type: object
      required:
        - messages
        - meta
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ReceivedMessage'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Error code identifying the type of error
              example: INVALID_INPUT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Optional non-sensitive values for interpolation of localized
                errors, keyed by error code. Never present for server errors.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Request ID for debugging
              example: 550e8400-e29b-41d4-a716-446655440000
    ReceivedMessage:
      type: object
      required:
        - id
        - crn
        - recipient
        - from
        - subject
        - received_at
        - expires_at
        - published_at
        - content_available
        - review_reason
        - authenticated
        - attachments
        - identity
        - notification_status
        - notification_error
      properties:
        crn:
          type: string
        id:
          type: string
          format: uuid
        recipient:
          type: string
        from:
          type: string
        subject:
          type: string
        received_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        published_at:
          type: string
          format: date-time
          nullable: true
        content_available:
          type: boolean
        review_reason:
          type: string
          enum:
            - ''
            - spam
            - sender_unverified
            - malware
        authenticated:
          type: boolean
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        identity:
          allOf:
            - $ref: '#/components/schemas/ResourceRef'
          nullable: true
          description: >-
            Receiving identity; null only when the original identity no longer
            exists.
          type: object
        notification_status:
          type: string
          enum:
            - pending
            - retrying
            - published
        notification_error:
          type: string
          nullable: true
          description: >-
            Safe publication failure detail. Retried automatically while content
            is retained.
        rfc_message_id:
          type: string
          description: RFC Message-ID header, distinct from the Email resource UUID.
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items
          example: 150
        limit:
          type: integer
          description: Number of items per page
          example: 20
        marker:
          type: string
          description: >-
            Opaque cursor for the next page. Pass it back as the `marker` query
            parameter; treat it as a token, not a value to parse.
          example: 550e8400-e29b-41d4-a716-446655440000
        has_more:
          type: boolean
          description: Whether there are more items
          example: true
    Attachment:
      type: object
      required:
        - id
        - name
        - content_type
        - size
        - bucket
        - key
        - sha256
      description: >-
        An immutable attachment reference. id is stable within the message.
        version_id is the Storage object version; sha256 pins decoded bytes even
        in an unversioned bucket. Bucket lifecycle controls object retention
        independently of the 30-day Email content lifetime. Legacy attachments
        can have a null bucket and remain downloadable by id until message
        expiry.
      properties:
        name:
          type: string
        content_type:
          type: string
        size:
          type: integer
        bucket:
          allOf:
            - $ref: '#/components/schemas/ResourceRef'
          nullable: true
          type: object
        key:
          type: string
        version_id:
          type: string
          description: Opaque Storage object version token, when versioning is enabled.
        sha256:
          type: string
          description: SHA-256 of the decoded attachment bytes.
        id:
          type: string
          format: uuid
    ResourceRef:
      type: object
      required:
        - id
        - crn
      properties:
        id:
          type: string
          format: uuid
          example: 288aa1e9-bbf5-5584-bce9-6a688f06d8a1
        crn:
          type: string
          example: crn:catalog::platform:country/288aa1e9-bbf5-5584-bce9-6a688f06d8a1
        name:
          type: string
          description: >-
            Display label at response time — the resource's name where it has
            one, otherwise its human label (an invoice number, an account
            display name). Absent when the target is gone. Not a lookup key.
          example: Brazil
  responses:
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        An OAuth 2.0 bearer token, sent as `Authorization: Bearer <token>`.
        This is the recommended way to authenticate.

        Get one by exchanging a service account's access key pair at
        `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
        standard client-credentials grant, so any OAuth-aware library will
        obtain and refresh it for you.

        ```
        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```

        Tokens last an hour by default. The same access key pair is separately
        your AWS SigV4 credential for the S3-compatible object endpoint, which
        speaks nothing else.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.