1 unstable release

0.1.0	Aug 14, 2020

#1659 in Parser implementations

Apache-2.0 OR MIT

87KB
1.5K SLoC

Enqueue Email (ɪnˈkjuː)

Table of Contents

Enqueue Email (ɪnˈkjuː)

Description

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.

Background

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.

Features

Takes the input from a command line option or reads the current clipboard.
Configurable via environment variables.
Can enque emails or trigger the spooling for each invocation.

The REFERENCES document gives proper credit to the libraries used and the references to the technical documentation and implementation.

ToDo List And Planning

Check the TODO file for an overview of the current and future development / ideas / features.

Prerequisites

A Unix-like operating system with a running X Window System Server to read the system clipboard.
Network connectivity open to HTTPS, DNS and SMTP traffic, to resolve the URL, to retrieve the page content and to send the email(s).

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.

##  msmtpq : queue funtions to both use & manage the msmtp queue,
##             as it was defined by Martin Lambers
##  Copyright (C) 2008 - 2015 Chris Gianniotis

## msmtp-queue : wrapper script for msmtpq
##               to expose the management functions
##               for the msmtp queue
##  Copyright (C) 2011 Chris Gianniotis

A writable access to a directory $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

To build the project: Rust and Cargo "2018" edition.

Usage

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:

ENQUEUE_MAIL_FROM, ENQUEUE_MAIL_TO, ENQUEUE_MAIL_CC [optional], ENQUEUE_MAIL_FCC [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 <cafile>
            A file with a certificate authority chain, allows to connect to certificate authories not included in the
            default set
    -d, --domain <domain>
            The domain to connect to. This may be different from the host!

    -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

Examples

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/Simple_Mail_Transfer_Protocol

$ RUST_LOG=INFO enqueue-email --clipboard
[2020-07-27T20:56:55Z INFO  enqueue_email] 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).

$ RUST_LOG=INFO enqueue-email --url https://wikipedia.org/wiki/Unix
[2020-07-27T20:57:58Z INFO  enqueue_email] page title: Unix - Wikipedia

$ RUST_LOG=INFO enqueue-email --host en.wikipedia.org --path /wiki/Free_and_open-source_software
[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
    ( <cr> alone to exit ) ..: 1

  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
    ( <cr> alone to exit ) ..:

$ 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

Limitations

Only HTTPS is supported.
The title extraction works only if the HTML title tag (<title>...</title>) is present; dynamically generated pages might be reported without a title.
The host resolution will follow no more than 10 HTTP Redirect (3**) responses.

Configurations

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.

Build And Install

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
...

Cargo Features

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.

Development

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.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or LICENSE-2.0)
MIT license (LICENSE-MIT or MIT)

at your option.

Contribution

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.

Dependencies

~24–38MB
~684K SLoC