ASIMOV IMAP Module

ASIMOV module for IMAP email import.

✨ Features

• Fetches email messages from IMAP servers and outputs them as JSON-LD.
• Constructs a semantic knowledge graph based on the KNOW ontology.
• Supports Gmail, Outlook, Yahoo, iCloud, Proton Mail, GMX, Fastmail, and just about any other email provider.
• Uses server-side sorting of email messages with servers that support it.
• Implements optimal client-side sorting when server-side sorting isn't available.
• Loads environment variables from .env (aka dotenv) files.
• Distributed as a standalone static binary with zero runtime dependencies.

🛠️ Prerequisites

• Rust 1.85+ (2024 edition) if building from source code

⬇️ Installation

Installation with the ASIMOV CLI

asimov module install imap -v

Installation from Source Code

cargo install asimov-imap-module

👉 Examples

Email Import from IETF Mailing Lists

Listing email messages in a mailbox

asimov list imaps://imap.ietf.org/Shared%20Folders/json-canon

Exporting email messages in a mailbox as JSON

asimov list imaps://imap.ietf.org/Shared%20Folders/json-canon -o json

Email Import from Gmail

Cataloging email messages in the inbox

asimov-imap-cataloger imaps://imap.gmail.com/INBOX -n5

Fetching a specific email message

asimov-imap-fetcher imaps://imap.gmail.com/INBOX#mid

⚙ Configuration

Authentication Credentials

Typically, authentication credentials are required to access an IMAP mailbox. These can be supplied in three different ways, listed below in order of precedence:

1. Configuring credentials in the imaps: URL

Authentication credentials can be supplied inline in the URL, as follows:

asimov-imap-cataloger imaps://myuser:mypassword@host:port/mailbox

2. Configuring credentials in environment variables

Authentication credentials can also be supplied via environment variables, as follows:

export ASIMOV_IMAP_USER=myuser
export ASIMOV_IMAP_PASSWORD=mypassword

asimov-imap-cataloger imaps://host:port/mailbox

3. Configuring credentials in the ~/.netrc file

Authentication credentials can also be supplied via the ~/.netrc (aka $HOME/.netrc) file, as follows:

machine host
login myuser
password mypassword

asimov-imap-cataloger imaps://host:port/mailbox

Gmail Configuration

To connect to your Gmail (aka Google Mail) account, follow these steps:

1. Enable 2-Step Verification in your account's Security configuration.
2. Create an app password in your account's App passwords configuration. (You can enter any app name, such as "ASIMOV".)

Then, construct your IMAP credentials and URL as follows:

• Use the imaps: URL scheme for a secure connection.
• Use your full email address--including @gmail.com, @googlemail.com, or your own Google Workspace domain name--as the IMAP username.
• Use the app password your created as the IMAP password.
• Use imap.gmail.com for the IMAP hostname.
• Use 993 for the IMAP port, or just omit the port altogether.

The authentication credentials can be configured using any of the aforementioned methods.

For example, configure the ~/.netrc (aka $HOME/.netrc) file to store your Gmail credentials as follows:

machine imap.gmail.com
login myuser@gmail.com
password myapppassword

Test your configuration by attempting to list the first five email messages in your inbox:

asimov-imap-cataloger imaps://imap.gmail.com/INBOX -n5

📚 Reference

Cloud Email Providers

Installed Binaries

• asimov-imap-cataloger: lists email messages in an IMAP mailbox
• asimov-imap-fetcher: fetches email messages from an IMAP mailbox

asimov-imap-cataloger

asimov-imap-cataloger

Usage: asimov-imap-cataloger [OPTIONS] <IMAP-MAILBOX-URL>

Arguments:
  <IMAP-MAILBOX-URL>  An `imaps://user@host:port/mailbox` (or `imap://...`) URL to the IMAP mailbox to catalog

Options:
  -d, --debug                Enable debugging output
      --license              Show license information
  -v, --verbose...           Enable verbose output (may be repeated for more verbosity)
  -V, --version              Print version information
  -b, --order-by <PROPERTY>  Order messages by a property [default: none] [possible values: none, timestamp, date, from, to, cc, size]
  -n, --limit <COUNT>        Limit the number of messages to catalog
  -o, --output <FORMAT>      Set the output format [default: cli] [possible values: cli, json, jsonld, jsonl]
  -h, --help                 Print help (see more with '--help')

asimov-imap-fetcher

asimov-imap-fetcher

Usage: asimov-imap-fetcher [OPTIONS] <IMAP-MESSAGE-URL>

Arguments:
  <IMAP-MESSAGE-URL>  An `imaps://user@host:port/mailbox#mid` (or `imap://...`) URL to the message to fetch

Options:
  -d, --debug            Enable debugging output
      --license          Show license information
  -v, --verbose...       Enable verbose output (may be repeated for more verbosity)
  -V, --version          Print version information
  -o, --output <FORMAT>  The output format
  -h, --help             Print help

👨‍💻 Development

git clone https://github.com/asimov-modules/asimov-imap-module.git