Unread Email Retrieval Workflow

Description

Overview

This unread email retrieval automation workflow enables users to extract the three most recent unread messages from a Fastmail inbox using the JMAP API. This orchestration pipeline is designed for individuals or teams requiring structured access to unread email metadata such as sender, subject, and timestamp without manual mailbox inspection.

The workflow initiates via a manual trigger node and leverages HTTP requests authenticated with header credentials to interact with Fastmail’s JMAP API endpoints.

Key Benefits

Efficiently fetches the latest three unread emails from a Fastmail inbox using an automation workflow.
Utilizes JMAP API methods to retrieve mailbox and message details in a structured, no-code integration.
Manually triggered for precise control over execution timing and data retrieval.
Extracts key email metadata including sender information, subject lines, and received timestamps.

Product Overview

This unread email retrieval workflow begins with a manual trigger node, allowing users to initiate the process on demand. It first performs an authenticated HTTP POST request to the Fastmail JMAP session endpoint to obtain session information, including the primary mail account ID. Subsequently, the workflow sends a second POST request to retrieve all mailboxes associated with the account, filtering specifically for the inbox mailbox by role.

After identifying the inbox mailbox ID, the workflow formats these critical identifiers and issues a final API call to query unread emails within the inbox. The query filters messages that lack the “seen” keyword, sorts them by the most recent received date, and limits the output to three messages. This dual-method call also fetches detailed email properties such as ID, received timestamp, sender, subject, and keywords.

The workflow operates synchronously within n8n, processing requests and formatting responses sequentially. Authentication is handled via HTTP header credentials with a bearer token, ensuring secure API access. Error handling relies on n8n’s default retry and failure management mechanisms.

Features and Outcomes

Core Automation

This no-code integration pipeline begins with a manual trigger and uses HTTP request nodes to extract mailbox and unread message data. Decision logic includes filtering unread emails by the absence of the “seen” keyword and limiting results to a maximum of three messages.

Single-pass evaluation of API responses to extract account and mailbox IDs.
Deterministic filtering and sorting of unread emails by received date.
Sequential node execution ensures data dependencies are respected throughout.

Integrations and Intake

The workflow integrates directly with Fastmail’s JMAP API via HTTP POST requests authenticated using HTTP header credentials containing a bearer token. It consumes session and mailbox data, and queries email messages with structured JSON payloads conforming to JMAP specifications.

Authenticates with Fastmail using HTTP Header Authentication (Bearer token).
Fetches session details from the JMAP session endpoint for account context.
Retrieves mailbox listings and email query results through JMAP-compliant API calls.

Outputs and Consumption

The workflow outputs JSON objects containing the three most recent unread emails, including properties such as message ID, sender, subject, received timestamp, and keywords. This data is returned synchronously after workflow execution for downstream use.

JSON-formatted response with unread email metadata.
Includes key fields: id, receivedAt, from, subject, and keywords.
Supports integration with additional workflows or external systems for further processing.

Workflow — End-to-End Execution

Step 1: Trigger

The workflow starts with a manual trigger node that requires a user to click “Execute Workflow” to initiate the process. This ensures controlled, user-driven execution without automatic scheduling or event-based triggers.

Step 2: Processing

The workflow processes begin by sending an authenticated HTTP POST request to the Fastmail JMAP session endpoint. It parses the JSON response to extract the primary mail account ID. Subsequently, it requests the list of mailboxes for this account and identifies the inbox mailbox by its “role” attribute. Basic presence checks ensure these required IDs are available before proceeding.

Step 3: Analysis

The workflow applies deterministic filtering on the mailbox ID to query unread emails. It uses JMAP filtering criteria to exclude messages marked with the “seen” keyword while sorting messages by their received date in descending order. The query limits the number of emails retrieved to three and fetches specified properties for each.

Step 4: Delivery

The response from the email query is formatted into JSON containing the relevant email details. This is returned synchronously as the final output of the workflow and can be consumed by other nodes or external systems integrated with n8n.

Use Cases

Scenario 1

Users requiring quick access to unread emails can trigger this workflow to retrieve the latest three unread messages from their Fastmail inbox. This solution enables structured email monitoring without manual inbox checks, providing a consistent snapshot of new communications.

Scenario 2

Integrators can include this automation workflow within larger pipelines to trigger notifications or further processing based on unread email arrival. The output can feed into alerting systems or data aggregation tools, enabling event-driven analysis of inbound messages.

Scenario 3

Developers building email-based workflows can use this orchestration pipeline to extract and parse unread email metadata for use in reporting or automated responses. The workflow ensures consistent email fetching through the JMAP protocol with authenticated API access.

How to use

To implement this workflow, import it into your n8n environment and configure the HTTP Header Authentication credentials with your Fastmail API token. Execute the workflow manually via the “Execute Workflow” button to initiate the process. The workflow will retrieve and output the three most recent unread emails from your inbox.

Ensure your Fastmail API token is valid and has appropriate permissions for JMAP access. Once configured, the workflow can be run on demand and integrated with other automation pipelines for extended functionality.

Comparison — Manual Process vs. Automation Workflow

Attribute	Manual/Alternative	This Workflow
Steps required	Multiple manual steps: login, navigate inbox, filter unread emails, review details.	Single manual trigger; automated API calls retrieve and parse relevant email data.
Consistency	Subject to human error and interface changes affecting mailbox navigation.	Deterministic API-driven retrieval with consistent filtering and sorting logic.
Scalability	Limited by manual effort; impractical for frequent or bulk email checks.	Scales to repeated executions with minimal effort; suitable for integration into broader workflows.
Maintenance	Requires manual updates if mailbox UI or email clients change.	Requires credential updates and occasional API adjustments; mostly code-free maintenance.

Technical Specifications

Environment	n8n automation platform
Tools / APIs	Fastmail JMAP API via HTTP requests
Execution Model	Manual trigger with synchronous request-response flow
Input Formats	None (manual trigger without external input)
Output Formats	JSON containing email metadata fields
Data Handling	Transient processing; no data persistence within workflow
Known Constraints	Relies on external Fastmail API availability and valid authentication
Credentials	HTTP Header Authentication using Bearer token

Implementation Requirements

Valid Fastmail API token configured as HTTP Header Authentication in n8n.
Network access allowing outbound HTTPS POST requests to Fastmail JMAP endpoints.
Manual workflow execution by user interaction within n8n interface.

Configuration & Validation

Configure HTTP Header Authentication credentials with a valid Fastmail API bearer token.
Run the workflow manually and verify the response contains three unread emails or fewer if unavailable.
Confirm extracted fields (id, from, subject, receivedAt) match expected email metadata in your Fastmail inbox.

Data Provenance

Manual Trigger node initiates the workflow execution.
HTTP Request nodes ‘Fetch API details’, ‘Get mailboxes’, and ‘Get unread messages’ interact with Fastmail JMAP API.
Set node ‘Format results’ extracts and formats account and mailbox IDs for query use.

FAQ

How is the unread email retrieval automation workflow triggered?

The workflow is triggered manually via the “Execute Workflow” button within n8n, allowing controlled, user-initiated runs without automatic scheduling.

Which tools or models does the orchestration pipeline use?

The pipeline integrates with Fastmail’s JMAP API using HTTP request nodes authenticated by HTTP header credentials containing a bearer token. No external AI models are involved.

What does the response look like for client consumption?

The workflow outputs a JSON array of up to three unread email objects, each containing fields such as id, receivedAt, from, subject, and keywords.

Is any data persisted by the workflow?

No data is persisted within the workflow. All information is processed transiently and returned synchronously on each execution.

How are errors handled in this integration flow?

Error handling relies on n8n’s default mechanisms including retries and failure notifications; no custom error management is implemented in this workflow.

Conclusion

This unread email retrieval automation workflow provides a structured method to extract recent unread messages from a Fastmail inbox using the JMAP API. It delivers dependable, deterministic results with essential email metadata on demand through a manual trigger. The workflow depends on valid Fastmail API authentication and the availability of Fastmail’s JMAP endpoints. Its design eliminates manual email filtering steps, enabling integration into broader automation pipelines while requiring minimal ongoing maintenance.