API Access
==========

1. API Token Generation
-----------------------

To use the MailTrigger HTTP API, you must first generate an API Token. Follow these steps:

1. Log in to MailTrigger and click the user avatar at the top right → **User Settings**.
2. From the sidebar, click **API Tokens**.
3. Click **Generate New Token**:
   - **Name** *(optional)*: Provide a label to identify this token.
   - Click **Create**.
4. The system will display the newly created token **only once**. Be sure to **copy and store it securely**.
5. If lost, go back to the **API Tokens** list, click **Revoke** for the lost token and generate a new one.

2. Authentication (No Username/Password Support)
------------------------------------------------

All MailTrigger API requests require authentication via API Token. **Username and password are not supported**.

- **HTTP Headers**
  Include the following headers in every API request:

  .. code-block:: none

     Authorization: Bearer <YOUR_API_TOKEN>
     Content-Type: application/json

- **Example**

  .. code-block:: bash

     curl -X GET https://app.mailtrigger.app/v1/domains \
          -H "Authorization: Bearer abcdef1234567890" \
          -H "Content-Type: application/json"

- **Error Responses**
  - Missing or invalid tokens will result in HTTP ``401 Unauthorized``.
  - Expired or revoked tokens may return ``401`` or ``403 Forbidden``.

.. note::
   - API Tokens grant **full access** to your account. Never expose them in public code or frontend environments.
   - For automated or scheduled access, store tokens securely in environment variables or a secrets manager.


MailTrigger API Reference
=========================

Available APIs
--------------

1. **GET /api/v1/mailbox/{mailboxId}/archives/**

   Retrieve all archived emails (sent and received) of a specific mailbox.

   **Filter Parameters:**

   - ``sender``: Filter by sender (case-insensitive, partial match supported)
   - ``receivers``: Filter by receiver(s) (case-insensitive, partial match supported)
   - ``subject``: Filter by subject (case-insensitive, partial match supported)
   - ``body``: Filter by email body (case-insensitive, partial match supported)
   - ``hasAttachments``: Filter by presence of attachments (``True`` / ``False``)
   - ``date_after`` / ``date_before``: Filter by email sending date range
   - ``date_exact``: Filter by exact sending date
   - ``createdTime_after`` / ``createdTime_before``: Filter by archive creation date
   - ``search``: Global search across sender, receivers, subject, body, attachments, and content

   **Usage Examples:**

   - Filter emails with subject containing "Meeting" and with attachments::

       GET /api/v1/mailbox/123/archives/?subject=Meeting&hasAttachments=True

   - Filter emails sent between August 1–20, 2024::

       GET /api/v1/mailbox/123/archives/?date_after=2024-08-01&date_before=2024-08-20

   - Global search for "project" keyword::

       GET /api/v1/mailbox/123/archives/?search=project

2. **GET /api/v1/mailbox/{mailboxId}/data/**

   Retrieve custom receiver data configured for a mailbox.

   **Filter Parameters:**

   - ``file``: Filter by file ID
   - ``emails``: Filter by email(s), comma-separated
   - ``note``: Filter by note content (case-insensitive, partial match supported)
   - ``data``: Search JSON key-value pairs (case-insensitive, partial match supported)
   - ``fields``: Return only selected JSON fields (comma-separated)
   - ``created_after`` / ``created_before``: Filter by data creation date range
   - ``created_exact``: Filter by exact creation date
   - ``search``: Global search in email, note, and all JSON fields

   **Usage Examples:**

   - Filter data with note containing "urgent"::

       GET /api/v1/mailbox/123/data/?note=urgent

   - Filter data created on August 15, 2024::

       GET /api/v1/mailbox/123/data/?created_exact=2024-08-15

   - Search for ``status: active`` in JSON data::

       GET /api/v1/mailbox/123/data/?data=status:active

   - Return only ``email`` and ``name`` fields::

       GET /api/v1/mailbox/123/data/?fields=email,name

3. **POST /api/v1/task-configs/{taskId}/db/execute/**

   Execute raw SQL queries on the background task's dedicated SQLite3 database.

4. **POST /api/v1/task-configs/{taskId}/action/execute/**

   Manually execute the action associated with a background task.

Additional Notes
----------------

- Authentication is required for all API usage.
- Access is restricted to mailboxes owned by the authenticated user.

When Would I Need to Use These APIs?
------------------------------------

See the "Scheduled Actions Setup" and this section for use cases requiring advanced logic for background tasks.

**Example: Bob's Use Case**

Bob wants to monitor server resource status every hour using a background task. He implements the following logic:

1. **Query archive:**
   Use ``GET /api/v1/mailbox/{mailboxId}/archives/`` to fetch emails related to "server resource changes".

2. **Track new emails:**
   Use ``POST /api/v1/task-configs/{taskId}/db/execute/`` to log each run into a ``records`` table in the SQLite3 database.
   Then compare current emails with past records to detect new incoming ones.

3. **Trigger alert if new email detected:**
   If new emails exist, extract the latest message and use
   ``POST /api/v1/task-configs/{taskId}/action/execute/`` to run the task's action
   (e.g., sending to Telegram or WhatsApp).

This setup ensures Bob only receives **one consolidated alert per hour**, avoiding redundant messages and helping him focus on meaningful changes.