Table of Contents
A CLI tool and a library that takes an URL in various ways, retrieves the HTML page title, and compose, enqueue and send an email with a link to that URL and the title.
To use an email address (or a mailing list) as a "bookmarking system" or simply to scratch the itch of an obsessive archivist.
Disclaimer: this project can hardly be useful to anyone else other than its author. For this reason it should honestly be considered a toy project.
The REFERENCES document gives proper credit to the libraries used and the references to the technical documentation and implementation.
Check the TODO file for an overview of the current and future
development / ideas / features.
msmtp "msmtp - An SMTP client" (marlam.de/msmtp)
installed and configured.
msmtp version 1.8.3
Platform: x86_64-pc-linux-gnu
TLS/SSL library: GnuTLS
Authentication library: GNU SASL
Supported authentication methods:
plain scram-sha-1 external gssapi cram-md5 digest-md5 login ntlm
IDN support: enabled
NLS: enabled, LOCALEDIR is /usr/share/locale
Keyring support: none
System configuration file name: /etc/msmtprc
msmtpq and msmtp-queue both available in the $PATH.
```
```
$HOME/.msmtp.queue/ to save the enqueued
emails as a pair of the generated files:
$ file $HOME/.msmtp.queue/*
/home/user/.msmtp.queue/1595792128.mail: news or mail, ASCII text
/home/user/.msmtp.queue/1595792128.msmtp: ASCII text
From the CLI --help:
``` enqueue-email 0.1.0 EnqueueEmail
Pass an URL using one of the options available (clipboard, full URL or a combination of the URL parts, and enqueue an email, ready to be spooled by msmtp-queue.
SETUP:
The following environment variables are required:
ENQUEUEMAILFROM, ENQUEUEMAILTO, ENQUEUEMAILCC [optional], ENQUEUEMAILFCC [in the format "provider/folder"]
USAGE: enqueue-email [FLAGS] [OPTIONS]
FLAGS: -c, --clipboard Use the URL currently on the top of the Clipboard. This option disables all the other defined options
--help
Prints help information
-r, --run
Run msmt-queue and flush all mail currently in queue. This wraps the command 'msmtp-queue -r'
-V, --version
Prints version information
OPTIONS:
--cafile
-f, --fragment <fragment>
An optional fragment component preceded by a hash (#)
-h, --host <host>
The host to connect to
-t, --path <path>
The path component in the URI. This follows the definitions of RFC2396 and RFC3986
(https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) [default: /]
-p, --port <port>
The port to connect to [default: 443]
-q, --query <query>
An optional query component preceded by a question mark (?), containing a query string of non-hierarchical
data
-s, --scheme <scheme>
The scheme protocol of the URI [default: https]
-u, --url <url>
The URL to bookmark and enqueue. This excludes scheme, host, port and domain. This option has the priority
over the Clipboard
```
Let's show some example, starting with an empty SMTP queue:
``` $ msmtp-queue
no mail in queue ```
All the examples are run with the environment variable RUST_LOG set to
the INFO level to show the bare minimum output to appreciate the result.
Let's print the content of the clipboard and enqueue an email with the same content and the title of the web page associated:
``` $ echo "$(xclip -o --selection clipboard)" https://en.wikipedia.org/wiki/SimpleMailTransfer_Protocol
$ RUSTLOG=INFO enqueue-email --clipboard [2020-07-27T20:56:55Z INFO enqueueemail] page title: Simple Mail Transfer Protocol - Wikipedia ```
There are other two options that can be used to save and enqueue a link:
explicitly with a complete and well-formed URL (--url) or with a combination
of its components (--host and --path in the example).
``` $ RUSTLOG=INFO enqueue-email --url https://wikipedia.org/wiki/Unix [2020-07-27T20:57:58Z INFO enqueueemail] page title: Unix - Wikipedia
$ RUSTLOG=INFO enqueue-email --host en.wikipedia.org --path /wiki/Freeandopen-sourcesoftware [2020-07-27T20:59:49Z INFO enqueue_email] page title: Free and open-source software - Wikipedia ```
At this point the expectated result is to have 3 message in the local queue:
``` $ msmtp-queue
mail num=[ 1 ] id=[ 1595883415 ] From: user user@provider.net To: list mailinglist@provider.net Subject: [link] Simple Mail Transfer Protocol - Wikipedia
mail num=[ 2 ] id=[ 1595883478 ] From: user user@provider.net To: list mailinglist@provider.net Subject: [link] Unix - Wikipedia
mail num=[ 3 ] id=[ 1595883589 ] From: user user@provider.net To: list mailinglist@provider.net Subject: [link] Free and open-source software - Wikipedia ```
When we are satified we can use the msmtp-queue tool directly to send a
specific email (-R) or send all (-r):
``` $ msmtp-queue -R
mail num=[ 1 ] id=[ 1595883415 ] From: user user@provider.net To: list mailinglist@provider.net Subject: [link] Simple Mail Transfer Protocol - Wikipedia
mail num=[ 2 ] id=[ 1595883478 ] From: user user@provider.net To: list mailinglist@provider.net Subject: [link] Unix - Wikipedia
mail num=[ 3 ] id=[ 1595883589 ] From: user user@provider.net To: list mailinglist@provider.net Subject: [link] Free and open-source software - Wikipedia
enter mail number or id to send
(
send : mail num=[ 1 ] id=[ 1595883415 ]
ok [Y/n] ..: mail [ 1 ] [ 1595883415 ] from queue ; send was successful ; purged from queue
mail num=[ 1 ] id=[ 1595883478 ] From: user user@provider.net To: list mailinglist@provider.net Subject: [link] Unix - Wikipedia
mail num=[ 2 ] id=[ 1595883589 ] From: user user@provider.net To: list mailinglist@provider.net Subject: [link] Free and open-source software - Wikipedia
enter mail number or id to send
(
$ msmtp-queue -r
mail [ 1 ] [ 1595883478 ] from queue ; send was successful ; purged from queue
mail [ 2 ] [ 1595883589 ] from queue ; send was successful ; purged from queue
If you want to trigger the delivery immediately and directly from
enqueue-email you can add the option --run to trigger msmtp-queue:
-r run (flush) mail queue - all mail in queue
This last example shows the --run option. It's important to note that using
--run will trigger the flush of the mail queue with all the messages
waiting there, not only the last in queue.
$ RUST_LOG=INFO enqueue-email --url https://en.wikipedia.org/wiki/Email --run
[2020-07-27T21:02:52Z INFO enqueue_email] page title: Email - Wikipedia
mail [ 1 ] [ 1595883772 ] from queue ; send was successful ; purged from queue
<title>...</title>) is present; dynamically generated pages might
be reported without a title.All the configurations are expected to be available from the environment variables. These options control the headers of the message format as defined in the RFC-3864:
ENQUEUE_MAIL_FROM: From: The email address, and, optionally, the
name of the author(s).ENQUEUE_MAIL_TO: The email address(es), and optionally name(s) of
the message's recipient(s). Indicates primary recipients (multiple
allowed), for secondary recipients see Cc: below.ENQUEUE_MAIL_CC: Carbon copy; Many email clients mark email in
one's inbox differently depending on whether they are in the To: or
Cc: list.ENQUEUE_MAIL_FCC: The name of a file, to which a copy of the sent
message should be appended (from
Emacs mail headers).ENQUEUE_MAIL_ACCOUNT: in the format "provider/folder".Optionally RUST_LOG can be used to tune the messages that are logged
in STDOUT.
The project is divided in a library (enqueuemail) and the
binary (enqueue-email).
Cargo should be used to conveniently build and install; here the references to cargo-build and cargo-install.
$ rustup toolchain install --profile default --allow-downgrade --component cargo,clippy,rustfmt,rust-docs,rust-src nightly
$ cargo build
$ cargo fmt
$ cargo clippy
...
live-tests: use this features to enable a subset of the test suite that
requires Internet connection (for the URL host resolution) and to run the
complete calculation of the test coverage. It has no other impact outside
of the tests module.Few well known / best practices that were and should always be taken in account for the development of this project are presented in the CONTRIBUTING document.
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.