Global Relay Email API

openapi: 3.2.0
info:
  title: Global Relay Archiving Email API
  description: The Global Relay Email Archiving API provides a RESTful interface to capture and archive email content and metadata into the Global Relay Archive. It supports archiving emails with attachments, headers, and full message structure. The API uses OAuth 2.0 Client Credentials authentication and provides secure, compliant email archiving for regulated industries.
  version: 2.0.0
  contact:
    name: Global Relay
    url: https://developers.globalrelay.com/api/email-archiving-api/
  license:
    name: Proprietary
    url: https://www.globalrelay.com/legal/
servers:
- url: https://email.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:
    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
    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
    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
    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
    EmailAddress:
      type: object
      required:
      - address
      properties:
        address:
          type: string
          format: email
          description: Email address
        displayName:
          type: string
          description: Display name
    EmailRequest:
      type: object
      required:
      - requestId
      - email
      properties:
        requestId:
          type: string
          format: uuid
          description: Unique identifier for this API request
        email:
          $ref: '#/components/schemas/Email'
    EmailHeader:
      type: object
      properties:
        name:
          type: string
          description: Header name
        value:
          type: string
          description: Header value
  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 email.