{
  "openapi": "3.0.1",
  "info": {
    "title": "OC Email API",
    "description": "Securely capture your emails in Global Relay Archive.",
    "termsOfService": "https://globalrelay.com/company-info/terms-of-use",
    "contact": {
      "email": "all_enterprise_api@globalrelay.net"
    },
    "version": "1.2"
  },
  "servers": [
    {
      "url": "https://swaggerhub.globalrelay.net/virts/Gateway-APIs/oc-email-api/1.2",
      "description": "SwaggerHub API Auto Mocking"
    },
    {
      "url": "",
      "description": "Production Environment"
    }
  ],
  "security": [
    {
      "oAuth2ClientCredentials": []
    }
  ],
  "tags": [
    {
      "name": "Email",
      "description": "Send email data, directly to Global Relay for archiving."
    }
  ],
  "paths": {
    "/v2/email": {
      "post": {
        "tags": [
          "Email"
        ],
        "summary": "POST a single email message",
        "description": "Represents a single email message that will be converted to a single Global Relay EML",
        "operationId": "createEmail",
        "parameters": [
          {
            "name": "X-SubType",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Submit an OC Email API JSON Payload",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/emailPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/createEmailResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/createEmailStatusResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "405": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "description": "Request size exceeds the allowable limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "413",
                  "message": "Payload Too Large",
                  "moreInformation": "Request size exceeds the allowable limit",
                  "context": {}
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/Error-429-Rate-Limit-Exceeded-3Scale"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "emailPayload": {
        "type": "object",
        "properties": {
          "requestInfo": {
            "$ref": "#/components/schemas/requestInfo"
          },
          "emailOverview": {
            "$ref": "#/components/schemas/emailOverview"
          }
        },
        "description": "A single JSON Object that represents a single Email"
      },
      "requestInfo": {
        "required": [
          "requestId"
        ],
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Client generated UUID for tracking purposes (A UUID specified by RFC4122).",
            "example": "c1319852-5367-5958-9aee-98fffdc22490"
          }
        },
        "description": "Top level information that must be included in every request payload."
      },
      "emailOverview": {
        "required": [
          "content",
          "messageId",
          "senders",
          "time"
        ],
        "type": "object",
        "properties": {
          "messageId": {
            "type": "string",
            "description": "An identifier used to help thread related emails together. Must contain at least one non-whitespace character.",
            "example": "c1319852-5367-5958-9aee-98fffdc22491"
          },
          "time": {
            "type": "integer",
            "description": "Time in epoch milliseconds of when the email was sent. The value must represent a time after 01-01-1990 00:00:00 and before end of current year + 1.",
            "format": "int64",
            "example": 1672531200000
          },
          "subject": {
            "type": "string",
            "description": "The subject line of the email, one will be generated if not provided.",
            "example": "RE Compliance Archiving Tools"
          },
          "senders": {
            "type": "array",
            "description": "The list of senders, at least one and only one entry must be of senderType 'sender'",
            "items": {
              "$ref": "#/components/schemas/sender"
            }
          },
          "recipients": {
            "type": "array",
            "description": "The list of receipients for this email.",
            "items": {
              "$ref": "#/components/schemas/recipientUser"
            }
          },
          "content": {
            "$ref": "#/components/schemas/content"
          },
          "files": {
            "type": "array",
            "example": [
              {
                "filename": "meeting-video.mp4",
                "fileKey": "example-corp/all-meetings/meeting-video.mp4"
              },
              {
                "filename": "image.gif",
                "fileKey": "default/acmeLtd/12345",
                "fileHref": "https://giphy.com/gifs/JIX9t2j0ZTN9S"
              },
              {
                "filename": "attached-image.jpg",
                "fileKey": "default/acmeLtd/123456",
                "contentId": "c1319852"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/file"
            }
          },
          "emailProperties": {
            "type": "array",
            "description": "Additional properties to set in the email. Up to ten headers can be added.",
            "items": {
              "$ref": "#/components/schemas/emailProperty"
            }
          },
          "eventType": {
            "type": "string",
            "description": "This indicates the type of the event that occurred in the email. This will be added as an Email Property with hidden set to false and xheader set to true.",
            "example": "email_sent",
            "enum": [
              "email_sent",
              "email_received",
              "email_forwarded",
              "email_replied",
              "email_replied_all",
              "email_bounced",
              "email_draft",
              "email_deleted",
              "email_read",
              "email_unread",
              "email_archived",
              "email_recalled",
              "email_sent_on_behalf",
              "auto_reply",
              "email_scheduled",
              "email_system_generated"
            ]
          }
        },
        "description": "Content and metadata information of the email."
      },
      "sender": {
        "required": [
          "displayName",
          "primaryEmail",
          "senderType"
        ],
        "type": "object",
        "properties": {
          "displayName": {
            "$ref": "#/components/schemas/displayName"
          },
          "companyName": {
            "$ref": "#/components/schemas/companyName"
          },
          "accountId": {
            "$ref": "#/components/schemas/accountId"
          },
          "accountName": {
            "$ref": "#/components/schemas/accountName"
          },
          "primaryEmail": {
            "$ref": "#/components/schemas/primaryEmail"
          },
          "otherAlias": {
            "$ref": "#/components/schemas/otherAlias"
          },
          "identityType": {
            "$ref": "#/components/schemas/identityType"
          },
          "phoneNumber": {
            "$ref": "#/components/schemas/phoneNumber"
          },
          "senderType": {
            "type": "string",
            "description": "The classification of type of sender, i.e. the entity who sent it, or if it was on behalf of another user",
            "example": "sender",
            "enum": [
              "sender",
              "sent_on_behalf_of",
              "original_sender",
              "shared_messenger"
            ]
          }
        },
        "description": "An entity that was involved in sending this email."
      },
      "recipientUser": {
        "required": [
          "deliveryTypes",
          "displayName",
          "primaryEmail"
        ],
        "type": "object",
        "properties": {
          "deliveryTypes": {
            "type": "array",
            "description": "The manner in which the email was sent to this recipient. A list of any of these values [to,cc,bcc]. At least one must be specified.",
            "example": [
              "to",
              "cc"
            ],
            "items": {
              "type": "string",
              "enum": [
                "to",
                "cc",
                "bcc"
              ]
            }
          },
          "displayName": {
            "$ref": "#/components/schemas/displayName"
          },
          "companyName": {
            "$ref": "#/components/schemas/companyName"
          },
          "accountId": {
            "$ref": "#/components/schemas/accountId"
          },
          "accountName": {
            "$ref": "#/components/schemas/accountName"
          },
          "primaryEmail": {
            "$ref": "#/components/schemas/primaryEmail"
          },
          "otherAlias": {
            "$ref": "#/components/schemas/otherAlias"
          },
          "phoneNumber": {
            "$ref": "#/components/schemas/phoneNumber"
          },
          "identityType": {
            "$ref": "#/components/schemas/identityType"
          }
        },
        "description": "A user who the email was sent to."
      },
      "content": {
        "required": [
          "message"
        ],
        "type": "object",
        "properties": {
          "textType": {
            "type": "string",
            "description": "The format of the email body.",
            "example": "plain",
            "enum": [
              "plain",
              "html",
              "markdown"
            ]
          },
          "priority": {
            "type": "string",
            "description": "The priority with which the message was sent. This will be added as an Email Property with hidden set to false and xheader set to true.",
            "example": "high"
          },
          "sensitivity": {
            "type": "string",
            "description": "The sensitivity of the message. This will be added as an Email Property with hidden set to false and xheader set to true.",
            "example": "internal"
          },
          "classification": {
            "type": "string",
            "description": "The classification of the message. This will be added as an Email Property with hidden set to false and xheader set to true.",
            "example": "marketing"
          },
          "message": {
            "type": "string",
            "description": "The main body of the email content. Required but can be set to empty string for Emails without a body. Text added in this field will not be HTML escaped, as such some characters will need to be HTML encoded in order to display properly."
          },
          "signature": {
            "type": "string",
            "description": "The signature of the email. Text added in this field will not be HTML escaped, as such some characters will need to be HTML encoded in order to display properly.",
            "example": "Joe Bloggs Employee My Company"
          },
          "disclaimer": {
            "type": "string",
            "description": "The disclaimer from the email. Text added in this field will not be HTML escaped, as such some characters will need to be HTML encoded in order to display properly.",
            "example": "This message is intended only for the use of the individual or entity to which it is addressed."
          }
        }
      },
      "file": {
        "required": [
          "fileKey"
        ],
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Name of the file.",
            "example": "file.txt"
          },
          "fileKey": {
            "type": "string",
            "description": "Location of the attachment relative to the upload of the file in Global Relay. Should be the same fileKey as specified when sending to Files endpoint.",
            "example": "example-corp/all-meetings/file.txt"
          },
          "fileHref": {
            "type": "string",
            "description": "hyperlink link to denote the external link to the file on the host provider platform.",
            "example": "http://example-corp.s3.amazonaws.com/file.txt"
          },
          "contentId": {
            "type": "string",
            "description": "If this file is an image which is embedded within the email body and to be displayed inline, this field represents the content identifier that is similarly set in the email body HTML.",
            "example": "12345"
          }
        }
      },
      "emailProperty": {
        "required": [
          "name",
          "value"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Property name. Must contain at least one non-whitespace character."
          },
          "value": {
            "type": "string",
            "description": "Property value. Must contain at least one non-whitespace character."
          },
          "xheader": {
            "type": "boolean",
            "description": "Defines if a xheader is to be created in the Archive for this email property. The displayed header name will be prefixed with \"X-GR-OC-\""
          },
          "customHeader": {
            "type": "boolean",
            "description": "Defines if a custom header is to be created in the Archive for this email property. The displayed header name will have no added prefix",
            "example": false,
            "default": false
          },
          "hidden": {
            "type": "boolean",
            "description": "If set to true the key value pair in the properties will not appear within the body of the EML. This property field should coincide with the xheader field set to true.",
            "example": false,
            "default": false
          }
        }
      },
      "displayName": {
        "type": "string",
        "description": "The human friendly display name of this user.",
        "example": "Joe Bloggs"
      },
      "companyName": {
        "type": "string",
        "description": "User's company/organisation name.",
        "example": "Corp Company"
      },
      "accountId": {
        "type": "string",
        "description": "In third party products/mailing systems an organisation/company can be divided into many accounts/departments, accountId represents the unique identifier for the account this user belongs to.",
        "example": "123456"
      },
      "accountName": {
        "type": "string",
        "description": "Relative to third party products, the user may belong to a certain account. i.e. the bloomberg mail account this user belongs to.",
        "example": "Bloomberg/ 404 MyCompany"
      },
      "primaryEmail": {
        "type": "string",
        "description": "User's primary email.",
        "example": "joe@example.com"
      },
      "otherAlias": {
        "type": "string",
        "description": "A secondary means of identifying this user.",
        "example": "userJoeBloggs1234"
      },
      "phoneNumber": {
        "type": "string",
        "description": "A phone number associated to this user.",
        "example": "00 44 1234 567890"
      },
      "identityType": {
        "type": "string",
        "description": "Describe the type of user relative to the company being archived, i.e. this user is external to the organisation.",
        "example": "internal",
        "enum": [
          "internal",
          "external",
          "bot"
        ]
      },
      "createEmailResponse": {
        "required": [
          "reconciliationId"
        ],
        "type": "object",
        "properties": {
          "reconciliationId": {
            "type": "string",
            "description": "Unique ID assigned by API service for each request which can be used for reconciliation reporting",
            "nullable": false,
            "example": "c1319852-5367-5958-9aee-98fffdc22493"
          }
        },
        "description": "API responses"
      },
      "createEmailStatusResponse": {
        "required": [
          "reconciliationId",
          "status"
        ],
        "type": "object",
        "properties": {
          "reconciliationId": {
            "type": "string",
            "description": "Unique ID assigned by API service for each request which can be used for reconciliation reporting",
            "nullable": false,
            "example": "c1319852-5367-5958-9aee-98fffdc22493"
          },
          "status": {
            "type": "string",
            "description": "Status of the request, indicating if the request is a duplication of a previous request",
            "nullable": false,
            "example": "duplicate"
          }
        },
        "description": "API responses"
      },
      "ErrorModel": {
        "required": [
          "code",
          "message"
        ],
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "A unique identifier for the error, not necessarily equivalent to HTTP error as it should be more specific. For debugging purposes"
          },
          "message": {
            "type": "string",
            "description": "A human-readable description of the error, and steps to resolve it for the client"
          },
          "moreInformation": {
            "type": "string",
            "description": "URI location for more detailed human readable information regarding this error"
          },
          "context": {
            "type": "object",
            "description": "API-specific contextual information about the error, e.g. a list of invalid/missing fields"
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "An error occurred",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      },
      "Error-429-Rate-Limit-Exceeded-3Scale": {
        "description": "Rate Limit for this endpoint has been exceeded. Check headers for more information.",
        "headers": {
          "ratelimit-limit": {
            "description": "The total number of requests permitted per time period.",
            "schema": {
              "type": "integer"
            }
          },
          "ratelimit-remaining": {
            "description": "The number of requests left on your account for the time window.",
            "schema": {
              "type": "integer"
            }
          },
          "ratelimit-reset": {
            "description": "The number of seconds until the rate limit resets.",
            "schema": {
              "type": "integer",
              "format": "seconds"
            }
          }
        },
        "content": {
          "text/plain": {
            "schema": {
              "type": "string",
              "example": "Limits exceeded"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "oAuth2ClientCredentials": {
        "type": "oauth2",
        "description": "This API uses OAuth2 with the client credentials flow.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "",
            "scopes": {}
          }
        }
      }
    }
  }
}