imap/src/mailutil/mailutil.1

   1 .ig
   2  * ========================================================================
   3  * Copyright 1988-2008 University of Washington
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *
  12  * ========================================================================
  13 ..
  14 .TH mailutil 1 "March 3, 2008"
  15 .SH NAME
  16 mailutil - mail utility program
  17 .nh
  18 .SH SYNTAX
  19 .B mailutil command [switches] [arguments]
  20 .PP
  21 All commands accept the -d, -v, and -u switches in addition to any
  22 command-specific switches.
  23 .PP
  24 .B mailutil check [MAILBOX]
  25 .PP
  26 .B mailutil create MAILBOX
  27 .PP
  28 .B mailutil dedup MAILBOX
  29 .PP
  30 .B mailutil delete MAILBOX
  31 .PP
  32 .B mailutil rename SOURCE DESTINATION
  33 .PP
  34 .B mailutil copy [-rw] [-kw] [-ig] SOURCE DESTINATION
  35 .PP
  36 .B mailutil move [-rw] [-kw] [-ig] SOURCE DESTINATION
  37 .PP
  38 .B mailutil append [-rw] [-kw] [-ig] SOURCE DESTINATION
  39 .PP
  40 .B mailutil appenddelete [-rw] [-kw] [-ig] SOURCE DESTINATION
  41 .PP
  42 .B mailutil prune MAILBOX CRITERIA
  43 .PP
  44 .B mailutil transfer [-m mode] [-rw] [-kw] [-ig] SOURCE DESTINATION
  45 .SH DESCRIPTION
  46 .B mailutil
  47 replaces the old chkmail, imapcopy, imapmove, imapxfer, mbxcopy,
  48 mbxcreat, and mbxcvt programs.
  49 .PP
  50 .B mailutil check
  51 determines whether new mail exists in the given mailbox (the default
  52 is INBOX).  The number of new messages is defined as the number of
  53 messages that have "Recent" status set.  If the mailbox contains no
  54 new messages,
  55 .B mailutil check
  56 will indicate that no new mail is present;
  57 otherwise, it will report the number of new messages.  In either case,
  58 it will also indicate the canonical form of the name of the mailbox.
  59 .PP
  60 .B mailutil create
  61 creates a new
  62 .I mailbox
  63 with the given name.  The mailbox name must not already exist.  A mailbox
  64 can be created in a particular format by prefixing the name with
  65 .I #driver.
  66 followed by the format name and a
  67 .I /
  68 character.  For example, the command
  69 .br
  70    mailutil create #driver.mbx/junkmail
  71 .br
  72 will create a new mailbox named "junkmail" in mbx format.
  73 .PP
  74 .B mailutil dedup
  75 removes messages that have the same message-id header in a
  76 .I mailbox.
  77 Messages that do not have a message-id header are not removed.
  78 .PP
  79 .B mailutil delete
  80 deletes an existing
  81 .I mailbox
  82 with the given name.
  83 .PP
  84 .B mailutil rename
  85 renames an existing mailbox to a new name (which must not already exist).
  86 This only works if the old and new names are in the same mail store.  A
  87 more general means to rename a mailbox is to do a
  88 .B mailutil copy
  89 of the old name to the new name, followed by a
  90 .B mailutil delete
  91 of the old name.
  92 .PP
  93 .B mailutil copy
  94 creates a new mailbox and copies messages from the old mailbox to the
  95 new mailbox.  As in
  96 .B mailutil create
  97 a mailbox format can be specified with the new mailbox.  For example, the
  98 command
  99 .br
 100    mailutil copy INBOX #driver.mbx/INBOX
 101 .br
 102 will copy messages from your existing INBOX to an mbx-format INBOX.
 103 .PP
 104 .B mailutil move
 105 is similar to
 106 .B mailutil copy
 107 but in addition will also remove (delete and expunge) the messages from the
 108 old mailbox after copying them to the new mailbox.
 109 .PP
 110 .B mailutil append
 111 and
 112 .B mailutil appenddelete
 113 are similar to
 114 .B mailutil copy
 115 and
 116 .B mailutil move
 117 respectively except that they do not create the destination mailbox.
 118 .PP
 119 .B mailutil prune
 120 prunes the mailbox of messages which match certain criteria, which are
 121 in the form of IMAP2 (RFC 1176) SEARCH arguments.  For example, the
 122 command.
 123 .br
 124   mailutil prune INBOX "before 1-jan-2004"
 125 .br
 126 will delete and expunge all messages written before January 1, 2004.
 127 .PP
 128 Note that mailutil implements pruning by deleting the matching messages,
 129 and then expunging the mailbox.  Consequently, mailutil will also expunge
 130 any messages which were deleted at the time of the pruning.
 131 .PP
 132 .B mailutil transfer
 133 copies an entire hierarchy of mailboxes from the named source to the
 134 named destination.  Mailboxes are created on the destination as
 135 needed.  Any error in copying messages will cause the transfer to stop.
 136 .PP
 137 Normally, any error in creation will cause the transfer to stop.
 138 However, if
 139 .B -m MODE
 140 or
 141 .B -merge MODE
 142 is specified, a merging transfer is performed.  The
 143 .B MODE
 144 argument indicats the type of merge:
 145 .PP
 146 .B -m[erge] prompt
 147 indicates that the user should be asked for an alternative name to create.
 148 If creating the new name fails, the user will be asked again.
 149 .PP
 150 .B -m[erge] append
 151 indicates that it's alright to copy the messages into an existing mailbox
 152 with that name.  If the mailbox does not exist, the user will be prompted
 153 for an alternative name.
 154 .PP
 155 .B -m[erge] suffix=XXXX
 156 where XXXX is any string, indicates that an alternative name should be
 157 built by appending the given suffix to the name.  It that alternative name
 158 can't be created, then the user will be prompted for an alternative name.
 159 .PP
 160 The source hierarchy consists of all mailboxes which start
 161 with the given source name.  With the exception of a remote system
 162 specification (within "{}" braces), the source name is used as the
 163 name of the destination.  The destination hierarchy is a prefix
 164 applied to any new names being created.  For example,
 165 .br
 166    mailutil transfer foo bar
 167 .br
 168 will copy all mailboxes with names beginning with "foo" to names
 169 beginning with "bar" (hence "foobar" will be copied to "barfoobar").
 170 Similarly,
 171 .br
 172    mailutil transfer "{imap.foo.com}" "{imap.bar.com}old/"
 173 .br
 174 will copy all mailboxes from the imap.foo.com IMAP server to
 175 equivalent names starting with "old/" on the imap.bar.com IMAP server.
 176 .SH FLAGS
 177 The
 178 .B -d
 179 or
 180 .B -debug
 181 flag prints full debugging telemetry including protocol operations.
 182 .PP
 183 The
 184 .B -v
 185 or
 186 .B -verbose
 187 flag prints verbose (non-error) telemetry.
 188 .PP
 189 The
 190 .B -u USERID
 191 or
 192 .B -user USERID
 193 switch attempts to become the indicated user.  This is for the benefit of
 194 system administrators who want to do mailutil operations on a userid that
 195 does not normally have shell access.
 196 .PP
 197 The
 198 .B -rw
 199 or
 200 .B -rwcopy
 201 flag causes the source mailbox to be open in readwrite mode rather than
 202 readonly mode.  Normally, mailutil tries to use readonly mode to avoid
 203 altering any flags in the source mailbox, but some mailbox types, e.g.
 204 POP3, can't be open in readonly mode.
 205 .PP
 206 The
 207 .B -kw
 208 or
 209 .B -kwcopy
 210 flag causes the keywords of the source mailbox to be created in the
 211 destination mailbox.  Normally, mailutil does not create keywords in
 212 the destination mailbox so only those keywords that are already defined
 213 in the destination mailbox will be preserved.  Note that some IMAP servers
 214 may automatically create keywords, so this flag may not be necessary.
 215 .PP
 216 The
 217 .B -ig
 218 or
 219 .B -ignore
 220 flag causes the keywords of the source mailbox to be ignored completely
 221 and no attempt is made to copy them to the destination mailbox.
 222 .PP
 223 The
 224 .B -ig[nore]
 225 and
 226 .B -kw[copy]
 227 flags are mutually exclusive.
 228 .SH ARGUMENTS
 229 The arguments are standard c-client mailbox names.  A
 230 variety of mailbox name formats and types of mailboxes are supported
 231 by c-client; examples of the most common forms of names are:
 232 .PP
 233 .I
 234 .IP Name 15
 235 .I Meaning
 236 .IP INBOX
 237 primary incoming mail folder on the local system
 238 .IP archive/tx-project
 239 mail folder named "tx-project" in "archive" subdirectory of local
 240 filesystem home directory
 241 .IP {imapserver.foo.com}INBOX
 242 primary incoming mail folder on IMAP server system
 243 "imapserver.foo.com"
 244 .IP {imapserver.foo.com}archive/tx-project
 245 mail folder named "tx-project" in "archive" subdirectory on IMAP
 246 server system "imapserver.foo.com"
 247 .IP #news.comp.mail.misc
 248 newsgroup "comp.mail.misc" on local filesystem
 249 .IP {newserver.foo.com/nntp}comp.mail.misc
 250 newsgroup "comp.mail.misc" on NNTP server system "newserver.foo.com"
 251 .IP {popserver.foo.com/pop3}
 252 mail folder on POP3 server system "popserver.foo.com"
 253 .LP
 254 See your system manager for more information about the types of
 255 mailboxes which are available on your system.
 256 .SH RESTRICTIONS
 257 You must surround a
 258 .I {host}mailbox
 259 argument with quotation marks if you run
 260 .B mailutil
 261 from
 262 .IR csh (1)
 263 or another shell for which braces have special meaning.
 264 .PP
 265 You must surround a
 266 .I #driver.format/mailbox
 267 argument with quotation marks if you run
 268 .B mailutil
 269 from a shell in which "#" is the comment character.
 270 .SH AUTHOR
 271 Mark Crispin, MRC@Washington.EDU