openapi: 3.0.3
info:
  title: Global Relay Conversation Archiving Conversations Email API
  description: The Global Relay Conversation Archiving API provides a RESTful interface to seamlessly integrate messaging platforms with the Global Relay Archive. It enables secure capture and preservation of one-to-one or multi-party conversations, including text messages, file attachments, reactions, edits, and deletions. The API supports all conversation events and provides guardrails and flexibility to efficiently automate the archiving process and meet compliance requirements. Authentication uses the Client Credentials OAuth 2.0 grant type with Bearer tokens.
  version: 2.0.0
  contact:
    name: Global Relay
    url: https://developers.globalrelay.com/api/conversation-archiving-api/
  license:
    name: Proprietary
    url: https://www.globalrelay.com/legal/
servers:
- url: https://conversations.api.globalrelay.com/v2
  description: Production server
security:
- BearerAuth: []
tags:
- name: Email
  description: Endpoints for archiving email messages
paths:
  /email:
    post:
      operationId: archiveEmail
      summary: Global Relay Archive an email
      description: Archives an email message to the Global Relay Archive. Each request must include a unique requestId (UUID). Emails can include headers, body content, recipients, and references to file attachments uploaded via the /files endpoint. Rate limited to 1000 requests per minute.
      tags:
      - Email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRequest'
      responses:
        '200':
          description: Email archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailResponse'
        '400':
          description: Bad request - invalid email data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded - max 1000 requests per minute
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        requestId:
          type: string
          format: uuid
          description: Request ID for troubleshooting
    EmailResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        status:
          type: string
          description: Status of the archive request
        messageId:
          type: string
          description: ID of the archived email
    EmailAddress:
      type: object
      required:
      - address
      properties:
        address:
          type: string
          format: email
          description: Email address
        displayName:
          type: string
          description: Display name
    EmailHeader:
      type: object
      properties:
        name:
          type: string
          description: Header name
        value:
          type: string
          description: Header value
    Email:
      type: object
      required:
      - from
      - to
      - subject
      - sentDate
      properties:
        messageId:
          type: string
          description: Unique message identifier
        from:
          $ref: '#/components/schemas/EmailAddress'
        to:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          description: List of To recipients
        cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          description: List of CC recipients
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          description: List of BCC recipients
        subject:
          type: string
          description: Email subject line
        sentDate:
          type: string
          format: date-time
          description: Date and time the email was sent
        receivedDate:
          type: string
          format: date-time
          description: Date and time the email was received
        body:
          $ref: '#/components/schemas/EmailBody'
        headers:
          type: array
          items:
            $ref: '#/components/schemas/EmailHeader'
          description: Email headers
        attachmentIds:
          type: array
          items:
            type: string
          description: IDs of attachments uploaded via /files endpoint
    EmailRequest:
      type: object
      required:
      - requestId
      - email
      properties:
        requestId:
          type: string
          format: uuid
          description: Unique identifier for this API request
        email:
          $ref: '#/components/schemas/Email'
    EmailBody:
      type: object
      properties:
        contentType:
          type: string
          description: MIME type of the body content
          enum:
          - text/plain
          - text/html
        content:
          type: string
          description: Body content
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Client Credentials grant. Obtain a token from https://iam-oauth2.globalrelay.com/oauth2/token with grant_type=client_credentials and scope=openid conversation.