pymap-admin

The pymap-admin tool can be used to perform various admin functions against a running pymap server. This is a separate grpc service using grpclib listening on a socket.

API Documentation

Connections

By default, the pymap-admin command will attempt to interact with a pymap admin server over a UNIX socket, typically in /tmp/pymap/pymap-admin.sock. See the pymap-admin --help commands for other connection options.

Commands

save-args Command

When administering remote pymap servers, it can be cumbersome to always supply connection arguments every time, such as --host. This command saves the arguments it is given to a config file.

$ pymap-admin --host imap.example.com --port 50051 save-args
Config file written: /home/user/.config/pymap/pymap-admin.conf

login Command

Sends login credentials and gets a bearer token. See Authentication for more information.

$ pymap-admin login -is user@example.com
user@example.com Password:
result {
  response: ". OK Login completed."
}
bearer_token: "MDAwZWxvY2F0aW9uIAowMDMwaWRlbnRpZmllciA0ZmM4MD..."

ping Command

Pings the running server and reports its version string.

$ pymap-admin ping
pymap_version: "0.21.1"
pymap_admin_version: "0.5.2"

append Command

To append a message directly to a mailbox, without using IMAP, use the append admin command. First, check out the help:

$ pymap-admin append --help

As a basic example, you can append a message to a like this:

$ cat <<EOF | pymap-admin append demouser
> From: user@example.com
>
> test message!
> EOF
mailbox: "INBOX"
validity: 1784302999
uid: 101

2.0.0 Message delivered

User Commands

These commands access and manipulate the users on the system:

$ pymap-admin set-user --help
$ pymap-admin change-password --help
$ pymap-admin get-user --help
$ pymap-admin delete-user --help

Passing a username to get-user will display that user's metadata, including the (securely hashed) password string. A username can be deleted with delete-user. The set-user command will create or overwrite a username, its password, and other metadata. The change-password command can update only the password of an existing username.

If using pymap as part of the slimta-docker configuration, see its Address Management documentation for additional options.

Admin Role

The builtin pymap backends use a special role string "admin" to assign admin privileges to existing users. Without the admin role, a user may only use set-user to change their own password. A user with the admin role (or using the admin token) can make any change to any user.

$ pymap-admin set-user --role admin user@example.com

Authentication

Every command except ping requires authentication to perform. Most commands will send a macaroon token to authenticate, except for login which uses the credentials provided.

When running pymap-admin and pymap on the same machine, a temporary file containing an admin token is used by default, allowing unrestricted access to all operations. This token is verified in-memory and is only valid for the current pymap process.

To use this admin token on another machine, copy the PYMAP_ADMIN_TOKEN=... line printed out on pymap startup and prefix it to pymap-admin calls, e.g.:

$ PYMAP_ADMIN_TOKEN=... pymap-admin get-user user@example.com

Permanent Tokens

For a token that is not tied to the current pymap process, use the login with the credentials of a user in the system. The resulting token can be used to authenticate as that user in the future.

$ pymap-admin login -is user@example.com

The -s flag will cause the token to be saved and used on future pymap-admin commands. Use --token-file or $PYMAP_ADMIN_TOKEN_FILE to specify a location, otherwise it is saved to ~/.pymap-admin.token.

If -s is not given, the bearer_token value from the output can provided to future pymap-admin commands with $PYMAP_ADMON_TOKEN.