MAN page from Fedora 23 archivemail-0.9.0-7.fc23.noarch.rpm


Section: archivemail user manual (1)
Updated: 5 July 2011


archivemail - archive and compress your old email 


archivemail [options] {MAILBOX...}



is a tool for archiving and compressing old email in mailboxes. By default it will read the mailboxMAILBOX, moving messages that are older than the specified number of days (180 by default) to ambox(5)-format mailbox in the same directory that is compressed withgzip(1). It can also just delete old email rather than archive it.

By default,archivemailderives the archive filename from the mailbox name by appending an_archivesuffix to the mailbox name. For example, if you runarchivemailon a mailbox calledexsouthrock, the archive will be created with the filenameexsouthrock_archive.gz. This default behavior can be overridden with command line options, choosing a custom suffix, a prefix, or a completely custom name for the archive.

archivemailsupports readingIMAP,Maildir,MHandmbox-format mailboxes, but always writesmbox-format archives.

Messages that are flagged important are not archived or deleted unless explicitly requested with the--include-flaggedoption. Also,archivemailcan be configured not to archive unread mail, or to only archive messages larger than a specified size.

To archive anIMAP-format mailbox, use the formatimap://username:password@server/mailbox to specify the mailbox.archivemailwill expand wildcards inIMAPmailbox names according to[RFC 3501], which says:lqThe character "*" is a wildcard, and matches zero or more characters at this position. The character "%" is similar to "*", but it does not match a hierarchy delimiter.rqYou can omit the password from theURL; use the--pwfileoption to makearchivemailread the password from a file, or alternatively just enter it upon request. If the--pwfileoption is set,archivemaildoes not look for a password in theURL, and the colon is not considered a delimiter. Substituteimapwithimaps, andarchivemailwill establish a secureSSLconnection. See below for moreIMAPpeculiarities. 


-d NUM, --days=NUM

Archive messages older thanNUMdays. The default is 180. This option is incompatible with the--dateoption below.

-D DATE, --date=DATE

Archive messages older thanDATE.DATEcan be a date string in ISO format (eglq2002-04-23rq), Internet format (eglq23 Apr 2002rq) or Internet format with full month names (eglq23 April 2002rq). Two-digit years are not supported. This option is incompatible with the--daysoption above.

-o PATH, --output-dir=PATH

Use the directory namePATHto store the mailbox archives. The default is the same directory as the mailbox to be read.

-P FILE, --pwfile=FILE

ReadIMAPpassword from fileFILEinstead of from the command line. Note that this will probably not work if you are archiving folders from more than one IMAP account.

-F STRING, --filter-append=STRING

AppendSTRINGto theIMAPfilter string. ForIMAPwizards.

-p NAME, --prefix=NAME

PrefixNAMEto the archive name.NAMEis expanded by thepython(1)functiontime.strftime(), which means that you can specify special directives inNAMEto make an archive named after the archive cut-off date. See the discussion of the--suffixoption for a list of validstrftime()directives. The default is not to add a prefix.

-s NAME, --suffix=NAME

Use the suffixNAMEto create the filename used for archives. The default is_archive, unless a prefix is specified.

Like a prefix, the suffixNAMEis expanded by thepython(1)functiontime.strftime()with the archive cut-off date.time.strftime()understands the following directives:

Locale's abbreviated weekday name.
Locale's full weekday name.
Locale's abbreviated month name.
Locale's full month name.
Locale's appropriate date and time representation.
Day of the month as a decimal number [01,31].
Hour (24-hour clock) as a decimal number [00,23].
Hour (12-hour clock) as a decimal number [01,12].
Day of the year as a decimal number [001,366].
Month as a decimal number [01,12].
Minute as a decimal number [00,59].
Locale's equivalent of either AM or PM.
Second as a decimal number [00,61]. (1)
Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
Weekday as a decimal number [0(Sunday),6].
Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
Locale's appropriate date representation.
Locale's appropriate time representation.
Year without century as a decimal number [00,99].
Year with century as a decimal number.
Time zone name (or by no characters if no time zone exists).
A literallq%rqcharacter.

-a NAME, --archive-name=NAME

UseNAMEas the archive name, ignoring the name of the mailbox that is archived. Like prefixes and suffixes,NAMEis expanded bytime.strftime()with the archive cut-off date. Because it hard-codes the archive name, this option cannot be used when archiving multiple mailboxes.

-S NUM, --size=NUM

Only archive messages that areNUMbytes or greater.

-n, --dry-run

Don't write to any files -- just show what would have been done. This is useful for testing to see how many messages would have been archived.

-u, --preserve-unread

Do not archive any messages that have not yet been read.archivemaildetermines if a message in ambox-format orMH-format mailbox has been read by looking at theStatusheader (if it exists). If the status header is equal tolqROrqorlqORrqthenarchivemailassumes the message has been read.archivemaildetermines if amaildirmessage has been read by looking at the filename. If the filename contains anlqSrqafter:2,then it assumes the message has been read.


Do not mangle lines in message bodies beginning withlqFrom rq. When archiving a message from a mailbox not inmboxformat, by defaultarchivemailmangles such lines by prepending alq>rqto them, since mail user agents might otherwise interpret these lines as message separators. Messages frommboxfolders are never mangled. Seembox(5)for more information.


Delete rather than archive old mail. Use this option with caution!


Copy rather than archive old mail. Creates an archive, but the archived messages are not deleted from the originating mailbox, which is left unchanged. This is a complement to the--deleteoption, and mainly useful for testing purposes. Note that multiple passes will create duplicates, since messages are blindly appended to an existing archive.


Archive all messages, without distinction.


Normally messages that are flagged important are not archived or deleted. If you specify this option, these messages can be archived or deleted just like any other message.


Do not compress any archives.


Warn about duplicateMessage-IDs that appear in the input mailbox.

-v, --verbose

Reports lots of extra debugging information about what is going on.


SetIMAPdebugging level. This makesarchivemaildump its conversation with theIMAPserver and some internalIMAPprocessing tostdout. Higher values forNUMgive more elaborate output. SetNUMto 4 to see all exchangedIMAPcommands. (Actually,NUMis just passed literally toimaplib.Debug.)

-q, --quiet

Turns on quiet mode. Do not print any statistics about how many messages were archived. This should be used if you are runningarchivemailfrom cron.

-V, --version

Display the version ofarchivemailand exit.

-h, --help

Display brief summary information about how to runarchivemail.


archivemailrequirespython(1)version 2.3 or later. When reading anmbox-format mailbox,archivemailwill create a lockfile with the extension.lockso thatprocmail(1)will not deliver to the mailbox while it is being processed. It will also create an advisory lock on the mailbox usinglockf(2). The archive is locked in the same way when it is updated.archivemailwill also complain and abort if a 3rd-party modifies the mailbox while it is being read.

archivemailwill always attempt to preserve the last-access and last-modify times of the input mailbox. Archive mailboxes are always created with a mode of0600. Ifarchivemailfinds a pre-existing archive mailbox it will append rather than overwrite that archive.archivemailwill refuse to operate on mailboxes that are symbolic links.

archivemailattempts to find the delivery date of a message by looking for valid dates in the following headers, in order of precedence:Delivery-date,Received,Resent-DateandDate. If it cannot find any valid date in these headers, it will use the last-modified file timestamp onMHandMaildirformat mailboxes, or the date on theFrom_line onmbox-format mailboxes.

When archiving mailboxes with leading dots in the name,archivemailwill strip the dots off the archive name, so that the resulting archive file is not hidden. This is not done if the--prefixor--archive-nameoption is used. Should there really be mailboxes distinguished only by leading dots in the name, they will thus be archived to the same archive file by default.

A conversion from other formats tombox(5)will silently overwrite existingStatusandX-Statusmessage headers. 


Whenarchivemailprocesses anIMAPfolder, all messages in that folder will have their\Recentflag unset, and they will probably not show up aslqnewrqin your user agent later on. There is no way around this, it's just howIMAPworks. This does not apply, however, if you runarchivemailwith the options--dry-runor--copy.

archivemailrelies on server-side searches to determine the messages that should be archived. When matching message dates,IMAPservers refer to server internal message dates, and these may differ from both delivery time of a message and itsDateheader. Also, there exist broken servers which do not implement server side searches.


archivemail'sIMAPURLparser was written with theRFC2882 (Internet Message Format) rules for thelocal-partof email addresses in mind. So, rather than enforcing anURL-style encoding of non-asciiand reserved characters, it allows to double-quote the username and password. If your username or password contains the delimiter characterslq@rqorlq:rq, just quote it like this:imap://"":"password" You can use a backslash to escape double-quotes that are part of a quoted username or password. Note that quoting only a substring will not work, and be aware that your shell will probably remove unprotected quotes or backslashes.

Similarly, there is no need to percent-encode non-asciicharacters inIMAPmailbox names. As long as your locale is configured properly,archivemailshould handle these without problems. Note, however, that due to limitations of theIMAPprotocol, non-asciicharacters do not mix well with wildcards in mailbox names.

archivemailtries to be smart when handling mailbox paths. In particular, it will automatically add anIMAPNAMESPACEprefix to the mailbox path if necessary; and if you are archiving a subfolder, you can use the slash as a path separator instead of theIMAPserver's internal representation.



To archive all messages in the mailboxdebian-userthat are older than 180 days to a compressed mailbox calleddebian-user_archive.gzin the current directory:

bash$ archivemail debian-user

To archive all messages in the mailboxdebian-userthat are older than 180 days to a compressed mailbox calleddebian-user_October_2001.gz(where the current month and year is April, 2002) in the current directory:

bash$ archivemail --suffix '_%B_%Y' debian-user

To archive all messages in the mailboxcm-melbthat are older than the first of January 2002 to a compressed mailbox calledcm-melb_archive.gzin the current directory:

bash$ archivemail --date='1 Jan 2002' cm-melb

Exactly the same as the above example, using anISOdate format instead:

bash$ archivemail --date=2002-01-01 cm-melb

To delete all messages in the mailboxspamthat are older than 30 days:

bash$ archivemail --delete --days=30 spam

To archive all read messages in the mailboxincomingthat are older than 180 days to a compressed mailbox calledincoming_archive.gzin the current directory:

bash$ archivemail --preserve-unread incoming

To archive all messages in the mailboxreceivedthat are older than 180 days to an uncompressed mailbox calledreceived_archivein the current directory:

bash$ archivemail --no-compress received

To archive all mailboxes in the directory$HOME/Mailthat are older than 90 days to compressed mailboxes in the$HOME/Mail/Archivedirectory:

bash$ archivemail -d90 -o $HOME/Mail/Archive $HOME/Mail/*

To archive all mails older than 180 days from the givenIMAPINBOXto a compressed mailboxINBOX_archive.gzin the$HOME/Mail/Archivedirectory, quoting the password and reading it from the environment variablePASSWORD:

bash$ archivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'

Note the protected quotes.

To archive all mails older than 180 days in subfolders offooon the givenIMAPserver to corresponding archives in the current working directory, reading the password from the file~/imap-pass.txt:

bash$ archivemail --pwfile=~/imap-pass.txt imaps://*


Probably the best way to runarchivemailis from yourcrontab(5)file, using the--quietoption. Don't forget to try the--dry-runand perhaps the--copyoption for non-destructive testing. 


Normally the exit status is 0. Nonzero indicates an unexpected error. 


If an IMAP mailbox path contains slashes, the archive filename will be derived from the basename of the mailbox. If the server's folder separator differs from the Unix slash and is used in the IMAP URL, however, the whole path will be considered the basename of the mailbox. E.g. the two URLs imap:// and imap:// will be archived in subfolder_archive.gz and folder.subfolder_archive.gz, respectively, although they might refer to the same IMAP mailbox.

archivemail does not support reading MMDF or Babyl-format mailboxes. In fact, it will probably think it is reading an mbox-format mailbox and cause all sorts of problems.

archivemail is still too slow, but if you are running from crontab(5) you won't care. Archiving maildir-format mailboxes should be a lot quicker than mbox-format mailboxes since it is less painful for the original mailbox to be reconstructed after selective message removal. 


mbox(5), crontab(5), python(1), procmail(1) 


The archivemail home page is currently hosted at m[blue]sourceforgem[][1] 


This manual page was written by Paul Rodger <paul at paulrodger dot com>. Updated and supplemented by Nikolaus Schulz 






This document was created byman2html,using the manual pages.