openapi: 3.0.0 info: description: This is the OAS 3.0 specification for the Sophos Email Management APIs. version: 1.3.0 contact: name: Sophos Central APIs url: 'https://developer.sophos.com' email: apis@sophos.com title: Email Management API tags: - name: Clawback description: Clawback messages from user inbox. - name: Mailbox Management description: Manage mailboxes. - name: Post-Delivery Quarantine description: >- Manage messages in post-delivery quarantine, and perform operations on them. - name: Quarantine description: 'Manage messages in quarantine, and perform operations on them.' servers: - url: 'https://api-{dataRegion}.central.sophos.com/email/v1' description: Regional service in the production environment. variables: dataRegion: description: The data region where tenant data is stored. default: eu01 enum: - eu01 - eu02 - us01 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 security: - bearerAuth: [] paths: /quarantine/messages/search: post: summary: Search quarantine description: >- Summary of all the quarantined messages matching your search and filter conditions. operationId: searchQuarantine tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Search request. required: true content: application/json: schema: type: object required: - beginDate - endDate properties: beginDate: type: string description: >- Messages quarantined on or after this date. Used with endDate. format: date-time example: '2012-06-26T11:55:36.100Z' endDate: type: string description: >- Messages quarantined on or after this date. Used with beginDate. format: date-time example: '2012-06-26T11:55:36.100Z' fields: type: array description: The fields to return in a partial response. items: type: string example: reason pageFromKey: type: string description: From where to start searching the records. pageSize: type: integer description: The size of the page requested. default: 50 maximum: 100 sort: type: array description: >- Defines how to sort the data. Supported fields are from, forRecipient, quarantinedAt. items: type: string example: 'quarantinedAt:DESC' filter: type: object description: Filtering conditions. properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e fromContains: type: string description: >- Return all rows which contains the provided text in from field. example: some text toContains: type: string description: >- Return all rows which contains the provided text in to field. example: some text subjectContains: type: string description: >- Return all rows which contains the provided text in subject field. example: some text attachmentNameContains: type: string description: >- Return all rows which contains the provided text in attachment names. example: some text sizeInMBGreaterThan: type: number description: >- Return all rows where the message size in MB is greater than the provided value. example: 1 sizeInMBLowerThan: type: number description: >- Return all rows where the message size in MB is less than the provided value. example: 2 direction: type: string enum: - inbound - outbound productType: type: string description: Email product. enum: - mailflow - gateway - ems reason: type: array description: >- Return all rows which has the reason provided in the list. items: type: string description: Reason for action. enum: - bulk - dataControl - dkim - dmarc - headerAnomaly - domainAnomaly - impersonation - intelixMalicious - intelixSuspicious - intelixUnscannable - maliciousUrl - malware - s/mime - spam - spf - suspectedSpam - unscannable - countrySpam - languageSpam - batvSpam - nrdSpam example: impersonation hasAnyAttachment: type: boolean description: Return all rows where email has at least one attachment. example: false responses: '200': description: Quarantined messages. content: application/json: schema: type: object description: List of quarantined messages. required: - items - pages properties: pages: type: object required: - maxSize - size properties: fromKey: type: string description: The key of the first item in the returned page. nextKey: type: string description: The key to use when fetching the next page. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: >- (Optional) The total number of items on all the pages, if pageTotal=true was passed into the request. maxSize: type: integer description: The maximum page size that can be requested. items: type: array description: List of quarantined messages. items: allOf: - type: object description: Quarantined message details. required: - id - direction properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' MIME header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e mimeMessageId: type: string description: ID from 'message-id' MIME header. example: <15a7f8ea-691c-4f03-862e-3cefb102818e> envelopeSender: type: object description: Email address and optional display name. required: - localAddress - domainAddress properties: name: type: string description: Name of the sender or recipient. example: Alice localAddress: type: string description: >- Local part of the mail address of the sender or recipient. example: user_alice domainAddress: type: string description: >- Domain part of the mail address of the sender or recipient. example: example.com envelopeRecipients: type: array description: List of envelope email addresses. items: type: object description: Email address and optional display name. required: - localAddress - domainAddress properties: name: type: string description: Name of the sender or recipient. example: Alice localAddress: type: string description: >- Local part of the mail address of the sender or recipient. example: user_alice domainAddress: type: string description: >- Domain part of the mail address of the sender or recipient. example: example.com from: type: object description: Email address and optional display name. required: - localAddress - domainAddress properties: name: type: string description: Name of the sender or recipient. example: Alice localAddress: type: string description: >- Local part of the mail address of the sender or recipient. example: user_alice domainAddress: type: string description: >- Domain part of the mail address of the sender or recipient. example: example.com to: type: array description: >- List of email addresses listed in 'To' MIME header. items: type: object description: Email address and optional display name. required: - localAddress - domainAddress properties: name: type: string description: Name of the sender or recipient. example: Alice localAddress: type: string description: >- Local part of the mail address of the sender or recipient. example: user_alice domainAddress: type: string description: >- Domain part of the mail address of the sender or recipient. example: example.com cc: type: array description: >- List of email addresses listed in 'Cc' MIME header. items: type: object description: Email address and optional display name. required: - localAddress - domainAddress properties: name: type: string description: Name of the sender or recipient. example: Alice localAddress: type: string description: >- Local part of the mail address of the sender or recipient. example: user_alice domainAddress: type: string description: >- Domain part of the mail address of the sender or recipient. example: example.com subject: type: string description: Message subject. example: This is the subject of the email direction: type: string enum: - inbound - outbound sizeInBytes: type: number description: 'Message size, in bytes.' example: '4134' clientIp: type: string description: IP address from where the message was sent. example: 10.223.0.45 sentAt: type: string format: date-time description: Time from 'Date' MIME header. example: '2012-05-26T11:55:36.100Z' receivedAt: type: string format: date-time description: Time the message was received by Sophos Email. example: '2012-05-26T11:55:36.100Z' quarantinedAt: type: string format: date-time description: Time the message was quarantined. example: '2012-05-26T11:55:36.100Z' productType: type: string description: Email product. enum: - mailflow - gateway - ems - type: object properties: attachments: type: object required: - total - size - items properties: total: type: integer description: >- Total number of attachments found in the message. example: 50 size: type: integer description: Number of attachments. example: 25 items: type: array items: type: object description: Attachment details. properties: name: type: string description: Attachment name. example: photo.png sizeInBytes: type: number description: 'Attachment size, in bytes.' example: 374427 fileType: type: string description: Attachment type. example: image stripped: type: boolean description: >- Whether the attachment has been stripped from the message. example: false maxItems: 100 - type: object description: Why the message was quarantined. required: - forRecipient - reason properties: forRecipient: type: string description: Email address for the quarantined message. example: user_alice@domain.com reason: type: string description: Reason for action. enum: - bulk - dataControl - dkim - dmarc - headerAnomaly - domainAnomaly - impersonation - intelixMalicious - intelixSuspicious - intelixUnscannable - maliciousUrl - malware - s/mime - spam - spf - suspectedSpam - unscannable - countrySpam - languageSpam - batvSpam - nrdSpam example: impersonation reasonDetail: type: string description: More information about the cause. example: '{"impersonationType" : "BRAND"}' maxItems: 100 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/quarantine/messages/{id}/preview': get: summary: Preview message description: Preview a message in quarantine. operationId: previewQuarantineMessage tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' MIME header. required: true schema: type: string format: uuid responses: '200': description: Preview of a quarantined message. content: application/json: schema: type: object description: Preview of a quarantined message. properties: headers: type: array description: List of all MIME headers in the message. items: type: string example: 'X-Sophos-Processing-Start-Time: 1603156423403' htmlBody: type: string description: The html body of the message. textBody: type: string description: The text body of the message. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/quarantine/messages/{id}/urls': get: summary: Get urls description: Get all URLs found in body of a quarantined message. operationId: getUrlsInQuarantineMessage tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' MIME header. required: true schema: type: string format: uuid - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' responses: '200': description: URLs in a quarantined message. content: application/json: schema: type: object description: URLs. required: - items - pages properties: pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. items: type: array description: List of URLs in message body. items: type: string example: 'http://google.com' maxItems: 500 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/quarantine/messages/{id}/attachments': get: summary: Get attachments description: Get all attachments of a quaratined message. operationId: getAttachmentsInQuarantineMessage tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' MIME header. required: true schema: type: string format: uuid - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' responses: '200': description: Attachments in a quarantined message. content: application/json: schema: type: object description: A page of attachments. required: - items - pages properties: pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. items: type: array description: Attachments. items: type: object description: Attachment details. properties: name: type: string description: Attachment name. example: photo.png sizeInBytes: type: number description: 'Attachment size, in bytes.' example: 374427 fileType: type: string description: Attachment type. example: image stripped: type: boolean description: >- Whether the attachment has been stripped from the message. example: false maxItems: 500 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /quarantine/messages/release: post: summary: Quarantine release description: Queue one or more messages from quarantine for release. operationId: releaseQuarantineMessage tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Release messages from quarantine. required: true content: application/json: schema: type: object required: - items properties: allowSender: type: boolean default: false description: Whether to add the sender to the allow list. enforceSenderAuthentication: type: boolean default: false description: >- Whether to enforce authentication checks when allowing a sender. submitMessageToLabs: type: boolean default: false description: >- Whether the message needs to be submitted to Sophos Labs as a false positive. Applicable for Spam and Virus messages only. items: type: array description: Items to be released. items: allOf: - type: object required: - id properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' MIME header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e forRecipients: type: array description: Target email addresses. items: type: string example: user_bob@sophos.com - type: object properties: stripAttachments: type: array description: >- Attachments that must be stripped before releasing the message. items: type: string example: employee_details.xslx maxItems: 50 responses: '202': description: Messages accepted for release. content: application/json: schema: type: object properties: items: type: array description: >- List of items for which the requested action was successful. items: type: object required: - id - recipient properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' MIME header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e recipient: type: string description: Target email address. example: user_bob@sophos.com errors: type: array description: List of items for which requested action failed. items: type: object required: - id - recipient properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' MIME header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e recipient: type: string description: >- Email address where there was an error in performing requested action. example: user_bob@sophos.com error: type: string description: Reason for error. example: Already released '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /quarantine/messages/delete: post: summary: Quarantine delete description: Delete one or more messages from quarantine. operationId: deleteQuarantineMessage tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: required: true description: Delete messages from quarantine. content: application/json: schema: type: object required: - items properties: blockSender: type: boolean default: false description: Whether to add the sender to the block list. items: type: array description: Items to be deleted. items: allOf: - type: object required: - id properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' MIME header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e forRecipients: type: array description: Target email addresses. items: type: string example: user_bob@sophos.com - type: object maxItems: 50 responses: '200': description: Messages deleted from quarantine. content: application/json: schema: type: object properties: items: type: array description: >- List of items for which the requested action was successful. items: type: object required: - id - recipient properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' MIME header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e recipient: type: string description: Target email address. example: user_bob@sophos.com errors: type: array description: List of items for which requested action failed. items: type: object required: - id - recipient properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' MIME header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e recipient: type: string description: >- Email address where there was an error in performing requested action. example: user_bob@sophos.com error: type: string description: Reason for error. example: Already released '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/quarantine/messages/{id}/attachments/strip': post: summary: Strip attachments description: Strips one or more attachments from message. operationId: stripQuarantineMessageAttachment tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' MIME header. required: true schema: type: string format: uuid requestBody: description: Strip attachments from a quarantined message. content: application/json: schema: type: object properties: attachments: type: array description: >- List of attachments to strip or reattach. If you specify attachment names, only those attachments are stripped or reattached. items: type: string example: employee.xslx forRecipients: type: array description: Target email addresses. items: type: string example: user_bob@sophos.com responses: '200': description: Attachments stripped from a quarantined message. content: application/json: schema: type: object properties: items: type: array description: List of items for which the action was successful. items: type: object required: - attachment - recipient properties: attachment: type: string description: Attachment name. example: employees.xslx recipient: type: string description: Target email address. example: user_bob@sophos.com errors: type: array description: List of items for which requested action failed. items: type: object required: - attachment - recipient properties: attachment: type: string description: Attachment name. example: employees.xslx recipient: type: string description: Email address associated with failed action. example: user_bob@sophos.com error: type: string description: Reason for error. example: Already released '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/quarantine/messages/{id}/attachments/reattach': post: summary: Reattach attachments description: Reattach one or more attachments to the message. operationId: reAttachQuarantineMessageAttachment tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' MIME header. required: true schema: type: string format: uuid requestBody: description: Reattach attachments to a quarantined message. content: application/json: schema: type: object properties: attachments: type: array description: >- List of attachments to strip or reattach. If you specify attachment names, only those attachments are stripped or reattached. items: type: string example: employee.xslx forRecipients: type: array description: Target email addresses. items: type: string example: user_bob@sophos.com responses: '200': description: Attachments stripped from a quarantined message. content: application/json: schema: type: object properties: items: type: array description: List of items for which the action was successful. items: type: object required: - attachment - recipient properties: attachment: type: string description: Attachment name. example: employees.xslx recipient: type: string description: Target email address. example: user_bob@sophos.com errors: type: array description: List of items for which requested action failed. items: type: object required: - attachment - recipient properties: attachment: type: string description: Attachment name. example: employees.xslx recipient: type: string description: Email address associated with failed action. example: user_bob@sophos.com error: type: string description: Reason for error. example: Already released '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/quarantine/messages/{id}/attachments/download': post: summary: Download attachments description: Download one or more attachments. operationId: downloadQuarantineMessage tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' MIME header. required: true schema: type: string format: uuid requestBody: description: Create a job for downloading attachments from a quarantined message. content: application/json: schema: type: object properties: attachments: type: array description: >- List of attachments to download. If you don't specify which to download, all the attachments in the message are downloaded. items: type: string example: employee.xslx responses: '200': description: Download job created. content: application/json: schema: type: object required: - id - status properties: id: type: string format: uuid description: Download job ID. example: 15a7f8ea-691c-4f03-862e-3cefb102818e status: type: string description: Status of download request. enum: - processing - completed - failed attachments: type: array description: >- List of attachments in the download job. Available when status is completed. items: type: string example: employee.xslx url: type: string description: >- Location where the requested files are available for download. Available when status is completed. example: >- https://sample-bucket.s3.eu-west-1.amazonaws.com/messages/0000/61b0588b939b8a0edced1fa7.zip password: type: string description: Downloaded zip file is password protected. example: ba9b5812800048548195c3616da998e0 error: type: string description: Failure reason. example: attachmentNotFound '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/quarantine/downloads/{downloadId}/status': get: summary: Download job status description: Get status of a download job. operationId: downloadQuarantineStatus tags: - Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: downloadId description: Download request ID. required: true schema: type: string format: uuid responses: '200': description: Status of download job. content: application/json: schema: type: object required: - id - status properties: id: type: string format: uuid description: Download job ID. example: 15a7f8ea-691c-4f03-862e-3cefb102818e status: type: string description: Status of download request. enum: - processing - completed - failed attachments: type: array description: >- List of attachments in the download job. Available when status is completed. items: type: string example: employee.xslx url: type: string description: >- Location where the requested files are available for download. Available when status is completed. example: >- https://sample-bucket.s3.eu-west-1.amazonaws.com/messages/0000/61b0588b939b8a0edced1fa7.zip password: type: string description: Downloaded zip file is password protected. example: ba9b5812800048548195c3616da998e0 error: type: string description: Failure reason. example: attachmentNotFound '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /post-delivery-quarantine/messages/search: post: summary: Search quarantine description: >- Summary of all the post-delivery quarantined messages matching your search and filter conditions. operationId: searchPostDeliveryQuarantine tags: - Post-Delivery Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Search request. required: true content: application/json: schema: type: object required: - beginDate - endDate properties: beginDate: type: string description: >- Messages quarantined on or after this date. Used with endDate. format: date-time example: '2012-06-26T11:55:36.100Z' endDate: type: string description: >- Messages quarantined on or after this date. Used with beginDate. format: date-time example: '2012-06-26T11:55:36.100Z' page: type: integer description: The 1-based index of the page to fetch. default: 1 pageSize: type: integer description: The size of the page requested. default: 50 maximum: 100 sort: type: array description: >- Defines how to sort the data. Supported fields are from, quarantinedAt, forRecipient, and reason. items: type: string example: 'forRecipient:DESC' filter: type: object description: Filtering conditions. properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e fromContains: type: string description: >- Return all rows which contains the provided text in from field. example: some text toContains: type: string description: >- Return all rows which contains the provided text in to field. example: some text subjectContains: type: string description: >- Return all rows which contains the provided text in subject field. example: some text attachmentNameContains: type: string description: >- Return all rows which contains the provided text in attachment names. example: some text sizeInMBGreaterThan: type: number description: >- Return all rows where the message size in MB is greater than the provided value. example: 1 sizeInMBLowerThan: type: number description: >- Return all rows where the message size in MB is less than the provided value. example: 2 productType: type: string description: Email product. enum: - mailflow - gateway - ems reason: type: array items: type: string description: Reason for clawback. enum: - malware - maliciousUrl - onDemand hasAnyAttachment: type: boolean description: Return all rows where email has at least one attachment. example: false responses: '200': description: Post-Delivery quarantined messages. content: application/json: schema: type: object description: List of post-delivery-quarantined messages. required: - items - pages properties: pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. items: type: array description: List of post-delivery-quarantined messages. items: type: object required: - id - quarantinedAt - o365MessageId - reason - forRecipient properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e mimeMessageId: type: string description: ID from 'message-id' MIME header. example: <15a7f8ea-691c-4f03-862e-3cefb102818e> o365MessageId: type: string description: O365 Message id. example: message id envelopeSender: type: object description: Email address and optional display name. required: - localAddress - domainAddress properties: name: type: string description: Name of the sender or recipient. example: Alice localAddress: type: string description: >- Local part of the mail address of the sender or recipient. example: user_alice domainAddress: type: string description: >- Domain part of the mail address of the sender or recipient. example: example.com to: type: array description: List of email addresses listed in 'To' header. items: type: object description: Email address and optional display name. required: - localAddress - domainAddress properties: name: type: string description: Name of the sender or recipient. example: Alice localAddress: type: string description: >- Local part of the mail address of the sender or recipient. example: user_alice domainAddress: type: string description: >- Domain part of the mail address of the sender or recipient. example: example.com cc: type: array description: List of email addresses listed in 'Cc' header. items: type: object description: Email address and optional display name. required: - localAddress - domainAddress properties: name: type: string description: Name of the sender or recipient. example: Alice localAddress: type: string description: >- Local part of the mail address of the sender or recipient. example: user_alice domainAddress: type: string description: >- Domain part of the mail address of the sender or recipient. example: example.com subject: type: string description: Message subject. example: This is the subject of the email sizeInBytes: type: number description: 'Message size, in bytes.' example: '4134' clientIp: type: string description: IP address from where the message was sent. example: 10.223.0.45 sentAt: type: string format: date-time description: Time from 'Date' MIME header. example: '2012-05-26T11:55:36.100Z' quarantinedAt: type: string format: date-time description: Time the message was quarantined post-delivery. example: '2012-05-26T11:55:36.100Z' productType: type: string description: Email product. enum: - mailflow - gateway - ems attachments: type: object required: - total - items properties: total: type: integer description: >- Total number of attachments found in the message. example: 50 items: type: array items: type: object description: Attachment details. properties: name: type: string description: Attachment name. example: photo.png sizeInBytes: type: number description: 'Attachment size, in bytes.' example: 374427 maxItems: 100 forRecipient: type: string description: >- Email address for the post-delivery quarantined message. example: user_alice@domain.com reason: type: string description: Reason for clawback. enum: - malware - maliciousUrl - onDemand '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/post-delivery-quarantine/messages/{id}/preview': get: summary: Preview message description: Preview a message in post-delivery quarantine. operationId: previewPostDeliveryQuarantineMessage tags: - Post-Delivery Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' header. required: true schema: type: string format: uuid responses: '200': description: Preview of a post-delivery quarantined message. content: application/json: schema: type: object description: Preview of a post quarantined message. required: - headers properties: headers: type: array description: List of all MIME headers in the message. items: type: string example: 'X-Sophos-Processing-Start-Time: 1603156423403' htmlBody: type: string description: The html body of the message. textBody: type: string description: The text body of the message. '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/post-delivery-quarantine/messages/{id}/attachments': get: summary: Get attachments description: Get all attachments of a post-delivery quarantined message. operationId: getAttachmentsInPostDeliveryQuarantineMessage tags: - Post-Delivery Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' header. required: true schema: type: string format: uuid - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' responses: '200': description: Attachments in a post-delivery quarantined message. content: application/json: schema: type: object description: A page of attachments. required: - items - pages properties: pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. items: type: array description: Attachments. items: type: object description: Attachment details. properties: name: type: string description: Attachment name. example: photo.png sizeInBytes: type: number description: 'Attachment size, in bytes.' example: 374427 maxItems: 500 '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /post-delivery-quarantine/messages/release: post: summary: Quarantine release description: Queue one or more messages from post-delivery quarantine for release. operationId: releasePostDeliveryQuarantineMessage tags: - Post-Delivery Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Release messages from post-delivery quarantine. required: true content: application/json: schema: type: object required: - items properties: items: type: array items: type: object required: - id properties: id: description: ID from 'X-Sophos-Email-ID' header. type: string format: uuid example: fcec2f92-68a3-4ce6-9387-a74547a4f72e forRecipients: type: array description: Target email addresses. items: type: string example: user_bob@sophos.com maxItems: 50 responses: '202': description: Messages accepted for release. content: application/json: schema: type: object properties: items: type: array description: >- List of items for which the requested action was successful. items: type: object required: - id - recipient properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e recipient: type: string description: Target email address. example: user_bob@sophos.com errors: type: array description: List of items for which requested action failed. items: type: object required: - id - recipient properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e recipient: type: string description: >- Email address where there was an error in performing requested action. example: user_bob@sophos.com error: type: string description: Reason for error. example: Already released '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /post-delivery-quarantine/messages/delete: post: summary: Quarantine delete description: Delete one or more messages from post quarantine. operationId: deletePostDeliveryQuarantineMessage tags: - Post-Delivery Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Delete messages from post-delivery quarantine. required: true content: application/json: schema: type: object required: - items properties: items: type: array items: type: object required: - id properties: id: description: ID from 'X-Sophos-Email-ID' header. type: string format: uuid example: fcec2f92-68a3-4ce6-9387-a74547a4f72e forRecipients: type: array description: Target email addresses. items: type: string example: user_bob@sophos.com maxItems: 50 responses: '200': description: Messages deleted from post-delivery quarantine. content: application/json: schema: type: object properties: items: type: array description: >- List of items for which the requested action was successful. items: type: object required: - id - recipient properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e recipient: type: string description: Target email address. example: user_bob@sophos.com errors: type: array description: List of items for which requested action failed. items: type: object required: - id - recipient properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e recipient: type: string description: >- Email address where there was an error in performing requested action. example: user_bob@sophos.com error: type: string description: Reason for error. example: Already released '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/post-delivery-quarantine/messages/{id}/attachments/download': post: summary: Download attachments description: Download one ore more attachments. operationId: downloadPostDeliveryQuarantineMessage tags: - Post-Delivery Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' header. required: true schema: type: string format: uuid requestBody: description: >- A request to create a job for downloading attachments from a post-delivery quarantined message. content: application/json: schema: type: object properties: attachments: type: array description: >- List of attachments to download. If you don't specify which to download, all the attachments in the message are downloaded. items: type: string example: employee.xslx responses: '200': description: Download job created. content: application/json: schema: type: object required: - id - status properties: id: type: string format: uuid description: Download job ID. example: 15a7f8ea-691c-4f03-862e-3cefb102818e status: type: string description: Status of download request. enum: - processing - completed - failed attachments: type: array description: >- List of attachments in the download job. Available when status is completed. items: type: string example: employee.xslx url: type: string description: >- Location where the requested files are available for download. Available when status is completed. example: >- https://sample-bucket.s3.eu-west-1.amazonaws.com/messages/0000/61b0588b939b8a0edced1fa7.zip password: type: string description: Downloaded zip file is password protected. example: ba9b5812800048548195c3616da998e0 error: type: string description: Failure reason. example: attachmentNotFound '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/post-delivery-quarantine/downloads/{downloadId}/status': get: summary: Download job status description: Get status of a download job. operationId: downloadPostDeliveryQuarantineStatus tags: - Post-Delivery Quarantine parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: downloadId description: Download request ID. required: true schema: type: string format: uuid responses: '200': description: Status of download job. content: application/json: schema: type: object required: - id - status properties: id: type: string format: uuid description: Download job ID. example: 15a7f8ea-691c-4f03-862e-3cefb102818e status: type: string description: Status of download request. enum: - processing - completed - failed attachments: type: array description: >- List of attachments in the download job. Available when status is completed. items: type: string example: employee.xslx url: type: string description: >- Location where the requested files are available for download. Available when status is completed. example: >- https://sample-bucket.s3.eu-west-1.amazonaws.com/messages/0000/61b0588b939b8a0edced1fa7.zip password: type: string description: Downloaded zip file is password protected. example: ba9b5812800048548195c3616da998e0 error: type: string description: Failure reason. example: attachmentNotFound '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/messages/{id}/clawback': post: summary: Clawback message description: Clawback message (can clawback message for specific recipients). x-soph-permissions: 'xgemail.msghistory:write' operationId: clawbackMessage tags: - Clawback parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' MIME header. required: true schema: type: string requestBody: description: Clawback messages from recipient's inbox. content: application/json: schema: type: object properties: recipients: type: array description: >- Target email addresses. If not specified, clawback is attempted for all recipients. items: type: string example: user_bob@sophos.com maxItems: 500 reason: type: string description: Clawback reason. enum: - malware - phishing - spam - unwanted example: phishing responses: '202': description: Clawback request accepted. content: application/json: schema: type: object properties: id: type: string format: uuid description: ID from 'X-Sophos-Email-ID' MIME header. example: 15a7f8ea-691c-4f03-862e-3cefb102818e recipients: type: array description: >- List of recipients for whom the clawback request was accepted. items: type: string example: user_bob@sophos.com errors: type: array description: >- List of recipients for whom clawback request was not accepted. items: type: object required: - recipient - error properties: recipient: type: string example: user_bob@sophos.com error: type: string description: Reason for error. example: clawbackNotSupported '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Authentication required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Authorization required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/messages/{id}/status': get: summary: Message status description: Get current status of a message. x-soph-permissions: 'xgemail.msghistory:read' operationId: messageStatus tags: - Clawback parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: ID from 'X-Sophos-Email-ID' MIME header. required: true schema: type: string responses: '200': description: Status of clawback job. content: application/json: schema: type: object properties: items: type: array description: Current status for each recipient. items: type: object properties: recipient: description: Recipient address. type: string example: user_bob@sophos.com status: type: string description: The current status of the message. enum: - accepted - deleted - quarantined - bounced - redirected - processing - deliverySuccessful - deliveryFailed - queuedForDelivery - pdfEncryption - tlsDelivery - tlsDeliveryFailed - encryptedDelivery - portalDelivery - clawbackProcessing - clawbackSuccessful - clawbackFailed example: clawbackSuccessful '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '401': description: Authentication required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '403': description: Authorization required. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /mailboxes: get: summary: Query Mailboxes description: List all mailboxes or search mailboxes based on query parameter. operationId: listMailboxes tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: pageFromKey required: false schema: type: string description: The key of the item from where to fetch a page. - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: name required: false description: Name of the mailbox. schema: type: string example: John Doe - in: query name: nameStartsWith required: false description: Mailboxes where the name starts with the given string. schema: type: string example: Joh - in: query name: email required: false description: Email address of the mailbox. schema: type: string format: email example: johndoe@example.com - in: query name: emailStartsWith required: false description: Mailboxes where the email address starts with the given string. schema: type: string example: joh - in: query name: createdAfter required: false description: Mailboxes created after the given date or date and time. schema: type: string format: datetime example: '2012-06-26T11:55:36.100Z' - in: query name: createdBefore required: false description: Mailboxes created before the given date or date and time. schema: type: string format: datetime example: '2012-06-26T11:55:36.100Z' - in: query name: type required: false description: Mailbox type. schema: type: string description: Mailbox type. enum: - user - distributionList - publicFolder - sharedMailbox example: user - in: query name: bulkSenderPrivilegeStatus required: false description: Bulk sender privilege status of the mailbox. schema: type: string description: Bulk sender privilege status of the mailbox. enum: - neverRequested - approvalPending - approved - rejected - revoked example: approved - in: query name: blocked required: false description: Status of the mailbox. schema: type: boolean example: true - in: query name: distributionListOwnedBy required: false description: >- Name or email address of the distribution list owner to find the distribution list mailboxes owned by the mailbox. schema: type: string example: John Doe - in: query name: alias required: false description: Mailbox of specified alias. schema: type: string example: johndoe@example.com format: email - in: query name: aliasesStartWith required: false description: Mailboxes where the alias starts with the given string. schema: type: string example: john - in: query name: delegate required: false description: Email address of the mailbox to find delegated mailbox. schema: type: string example: johndoe@example.com format: email responses: '200': description: List of mailboxes. content: application/json: schema: type: object description: List of mailboxes. properties: pages: type: object required: - size - maxSize properties: fromKey: type: string description: The key of the first item in the returned page. nextKey: type: string description: The key to use when fetching the next page. size: type: integer description: The size of the page being returned. maxSize: type: integer description: The maximum page size that can be requested. items: type: array description: List of mailboxes. items: type: object description: Mailbox. required: - id - type - email - name - createdAt - blocked properties: id: description: Mailbox ID. type: string format: uuid type: type: string description: Mailbox type. enum: - user - distributionList - publicFolder - sharedMailbox example: user email: description: Email address. type: string name: description: Name. type: string createdAt: type: string format: date-time description: 'Creation date of the mailbox, in ISO 8601 format.' bulkSenderPrivilege: type: object description: Bulk sender privilege. required: - bulkSenderPrivilegeStatus properties: bulkSenderPrivilegeStatus: type: string description: Bulk sender privilege status of the mailbox. enum: - neverRequested - approvalPending - approved - rejected - revoked example: approved blocked: type: boolean description: Status of the mailbox. distributionListOwners: description: Owners of the distribution list mailbox. type: array items: type: string aliases: description: Aliases of the mailbox. type: array items: type: string delegates: description: Delegates of the mailbox. type: array items: type: string policies: type: object description: Policies applied to the mailbox. required: - emailSecurity - dataControl - secureMessage properties: emailSecurity: description: Email security policies applied to the mailbox. type: array items: type: string example: - John Doe policy - Base Policy dataControl: description: Data control policies applied to the mailbox. type: array items: type: string example: - Block credit card - Base Policy secureMessage: description: Secure message policies applied to the mailbox. type: array items: type: string example: - Base Policy '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: summary: Add mailbox description: Add a new mailbox. operationId: addNewMailbox tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Add mailbox request. required: true content: application/json: schema: type: object description: Add a new mailbox. required: - type - email - name properties: type: type: string description: Mailbox type. enum: - user - distributionList - publicFolder - sharedMailbox example: user email: description: Email address. type: string format: email minLength: 4 maxLength: 320 name: description: Name. type: string minLength: 1 maxLength: 256 responses: '201': description: A new mailbox is added. content: application/json: schema: type: object description: Mailbox. required: - id - type - email - name - createdAt - blocked properties: id: description: Mailbox ID. type: string format: uuid type: type: string description: Mailbox type. enum: - user - distributionList - publicFolder - sharedMailbox example: user email: description: Email address. type: string name: description: Name. type: string createdAt: type: string format: date-time description: 'Creation date of the mailbox, in ISO 8601 format.' bulkSenderPrivilege: type: object description: Bulk sender privilege. required: - bulkSenderPrivilegeStatus properties: bulkSenderPrivilegeStatus: type: string description: Bulk sender privilege status of the mailbox. enum: - neverRequested - approvalPending - approved - rejected - revoked example: approved blocked: type: boolean description: Status of the mailbox. distributionListOwners: description: Owners of the distribution list mailbox. type: array items: type: string aliases: description: Aliases of the mailbox. type: array items: type: string delegates: description: Delegates of the mailbox. type: array items: type: string policies: type: object description: Policies applied to the mailbox. required: - emailSecurity - dataControl - secureMessage properties: emailSecurity: description: Email security policies applied to the mailbox. type: array items: type: string example: - John Doe policy - Base Policy dataControl: description: Data control policies applied to the mailbox. type: array items: type: string example: - Block credit card - Base Policy secureMessage: description: Secure message policies applied to the mailbox. type: array items: type: string example: - Base Policy '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Mailbox or alias already exists with email address. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /mailboxes/bulk: post: summary: Add mailboxes description: Request to add multiple mailboxes. operationId: addMailboxesInBulk tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Add multiple mailbox request. required: true content: application/json: schema: type: object description: Add multiple mailboxes. required: - items properties: items: type: array description: List of new mailboxes. maxItems: 10 items: type: object description: Add a new mailbox. required: - type - email - name properties: type: type: string description: Mailbox type. enum: - user - distributionList - publicFolder - sharedMailbox example: user email: description: Email address. type: string format: email minLength: 4 maxLength: 320 name: description: Name. type: string minLength: 1 maxLength: 256 responses: '201': description: All or few mailboxes are added. content: application/json: schema: type: object description: Response of add multiple mailboxes. properties: items: type: array description: List of successfully added mailboxes. items: type: object description: Mailbox. required: - id - type - email - name - createdAt - blocked properties: id: description: Mailbox ID. type: string format: uuid type: type: string description: Mailbox type. enum: - user - distributionList - publicFolder - sharedMailbox example: user email: description: Email address. type: string name: description: Name. type: string createdAt: type: string format: date-time description: 'Creation date of the mailbox, in ISO 8601 format.' bulkSenderPrivilege: type: object description: Bulk sender privilege. required: - bulkSenderPrivilegeStatus properties: bulkSenderPrivilegeStatus: type: string description: Bulk sender privilege status of the mailbox. enum: - neverRequested - approvalPending - approved - rejected - revoked example: approved blocked: type: boolean description: Status of the mailbox. distributionListOwners: description: Owners of the distribution list mailbox. type: array items: type: string aliases: description: Aliases of the mailbox. type: array items: type: string delegates: description: Delegates of the mailbox. type: array items: type: string policies: type: object description: Policies applied to the mailbox. required: - emailSecurity - dataControl - secureMessage properties: emailSecurity: description: Email security policies applied to the mailbox. type: array items: type: string example: - John Doe policy - Base Policy dataControl: description: Data control policies applied to the mailbox. type: array items: type: string example: - Block credit card - Base Policy secureMessage: description: Secure message policies applied to the mailbox. type: array items: type: string example: - Base Policy errors: type: array description: List of items for which mailbox addition failed. items: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /mailboxes/delete: post: summary: Delete mailboxes description: Delete multiple mailboxes. operationId: deleteMailboxes tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid requestBody: description: Delete multiple mailbox request. required: true content: application/json: schema: type: object description: Delete multiple mailboxes. required: - items properties: items: type: array description: List of mailbox IDs. maxItems: 20 items: type: object description: Mailbox ID. required: - id properties: id: description: Mailbox ID. type: string format: uuid responses: '200': description: All or few mailboxes successfully deleted. content: application/json: schema: type: object description: Response of delete multiple mailboxes. properties: items: type: array description: List of mailbox IDs for successfully deleted mailboxes. items: type: object description: Mailbox ID. required: - id properties: id: description: Mailbox ID. type: string format: uuid errors: type: array description: List of mailbox IDs for which mailbox deletion failed. items: type: object description: Error message. required: - id - error properties: id: description: Mailbox ID for which mailbox deletion was failed. type: string format: uuid error: description: Reason of mailbox deletion failure. type: string '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/mailboxes/{id}': get: summary: Get mailbox description: Get information of the mailbox. operationId: getMailbox tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: Mailbox ID. required: true schema: type: string format: uuid responses: '200': description: Information of the mailbox. content: application/json: schema: type: object description: Mailbox. required: - id - type - email - name - createdAt - blocked properties: id: description: Mailbox ID. type: string format: uuid type: type: string description: Mailbox type. enum: - user - distributionList - publicFolder - sharedMailbox example: user email: description: Email address. type: string name: description: Name. type: string createdAt: type: string format: date-time description: 'Creation date of the mailbox, in ISO 8601 format.' bulkSenderPrivilege: type: object description: Bulk sender privilege. required: - bulkSenderPrivilegeStatus properties: bulkSenderPrivilegeStatus: type: string description: Bulk sender privilege status of the mailbox. enum: - neverRequested - approvalPending - approved - rejected - revoked example: approved blocked: type: boolean description: Status of the mailbox. distributionListOwners: description: Owners of the distribution list mailbox. type: array items: type: string aliases: description: Aliases of the mailbox. type: array items: type: string delegates: description: Delegates of the mailbox. type: array items: type: string policies: type: object description: Policies applied to the mailbox. required: - emailSecurity - dataControl - secureMessage properties: emailSecurity: description: Email security policies applied to the mailbox. type: array items: type: string example: - John Doe policy - Base Policy dataControl: description: Data control policies applied to the mailbox. type: array items: type: string example: - Block credit card - Base Policy secureMessage: description: Secure message policies applied to the mailbox. type: array items: type: string example: - Base Policy '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Mailbox not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: summary: Update name description: Update name of the mailbox. operationId: updateMailbox tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: Mailbox ID. required: true schema: type: string format: uuid requestBody: description: Update name of the mailbox. required: true content: application/json: schema: type: object description: Update the mailbox. properties: name: description: Name. type: string minLength: 1 maxLength: 256 responses: '201': description: Mailbox updated. content: application/json: schema: type: object description: Mailbox. required: - id - type - email - name - createdAt - blocked properties: id: description: Mailbox ID. type: string format: uuid type: type: string description: Mailbox type. enum: - user - distributionList - publicFolder - sharedMailbox example: user email: description: Email address. type: string name: description: Name. type: string createdAt: type: string format: date-time description: 'Creation date of the mailbox, in ISO 8601 format.' bulkSenderPrivilege: type: object description: Bulk sender privilege. required: - bulkSenderPrivilegeStatus properties: bulkSenderPrivilegeStatus: type: string description: Bulk sender privilege status of the mailbox. enum: - neverRequested - approvalPending - approved - rejected - revoked example: approved blocked: type: boolean description: Status of the mailbox. distributionListOwners: description: Owners of the distribution list mailbox. type: array items: type: string aliases: description: Aliases of the mailbox. type: array items: type: string delegates: description: Delegates of the mailbox. type: array items: type: string policies: type: object description: Policies applied to the mailbox. required: - emailSecurity - dataControl - secureMessage properties: emailSecurity: description: Email security policies applied to the mailbox. type: array items: type: string example: - John Doe policy - Base Policy dataControl: description: Data control policies applied to the mailbox. type: array items: type: string example: - Block credit card - Base Policy secureMessage: description: Secure message policies applied to the mailbox. type: array items: type: string example: - Base Policy '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Mailbox not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Directory synced mailbox. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: summary: Delete mailbox description: Delete the mailbox. operationId: deleteMailbox tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: Mailbox ID. required: true schema: type: string format: uuid responses: '200': description: Mailbox deleted or can't find mailbox. content: application/json: schema: type: object description: Response of delete the mailbox. required: - deleted properties: deleted: type: boolean description: Mailbox deleted. '409': description: Directory synced mailbox. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/mailboxes/{id}/aliases': post: summary: Change aliases description: Add and remove aliases of the mailbox. operationId: updateAliases tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: Mailbox ID. required: true schema: type: string format: uuid requestBody: description: Update aliases request. required: true content: application/json: schema: type: object description: Add and remove aliases of the mailbox. properties: add: description: Add aliases of the mailbox. type: array maxItems: 100 items: type: string remove: description: Remove aliases of the mailbox. type: array maxItems: 100 items: type: string responses: '200': description: All or few aliases updated. content: application/json: schema: type: object description: Response of add and remove aliases of the mailbox. properties: added: description: Successfully added aliases of the mailbox. type: array items: type: string removed: description: Successfully removed aliases of the mailbox. type: array items: type: string errors: type: object description: Failed to add and remove from the mailbox. properties: failedToAdd: description: Failed to add. type: array items: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri failedToRemove: description: Failed to remove. type: array items: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Mailbox not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Directory synced mailbox. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/mailboxes/{id}/delegates': post: summary: Change delegates description: Add and remove delegates of the mailbox. operationId: updateDelegates tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: Mailbox ID. required: true schema: type: string format: uuid requestBody: description: Update delegates request. required: true content: application/json: schema: type: object description: Add and remove delegates of the mailbox. properties: add: description: Add delegates of the mailbox. type: array maxItems: 50 items: type: string remove: description: Remove delegates of the mailbox. type: array maxItems: 50 items: type: string responses: '200': description: All or few delegates updated. content: application/json: schema: type: object description: Response of add and remove delegates of the mailbox. properties: added: description: Successfully added delegates of the mailbox. type: array items: type: string removed: description: Successfully removed delegates of the mailbox. type: array items: type: string errors: type: object description: Failed to add and remove from the mailbox. properties: failedToAdd: description: Failed to add. type: array items: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri failedToRemove: description: Failed to remove. type: array items: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Mailbox not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Directory synced mailbox. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/mailboxes/{id}/distribution-list-owners': post: summary: Change DL owners description: Add and remove distribution list owners of the mailbox. operationId: updateDistributionListOwners tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: Mailbox ID. required: true schema: type: string format: uuid requestBody: description: Update distribution list owners request. required: true content: application/json: schema: type: object description: Add and remove distribution list owners of the mailbox. properties: add: description: Add distribution list owners of the mailbox. type: array maxItems: 1 items: type: string remove: description: Remove distribution list owners of the mailbox. type: array maxItems: 1 items: type: string responses: '200': description: All or few distribution list owners updated. content: application/json: schema: type: object description: >- Response of add and remove distribution list owners of the mailbox. properties: added: description: >- Successfully added distribution list owners of the mailbox. type: array items: type: string removed: description: >- Successfully removed distribution list owners of the mailbox. type: array items: type: string errors: type: object description: Failed to add and remove from the mailbox. properties: failedToAdd: description: Failed to add. type: array items: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri failedToRemove: description: Failed to remove. type: array items: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Mailbox not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/mailboxes/{id}/bulksender-privilege-request': post: summary: Bulk privilege description: Generate request to get bulk sender privilege for the mailbox. operationId: bulkSenderPrivilegeRequest tags: - Mailbox Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: id description: Mailbox ID. required: true schema: type: string format: uuid requestBody: description: Bulk sender privilege request. required: true content: application/json: schema: type: object description: Request for bulk sender privilege for the mailbox. required: - count - period - purpose properties: count: description: Number of emails per period. type: integer period: type: string description: Interval type. enum: - daily - weekly - monthly example: daily purpose: description: Purpose to send bulk emails. type: string minLength: 2 maxLength: 2048 responses: '200': description: Status of bulk sender privilege request. content: application/json: schema: type: object description: Bulk sender privilege response. required: - accepted properties: accepted: description: Bulk sender privilege request accepted or not. type: boolean '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Not found. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT