diff --git a/404.html b/404.html index 1f791af..61a22da 100644 --- a/404.html +++ b/404.html @@ -9,7 +9,7 @@ - + @@ -18,7 +18,7 @@
- + \ No newline at end of file diff --git a/SUMMARY.html b/SUMMARY.html index 3f09fe7..8b7e50e 100644 --- a/SUMMARY.html +++ b/SUMMARY.html @@ -9,9 +9,9 @@ - + - + @@ -20,8 +20,8 @@ -
Skip to content
- +
Skip to content
+ \ No newline at end of file diff --git a/api/archived-email.html b/api/archived-email.html index 5cea3c9..5fb085e 100644 --- a/api/archived-email.html +++ b/api/archived-email.html @@ -9,9 +9,9 @@ - + - + @@ -20,7 +20,7 @@ -
Skip to content

Archived Email Service API

The Archived Email Service is responsible for retrieving archived emails and their details from the database and storage.

Endpoints

All endpoints in this service require authentication.

GET /api/v1/archived-emails/ingestion-source/:ingestionSourceId

Retrieves a paginated list of archived emails for a specific ingestion source.

Access: Authenticated

URL Parameters

ParameterTypeDescription
ingestionSourceIdstringThe ID of the ingestion source to get emails for.

Query Parameters

ParameterTypeDescriptionDefault
pagenumberThe page number for pagination.1
limitnumberThe number of items per page.10

Responses

  • 200 OK: A paginated list of archived emails.

    json
    {
    +    
    Skip to content

    Archived Email Service API

    The Archived Email Service is responsible for retrieving archived emails and their details from the database and storage.

    Endpoints

    All endpoints in this service require authentication.

    GET /api/v1/archived-emails/ingestion-source/:ingestionSourceId

    Retrieves a paginated list of archived emails for a specific ingestion source.

    Access: Authenticated

    URL Parameters

    ParameterTypeDescription
    ingestionSourceIdstringThe ID of the ingestion source to get emails for.

    Query Parameters

    ParameterTypeDescriptionDefault
    pagenumberThe page number for pagination.1
    limitnumberThe number of items per page.10

    Responses

    • 200 OK: A paginated list of archived emails.

      json
      {
       	"items": [
       		{
       			"id": "email-id",
      @@ -51,7 +51,7 @@
       		}
       	]
       }
    • 404 Not Found: The archived email with the specified ID was not found.

    • 500 Internal Server Error: An unexpected error occurred.

    Service Methods

    getArchivedEmails(ingestionSourceId: string, page: number, limit: number): Promise<PaginatedArchivedEmails>

    Retrieves a paginated list of archived emails from the database for a given ingestion source.

    • ingestionSourceId: The ID of the ingestion source.
    • page: The page number for pagination.
    • limit: The number of items per page.
    • Returns: A promise that resolves to a PaginatedArchivedEmails object.

    getArchivedEmailById(emailId: string): Promise<ArchivedEmail | null>

    Retrieves a single archived email by its ID, including its raw content and attachments.

    • emailId: The ID of the archived email.
    • Returns: A promise that resolves to an ArchivedEmail object or null if not found.
    - + \ No newline at end of file diff --git a/api/auth.html b/api/auth.html index e86dd3e..3e38fd1 100644 --- a/api/auth.html +++ b/api/auth.html @@ -9,9 +9,9 @@ - + - + @@ -20,7 +20,7 @@ -
    Skip to content

    Auth Service API

    The Auth Service is responsible for handling user authentication, including login and token verification.

    Endpoints

    POST /api/v1/auth/login

    Authenticates a user and returns a JWT if the credentials are valid.

    Access: Public

    Rate Limiting: This endpoint is rate-limited to prevent brute-force attacks.

    Request Body

    FieldTypeDescription
    emailstringThe user's email address.
    passwordstringThe user's password.

    Responses

    • 200 OK: Authentication successful.

      json
      {
      +    
      Skip to content

      Auth Service API

      The Auth Service is responsible for handling user authentication, including login and token verification.

      Endpoints

      POST /api/v1/auth/login

      Authenticates a user and returns a JWT if the credentials are valid.

      Access: Public

      Rate Limiting: This endpoint is rate-limited to prevent brute-force attacks.

      Request Body

      FieldTypeDescription
      emailstringThe user's email address.
      passwordstringThe user's password.

      Responses

      • 200 OK: Authentication successful.

        json
        {
         	"accessToken": "your.jwt.token",
         	"user": {
         		"id": "user-id",
        @@ -34,7 +34,7 @@
         }
      • 500 Internal Server Error: An unexpected error occurred.

        json
        {
         	"message": "An internal server error occurred"
         }

      Service Methods

      verifyPassword(password: string, hash: string): Promise<boolean>

      Compares a plain-text password with a hashed password to verify its correctness.

      • password: The plain-text password.
      • hash: The hashed password to compare against.
      • Returns: A promise that resolves to true if the password is valid, otherwise false.

      login(email: string, password: string): Promise<LoginResponse | null>

      Handles the user login process. It finds the user by email, verifies the password, and generates a JWT upon successful authentication.

      • email: The user's email.
      • password: The user's password.
      • Returns: A promise that resolves to a LoginResponse object containing the accessToken and user details, or null if authentication fails.

      verifyToken(token: string): Promise<AuthTokenPayload | null>

      Verifies the authenticity and expiration of a JWT.

      • token: The JWT string to verify.
      • Returns: A promise that resolves to the token's AuthTokenPayload if valid, otherwise null.
      - + \ No newline at end of file diff --git a/api/authentication.html b/api/authentication.html index 01b43d6..e6c4c14 100644 --- a/api/authentication.html +++ b/api/authentication.html @@ -9,9 +9,9 @@ - + - + @@ -20,9 +20,9 @@ -
      Skip to content

      API Authentication

      To access protected API endpoints, you need to include a user-generated API key in the X-API-KEY header of your requests.

      1. Creating an API Key

      You can create, manage, and view your API keys through the application's user interface.

      1. Navigate to Settings > API Keys in the dashboard.
      2. Click the "Generate API Key" button.
      3. Provide a descriptive name for your key and select an expiration period.
      4. The new API key will be displayed. Copy this key immediately and store it in a secure location. You will not be able to see it again.

      2. Making Authenticated Requests

      Once you have your API key, you must include it in the X-API-KEY header of all subsequent requests to protected API endpoints.

      Example:

      http
      GET /api/v1/dashboard/stats
      +    
      Skip to content

      API Authentication

      To access protected API endpoints, you need to include a user-generated API key in the X-API-KEY header of your requests.

      1. Creating an API Key

      You can create, manage, and view your API keys through the application's user interface.

      1. Navigate to Settings > API Keys in the dashboard.
      2. Click the "Generate API Key" button.
      3. Provide a descriptive name for your key and select an expiration period.
      4. The new API key will be displayed. Copy this key immediately and store it in a secure location. You will not be able to see it again.

      2. Making Authenticated Requests

      Once you have your API key, you must include it in the X-API-KEY header of all subsequent requests to protected API endpoints.

      Example:

      http
      GET /api/v1/dashboard/stats
       X-API-KEY: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

      If the API key is missing, expired, or invalid, the API will respond with a 401 Unauthorized status code.

      - + \ No newline at end of file diff --git a/api/dashboard.html b/api/dashboard.html index 3b9a2f1..ae0bc9f 100644 --- a/api/dashboard.html +++ b/api/dashboard.html @@ -9,9 +9,9 @@ - + - + @@ -20,7 +20,7 @@ -
      Skip to content

      Dashboard Service API

      The Dashboard Service provides endpoints for retrieving statistics and data for the main dashboard.

      Endpoints

      All endpoints in this service require authentication.

      GET /api/v1/dashboard/stats

      Retrieves overall statistics, including the total number of archived emails, total storage used, and the number of failed ingestions in the last 7 days.

      Access: Authenticated

      Responses

      • 200 OK: An object containing the dashboard statistics.

        json
        {
        +    
        Skip to content

        Dashboard Service API

        The Dashboard Service provides endpoints for retrieving statistics and data for the main dashboard.

        Endpoints

        All endpoints in this service require authentication.

        GET /api/v1/dashboard/stats

        Retrieves overall statistics, including the total number of archived emails, total storage used, and the number of failed ingestions in the last 7 days.

        Access: Authenticated

        Responses

        • 200 OK: An object containing the dashboard statistics.

          json
          {
           	"totalEmailsArchived": 12345,
           	"totalStorageUsed": 54321098,
           	"failedIngestionsLast7Days": 3
          @@ -58,7 +58,7 @@
           		}
           	]
           }
        - + \ No newline at end of file diff --git a/api/index.html b/api/index.html index 0b260ff..4a8a0fa 100644 --- a/api/index.html +++ b/api/index.html @@ -9,9 +9,9 @@ - + - + @@ -20,8 +20,8 @@ -
        Skip to content

        API Overview

        Welcome to the Open Archiver API documentation. This section provides detailed information about the available API endpoints.

        All API endpoints are prefixed with /api/v1.

        Authentication

        Before making requests to protected endpoints, you must authenticate with the API. See the Authentication Guide for details on how to obtain and use API tokens.

        API Services

        - +
        Skip to content

        API Overview

        Welcome to the Open Archiver API documentation. This section provides detailed information about the available API endpoints.

        All API endpoints are prefixed with /api/v1.

        Authentication

        Before making requests to protected endpoints, you must authenticate with the API. See the Authentication Guide for details on how to obtain and use API tokens.

        API Services

        + \ No newline at end of file diff --git a/api/ingestion.html b/api/ingestion.html index 3b7458c..f8ec91a 100644 --- a/api/ingestion.html +++ b/api/ingestion.html @@ -9,9 +9,9 @@ - + - + @@ -20,7 +20,7 @@ -
        Skip to content

        Ingestion Service API

        The Ingestion Service manages ingestion sources, which are configurations for connecting to email providers and importing emails.

        Endpoints

        All endpoints in this service require authentication.

        POST /api/v1/ingestion-sources

        Creates a new ingestion source.

        Access: Authenticated

        Request Body

        The request body should be a CreateIngestionSourceDto object.

        typescript
        interface CreateIngestionSourceDto {
        +    
        Skip to content

        Ingestion Service API

        The Ingestion Service manages ingestion sources, which are configurations for connecting to email providers and importing emails.

        Endpoints

        All endpoints in this service require authentication.

        POST /api/v1/ingestion-sources

        Creates a new ingestion source.

        Access: Authenticated

        Request Body

        The request body should be a CreateIngestionSourceDto object.

        typescript
        interface CreateIngestionSourceDto {
         	name: string;
         	provider: 'google' | 'microsoft' | 'generic_imap';
         	providerConfig: IngestionCredentials;
        @@ -30,7 +30,7 @@
         	providerConfig?: IngestionCredentials;
         	status?: 'pending_auth' | 'auth_success' | 'importing' | 'active' | 'paused' | 'error';
         }

        Responses

        • 200 OK: The updated ingestion source object.
        • 404 Not Found: Ingestion source not found.
        • 500 Internal Server Error: An unexpected error occurred.

        DELETE /api/v1/ingestion-sources/:id

        Deletes an ingestion source and all associated data.

        Access: Authenticated

        URL Parameters

        ParameterTypeDescription
        idstringThe ID of the ingestion source.

        Responses

        • 204 No Content: The ingestion source was deleted successfully.
        • 404 Not Found: Ingestion source not found.
        • 500 Internal Server Error: An unexpected error occurred.

        POST /api/v1/ingestion-sources/:id/import

        Triggers the initial import process for an ingestion source.

        Access: Authenticated

        URL Parameters

        ParameterTypeDescription
        idstringThe ID of the ingestion source.

        Responses

        • 202 Accepted: The initial import was triggered successfully.
        • 404 Not Found: Ingestion source not found.
        • 500 Internal Server Error: An unexpected error occurred.

        POST /api/v1/ingestion-sources/:id/pause

        Pauses an active ingestion source.

        Access: Authenticated

        URL Parameters

        ParameterTypeDescription
        idstringThe ID of the ingestion source.

        Responses

        • 200 OK: The updated ingestion source object with a paused status.
        • 404 Not Found: Ingestion source not found.
        • 500 Internal Server Error: An unexpected error occurred.

        POST /api/v1/ingestion-sources/:id/sync

        Triggers a forced synchronization for an ingestion source.

        Access: Authenticated

        URL Parameters

        ParameterTypeDescription
        idstringThe ID of the ingestion source.

        Responses

        • 202 Accepted: The force sync was triggered successfully.
        • 404 Not Found: Ingestion source not found.
        • 500 Internal Server Error: An unexpected error occurred.
        - + \ No newline at end of file diff --git a/api/rate-limiting.html b/api/rate-limiting.html index 9fb71c3..0496e69 100644 --- a/api/rate-limiting.html +++ b/api/rate-limiting.html @@ -9,9 +9,9 @@ - + - + @@ -20,11 +20,11 @@ -
        Skip to content

        Rate Limiting

        The API implements rate limiting as a security measure to protect your instance from denial-of-service (DoS) and brute-force attacks. This is a crucial feature for maintaining the security and stability of the application.

        How It Works

        The rate limiter restricts the number of requests an IP address can make within a specific time frame. These limits are configurable via environment variables to suit your security needs.

        By default, the limits are:

        • 100 requests per 1 minute per IP address.

        If this limit is exceeded, the API will respond with an HTTP 429 Too Many Requests status code.

        Response Body

        When an IP address is rate-limited, the API will return a JSON response with the following format:

        json
        {
        +    
        Skip to content

        Rate Limiting

        The API implements rate limiting as a security measure to protect your instance from denial-of-service (DoS) and brute-force attacks. This is a crucial feature for maintaining the security and stability of the application.

        How It Works

        The rate limiter restricts the number of requests an IP address can make within a specific time frame. These limits are configurable via environment variables to suit your security needs.

        By default, the limits are:

        • 100 requests per 1 minute per IP address.

        If this limit is exceeded, the API will respond with an HTTP 429 Too Many Requests status code.

        Response Body

        When an IP address is rate-limited, the API will return a JSON response with the following format:

        json
        {
         	"status": 429,
         	"message": "Too many requests from this IP, please try again after 15 minutes"
         }

        Configuration

        You can customize the rate-limiting settings by setting the following environment variables in your .env file:

        • RATE_LIMIT_WINDOW_MS: The time window in milliseconds. Defaults to 60000 (1 minute).
        • RATE_LIMIT_MAX_REQUESTS: The maximum number of requests allowed per IP address within the time window. Defaults to 100.

        Handling Rate Limits

        If you are developing a client that interacts with the API, you should handle rate limiting gracefully:

        1. Check the Status Code: Monitor for a 429 HTTP status code in responses.
        2. Implement a Retry Mechanism: When you receive a 429 response, it is best practice to wait before retrying the request. Implementing an exponential backoff strategy is recommended.
        3. Check Headers: The response will include the following standard headers to help you manage your request rate:
          • RateLimit-Limit: The maximum number of requests allowed in the current window.
          • RateLimit-Remaining: The number of requests you have left in the current window.
          • RateLimit-Reset: The time when the rate limit window will reset, in UTC epoch seconds.

        Excluded Endpoints

        Certain essential endpoints are excluded from rate limiting to ensure the application's UI remains responsive. These are:

        • /auth/status
        • /settings/system

        These endpoints can be called as needed without affecting your rate limit count.

        - + \ No newline at end of file diff --git a/api/search.html b/api/search.html index 11862d6..8fdf004 100644 --- a/api/search.html +++ b/api/search.html @@ -9,9 +9,9 @@ - + - + @@ -20,7 +20,7 @@ -
        Skip to content