Mailctl

mailctl provides IMAP/SMTP clients with the capabilities of renewal and authorization of OAuth2 credentials.

Documentation

github	https://github.com/pdobsan/mailctl
config docs	https://github.com/pdobsan/mailctl#configuration

Locations

$XDG_CONFIG_HOME/mailctl/config.yml

config

Install

aura -A mailctl-bin
touch ~/.config/mailctl/config.yaml
touch ~/.config/mailctl/services.yaml
mkdir -p ~/.local/var/mailctl/

Usage

• configure directories and gpg-access in config.yaml
• configure services (ex. gmail) in services.yaml

Initial Account Setup

# now you can authorize an email for a particular service
# mailctl authorize ${service} ${email}
mailctl authorize gmail_family foo@gmail.com
open 'http://localhost:8080/start'

# continue manual auth flow

Obtain cached token

# once your service has been authorized once on this computer,
# you can manage access using 'access'
mailctl access foo@gmail.com

You'll also need to periodically renew your token (put this in a cron job)

mailctl rewnew foo@gmail.com

Configuration

Mailctl

# ~/.config/mailctl/config.yml
#
# annotated template: https://github.com/pdobsan/mailctl/blob/main/configs/config-template.yaml

# These four entries should be use for OAuth2 access method
services_file: /home/youruser/.config/mailctl/services.yaml
oauth2_dir: /home/youruser/.local/var/mailctl

# encrypt/decrypt with gpg (other options available)
encrypt_cmd:
  exec: gpg
  args:
    - --encrypt
    - --recipient
    - ${your_gpg_key_id}
    - -o
decrypt_cmd:
  exec: gpg
  args:
    - --decrypt

Services

Gmail

Each email should have it's own configuration (since each will have it's own id/secret).

create OAUTH tokens using instructions in gmail.

# ~/.config/mailctl/config.yml
#
# annotated template: https://github.com/pdobsan/mailctl/blob/main/configs/services-template.yaml
gmail_junk:
  auth_endpoint: https://accounts.google.com/o/oauth2/auth
  auth_http_method: POST
  auth_params_mode: query-string
  token_endpoint: https://accounts.google.com/o/oauth2/token
  token_http_method: POST
  token_params_mode: both
  redirect_uri: http://localhost:8080
  auth_scope: https://mail.google.com/
  client_id: XXXXXXXXXXXXXXXXXX
  client_secret: XXXXXXXXXXXXXXXXXX