API Usage Guide

8. API Usage Guide#

The MailTrigger system provides the following APIs:

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

    Description: All emails received or sent by a mailbox are stored in the archive. You can use this API to retrieve the archived emails of a specific mailbox.

    Filter Parameters:

    • sender: Filter by sender, supports case-insensitive partial match.

    • receivers: Filter by receivers, supports case-insensitive partial match.

    • subject: Filter by subject, supports case-insensitive partial match.

    • body: Filter by email body, supports case-insensitive partial match.

    • hasAttachments: Filter emails with attachments, pass True or False.

    • date_after / date_before: Filter by email sending date, pass a date range.

    • date_exact: Filter by exact email sending date.

    • createdTime_after / createdTime_before: Filter by archive creation date, pass a date range.

    • search: Global search, allows searching across sender, receivers, subject, email body, attachments, and message content.

    Usage Examples:

    • Filter emails with a subject containing “Meeting” and with attachments:

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

    • Filter emails sent between August 1, 2024, and August 20, 2024:

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

    • Global search for emails containing the keyword “project”:

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

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

    Description: Retrieve custom receiver data configured for the mailbox.

    Filter Parameters:

    • file: Filter by a specific file, pass the file ID.

    • emails: Filter by email, supports multiple emails separated by commas.

    • note: Filter by note content, supports case-insensitive partial match.

    • data: Search within JSON data for specific key-value pairs, supports case-insensitive partial match.

    • fields: Return only the specified JSON fields and their values, supports multiple fields separated by commas.

    • created_after / created_before: Filter by data creation date, pass a date range.

    • created_exact: Filter by exact data creation date.

    • search: Global search, allows searching across email, note, and all JSON fields.

    Usage Examples:

    • Filter data with notes containing “urgent”:

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

    • Filter data created on a specific date:

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

    • Filter JSON data containing “status: active”:

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

    • Return only the specified JSON fields “email” and “name”:

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

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

    Description: Each background task (if you have configured a background task) has its own dedicated SQLite3 database. This API allows you to execute any SQL commands on the SQLite3 database.

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

    Description: Each background task (if you have configured a background task) has an associated action. This action is not automatically executed when the background task runs. You need to use this API to manually execute the action (e.g., sending a message to WhatsApp).

8.1. Additional Notes#

Authentication is required for each API usage (restricted to operations within your owned mailboxes).

8.2. When Would I Need to Use These APIs?#

Refer to the “How to set up scheduled actions?” and “When would I need to use these APIs?” sections to understand the need for writing custom background task execution logic, which is highly customizable and a powerful feature of MailTrigger. For example, Jack from the “When would I need to use these APIs?” section needs to execute the following three steps every hour when running background tasks:

  1. Retrieve all archived emails related to “server resource changes” for the current mailbox using GET /api/mailbox/{mailboxId}/archives/ API.

  2. Check if there are new archived emails related to “server resource changes” received since the last execution of the background task. Jack uses the POST /api/task-configs/{taskId}/db/execute/ API to create a SQLite3 database table named “records” and records the current mailbox archive records for each execution of the background task. Jack compares the archived emails obtained from GET /api/mailbox/{mailboxId}/archives/ with the archived email records in the SQLite3 records table to determine if new emails have been generated.

  3. If new emails are found, retrieve the content of the latest archived email and execute the action configured for that background task using POST /api/task-configs/{taskId}/action/execute/ API.

Following these steps ensures that Jack only receives one email per hour despite his server resource management system sending out many duplicate emails. This enhances Jack’s efficiency in reading emails and helps him avoid missing important information.

Contents