API Access

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:

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

  • Example

    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.

Contents