>.TH ROUNDUP-MAILGW 1 "27 October 2022"

NAME
roundup-mailgw - mail gateway for roundup

SYNOPSIS
roundup-mailgw [-h|--help] [-v] [--version] [-c|--default-class default_class] [-S|--set-value [class.]field=value] [-O|--oauth-directory directory] [-T|--oauth-token-endpoint endpoint-url] [instance_home] [mail source [specification]]

OPTIONS

-v --version
    Print version and exit.

-c --default-class hyperdb class
    specify the default tracker class - one of issue (the default), msg, file, user etc. Overrides the tracker's mailgw default_class setting.

-S --set-value [class.]property=value[;property=value]
    specify the values to set on the class specified as prefix using the same format as the Subject line property manipulations. If the class prefix is left out it defaults to msg. Can also be specified with --set-value (and abbreviated to --set).

-O --oauth-directory directory
    Only with OAuth authentication specify the directory containing additional OAuth credentials.

-T --oauth-token-endpoint url
    Token endpoint URL of your cloud provider, only used with OAuth.

DESCRIPTION
The roundup mail gateway may be called in one of four ways:

•   without arguments which will use the env var ROUNDUP_INSTANCE,

•   with an instance_home as the only argument,

•   with both an instance_home and a mail spool file, or

•   with both an instance home and a mail source type and its specification.

PIPE
If there is no mail source specified, the mail gateway reads a single message from the standard input and submits the message to the roundup.mailgw module. UNIX mailbox
In this case, the gateway reads all messages from the UNIX mail spool file and submits each in turn to the roundup.mailgw module. The file is emptied once all messages have been successfully handled. The file is specified as:
 mailbox /path/to/mailbox In all of the following mail source types, the username and password can be stored in a ~/.netrc file. If done so, only the server name needs to be specified on the command-line. The username and/or password will be prompted for if not supplied on the command-line or in ~/.netrc. POP
For the mail source "pop", the gateway reads all messages from the POP server specified and submits each in turn to the roundup.mailgw module. The server is specified as:
 pop username:password@server
The username and password may be omitted:
 pop username@server
 pop server
are both valid. POPS
Connect to the POP server over ssl/tls. This supports the same notation as POP. APOP
Same as POP, but using Authenticated POP:
 apop username:password@server IMAP
Connect to an IMAP server. This supports the same notation as that of POP mail.
 imap username:password@server
It also allows you to specify a specific mailbox other than INBOX using this format:
 imap username:password@server mailbox IMAPS
Connect to an IMAP server over ssl/tls. This supports the same notation as IMAP.
 imaps username:password@server [mailbox] IMAPS_CRAM
Connect to an IMAP server over ssl/tls using CRAM-MD5 authentication. This supports the same notation as IMAP.
 imaps_cram username:password@server [mailbox] IMAPS_OAUTH
Connect to an IMAP server over ssl/tls using OAUTH authentication. Note that this does not support a password in imaps URLs. Instead it uses only the user and server and a command-line option for the directory with the files access_token, refresh_token, client_secret, and client_id. By default this directory is oauth in your tracker home directory. The access token is tried first and, if expired, the refresh token together with the client secret is used to retrieve a new access token. Note that both token files need to be writeable, the access token is continuously replaced and some cloud providers may also renew the refresh token from time to time:
 imaps_oauth username@server [mailbox]
The refresh and access tokens (the latter can be left empty), the client id and the client secret need to be retrieved via cloud provider specific protocols or websites.

ENVIRONMENT VARIABLES
ROUNDUP_INSTANCE
This can be used to set the instance directory. If it is set, the instance_home argument is optional.

EXAMPLE
If your msg class has a messsagetype property you can set up aliases to receive the different types of messages. Setting up an alias in your MTA Using:
  tracker: |/tools/roundup/bin/roundup-mailgw
             -S "msg.messagetype=reply - to all" /var/roundup/sysadmin (the lines are split for readability. In the alias file they will be on the same line). Replace /tools/roundup/bin/roundup-mailgw by your path to the roundup-mailgw. This creates the email alias "tracker". All messages sent to it have their messagetype property set to "reply - to all". The roundup tracker instance is located at /var/roundup/sysadmin. A comment alias would receive emails at tracker_comment with:
  tracker_comment: |/tools/roundup/bin/roundup-mailgw
             -S "msg.messagetype=to tech" /var/roundup/sysadmin which would be a technical message. These messages can trigger different workflows based on the messagetype. Both examples use the default class specified in the tracker's config.ini (usually the issue class). You can also set properties directly on the issue class. If your tracker's issue has a "private" property that limits who can view an issue and its messages:
  security: |/tools/roundup/bin/roundup-mailgw
             -S "issue.private=true" -S "issue.keyword+=security"
             /var/roundup/sysadmin would set the private property on a issue to restrict visiblity and mark the issue as a security topic using a keyword. Both examples use the default class specified in the tracker's config.ini (usually the issue class).

AUTHOR
This manpage was written by Bastian Kleineidam <calvin@debian.org> for the Debian distribution of roundup. The main author of roundup is Richard Jones <richard@users.sourceforge.net>. Updates by John Rouillard <rouilj@users.sourceforge.net> and Ralf Schlatterbeck <rsc@runtux.com>.