{
  "openapi": "3.0.3",
  "info": {
    "title": "SecuMailer Events REST API",
    "version": "3.0"
  },
  "servers": [
    {
      "url": "https://test-public-api.secumail.nl/event/v3",
      "description": "Acceptance environment"
    },
    {
      "url": "https://public-api.secumail.nl/event/v3",
      "description": "Production environment"
    }
  ],
  "paths": {
    "/event": {
      "get": {
        "tags": [
          "events"
        ],
        "summary": "Get event data",
        "description": "Returns event data for all domains belonging to the authenticated account, or for one or more domains specified explicitly. Results can be filtered by time range and event type, and paginated either by offset (via 'search_from'/'size') or by cursor (via 'search_after').",
        "operationId": "getEvents",
        "parameters": [
          {
            "name": "search_from",
            "in": "query",
            "description": "The document number from which to start showing results. Results are zero-indexed, so the first page of a series of paginated requests should use 0. Works together with the optional 'size' parameter. Defaults to 0 when omitted.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            },
            "example": 20
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 100
          },
          {
            "name": "date_start",
            "in": "query",
            "description": "Start datetime for the search, in ISO 8601 extended format. The timezone must be either 'Z' or a ':'-delimited UTC offset (e.g. '+02:00'). Offsets without a colon (e.g. '+0200') are rejected.",
            "required": true,
            "schema": {
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$",
              "type": "string",
              "format": "date-time"
            },
            "example": "2019-09-26T07:58:30+02:00"
          },
          {
            "name": "date_end",
            "in": "query",
            "description": "End datetime for the search, in the same ISO 8601 extended format as 'date_start'. If omitted, defaults to the current datetime. Must not precede 'date_start'.",
            "required": false,
            "schema": {
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$",
              "type": "string",
              "format": "date-time"
            },
            "example": "2019-09-26T09:00:00+02:00"
          },
          {
            "name": "domain",
            "in": "query",
            "description": "The domain or domains to filter events by. Every domain supplied must belong to the authenticated account, or the request is rejected with 403. If omitted, events for all domains belonging to the account are returned.",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "examples": {
              "oneDomain": {
                "summary": "Example of a single domain",
                "value": "example.com"
              },
              "multipleDomains": {
                "summary": "Example of multiple domains",
                "value": "domain[]=example.com&domain[]=example.org&domain[]=example.net"
              }
            }
          },
          {
            "name": "event_type",
            "in": "query",
            "description": "Filter for a specific event type. Matching is exact but case-insensitive, and is not limited to the standard mail lifecycle types (e.g. 'send', 'delivery', 'bounce', 'complaint') - any event type the account has data for is supported, including application-specific event types that contain hyphens (e.g. 'transaction-completed'). If omitted, results include all event types. For a list of supported event types, refer to https://legalbot.atlassian.net/wiki/spaces/SEC/pages/2177105921/Kibana+events",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "delivery"
          },
          {
            "name": "search_after",
            "in": "query",
            "description": "Cursor for pagination, as an alternative to 'search_from'/'size'. Pass the 'sort' value of the last event from a previous response, serialized as a comma-separated list, to fetch results starting immediately after that event. Must contain exactly two comma-separated values.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1706533517906,0102018d5552fa52-6a865fb0-c30f-4be0-8695-263dc9147ef3-000000"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request. Your request contains errors.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ProblemDetails"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "integer",
                          "example": 400
                        },
                        "detail": {
                          "type": "string",
                          "enum": [
                            "[001] The querystring contains one or more unsupported parameters.",
                            "[002] The search_from parameter is invalid.",
                            "[003] The search_after parameter is invalid.",
                            "[004] The size parameter is invalid.",
                            "[005] The date_start parameter is missing or empty.",
                            "[006] The date_start parameter has an invalid format.",
                            "[007] The date_start parameter is not a valid date.",
                            "[008] The date_end parameter is empty.",
                            "[009] The date_end parameter has an invalid format.",
                            "[010] The date_end parameter is not a valid date.",
                            "[011] The date_end parameter preceeds the date_start parameter."
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Returned by the application when the API key is not associated with an account, has no mailbox or domain bindings, or one or more requested domains do not belong to the account (body: a ProblemDetails object). When no API key is provided at all, a simpler message is returned (body: {\"message\": \"Forbidden\"}).",
            "content": {
              "application/json": {
                "schema": {
                  "required": [
                    "message"
                  ],
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Forbidden"
                    }
                  }
                }
              },
              "application/problem+json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ProblemDetails"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "integer",
                          "example": 403
                        },
                        "detail": {
                          "type": "string",
                          "enum": [
                            "[012] API key not configured. Contact Support.",
                            "[013] API key has no mailbox bindings. Contact Support.",
                            "[015] API key has no domain bindings. Contact Support.",
                            "[016] Invalid domain. Contact Support."
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ProblemDetails"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "integer",
                          "example": 500
                        },
                        "detail": {
                          "type": "string",
                          "enum": []
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ProblemDetails": {
        "required": [
          "detail",
          "instance",
          "status",
          "title",
          "type"
        ],
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "A URI reference identifying this problem type; currently always points to this API's documentation.",
            "format": "uri",
            "example": "https://app.swaggerhub.com/apis/SecuMailer/Events/3.0.1#/events/getEvents"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code, repeated in the body."
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence, prefixed with a stable numeric error code in brackets (e.g. '[002] ...') that can be used for programmatic handling."
          },
          "instance": {
            "type": "string",
            "description": "A URI reference identifying this specific occurrence. Currently always an empty string.",
            "example": ""
          }
        },
        "description": "RFC 9457-style problem details object returned for 4xx/5xx responses."
      },
      "EventSearchResponse": {
        "required": [
          "api.version",
          "events",
          "matches"
        ],
        "type": "object",
        "properties": {
          "api.version": {
            "type": "string",
            "description": "The version of the API that produced this response.",
            "example": "3.0"
          },
          "matches": {
            "type": "integer",
            "description": "The total number of events that match the search criteria (may exceed the number of items in 'events')."
          },
          "events": {
            "type": "array",
            "description": "The page of matching events, ordered by mail.timestamp ascending.",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          }
        }
      },
      "Event": {
        "required": [
          "category",
          "eventType",
          "sort"
        ],
        "type": "object",
        "properties": {
          "eventType": {
            "type": "string",
            "description": "The event type, lower-cased, e.g. 'send', 'delivery', 'bounce', 'complaint', or a custom application event type. For a list of event types, refer to https://legalbot.atlassian.net/wiki/spaces/SEC/pages/2177105921/Kibana+events",
            "example": "delivery"
          },
          "category": {
            "type": "string",
            "description": "'email' for the standard mail lifecycle event types, 'process' for any other (e.g. application/business) event type.",
            "enum": [
              "email",
              "process"
            ]
          },
          "sort": {
            "type": "array",
            "description": "Opaque sort key from the underlying search index. Pass it back via 'search_after' (as a comma-separated string) to fetch results starting after this event.",
            "items": {}
          },
          "mail": {
            "$ref": "#/components/schemas/MailObject"
          },
          "delivery": {
            "$ref": "#/components/schemas/DeliveryObject"
          },
          "bounce": {
            "$ref": "#/components/schemas/BounceObject"
          },
          "complaint": {
            "$ref": "#/components/schemas/ComplaintObject"
          }
        },
        "additionalProperties": true,
        "description": "The underlying event document. Beyond the properties listed below, additional attributes are passed through as-is and vary by event type - custom application event types carry whatever payload was recorded for them, which this schema does not constrain."
      },
      "MailObject": {
        "type": "object",
        "properties": {
          "headers": {
            "type": "array",
            "description": "The email's original headers.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          },
          "destination": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          },
          "headersTruncated": {
            "type": "boolean"
          },
          "messageId": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "description": "Sending email address (the \"From\" mailbox)."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "commonHeaders": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string"
              },
              "subject": {
                "type": "string"
              },
              "messageId": {
                "type": "string"
              },
              "from": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "to": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "replyTo": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "cc": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "bcc": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "tags": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "SES tags associated with the send, keyed by tag name (e.g. 'ses:from-domain', 'ses:source-ip')."
          }
        },
        "description": "The original SES mail object recorded for the event."
      },
      "DeliveryObject": {
        "type": "object",
        "properties": {
          "smtpResponse": {
            "type": "string"
          },
          "processingTimeMillis": {
            "type": "integer"
          },
          "recipients": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          },
          "reportingMTA": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "description": "Present when 'eventType' is 'delivery'."
      },
      "BounceObject": {
        "type": "object",
        "properties": {
          "bounceType": {
            "type": "string",
            "enum": [
              "Permanent",
              "Transient",
              "Undetermined"
            ]
          },
          "bounceSubType": {
            "type": "string"
          },
          "bouncedRecipients": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "emailAddress": {
                  "type": "string",
                  "format": "email"
                },
                "action": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "diagnosticCode": {
                  "type": "string"
                }
              }
            }
          },
          "feedbackId": {
            "type": "string"
          },
          "reportingMTA": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "description": "Present when 'eventType' is 'bounce'."
      },
      "ComplaintObject": {
        "type": "object",
        "properties": {
          "complaintSubType": {
            "type": "string",
            "nullable": true
          },
          "complainedRecipients": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "emailAddress": {
                  "type": "string",
                  "format": "email"
                }
              }
            }
          },
          "complaintFeedbackType": {
            "type": "string",
            "enum": [
              "abuse",
              "auth-failure",
              "fraud",
              "not-spam",
              "other",
              "virus"
            ]
          },
          "userAgent": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "arrivalDate": {
            "type": "string",
            "format": "date-time"
          }
        },
        "description": "Present when 'eventType' is 'complaint'."
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
      }
    }
  },
  "tags": []
}