<<< Previous | Simple Mail Access Protocol, Version 1 | Next >>>

# Adding messages to folders

C: ADD FOLDER Folders "Sent Mail" ""
S: +OK Ok
C: ADD RCPTTO=tom@example.com RCPTTO=alice@example.com
S: +OK Ok
C: ADD MAILFROM=john@example.com FLAGS=SEEN,DRAFT
S: +OK Ok
C: ADD {.7618}
S: > Proceed, please.
C: From: <john@example.com>
C: To: distribution-list: ;
C: Subject: Meeting
C:
C: [ ... ]
C: .
S: * ADD UID=1043320248/3479
S: +OK Message added

The `ADD` command uploads a message from the client to the server to a folder, and/or sends the message to its designated recipients. In most cases the client sends several `ADD` commands that specify the attributes, and/or the properties of a given message. The client may send everything in a single `ADD` command provided that it is not large enough to exceed the maximum line length limitation, but most clients will find it easier just to use multiple commands. Other SMAP commands cannot be intermixed with a batch of `ADD` commands. Upon receiving another command, the server quietly aborts the upload process before handling the command, and the client will have to start over at some later point in time. A single rejected `ADD` does not abort the upload, the client can retry or explicitly issue some other command (such as the `RSET` command) to abort it.

The following attributes and/or keywords follow the `ADD` command:

FOLDER `name` ""

  This keyword specifies the folder where the message is added to. A maximum of one `FOLDER` may be specified. Whitespace-delimited words that name an existing folder follow the `FOLDER` keyword, followed by a single empty word. At least one `RCPTTO` keyword is required if `FOLDER` is not specified, in which case the message is only mailed to the designated recipients without saving a copy in any folder. Both `FOLDER` and `RCPTTO` keywords may be specified; the message is both saved in the folder, and sent to its designated recipients.

RCPTTO=`user`@`host`

  Specifies the message's recipient. If this keyword is present, the message will be mailed to the specified address. Multiple occurences of `RCPTTO` specify multiple recipients.

MAILFROM=`user`@`host`

  Specifies the message's return address. This is optional, if not specified, the server uses whatever it thinks the return address is. Clients should not rely on this, because the mechanism by which the server makes this determination is not specified, and will vary from server to server.

NOTIFY=`list`

  Sets delivery status notification options for the sent message, as described by RFC 1891. This is an optional keyword that may not be implemented by all servers. Servers that do not implement delivery status notifications should reject this keyword.

  `list` is a comma-separated list of the usual delivery confirmation requests, such as "`SUCCESS,FAIL`". The default set of delivery status notifications (when this keyword is not specified) is implementation-defined.

FLAGS, KEYWORDS, INTERNALDATE

  The `FLAGS`, `KEYWORDS`, and `INTERNALDATE` set their corresponding attributes, when the message is to be saved in a folder. See "Reading message attributes" for more information. These keywords are optional, and the server will use implementation-defined defaults if they are not specified.

{.`nnnn`} or {`xxxx`/`yyyy`}

  This keyword must appear in the last `ADD` command (when the client uses multiple `ADD` commands to list all attributes and properties). It indicates that the client is ready to upload the contents of the message to the server. The client uses the same multi-line or binary format that's used for downloading message contents from the server, with one difference. The client does not proceed with sending the actual message immediately. The client must wait for the server's reply. The server replies with a single line of text whose first whitespace-delimited word is a single `>` character. Note that the server may reject the command (and the client will receive an `-ERR`), otherwise, upon receiving the "`>`" the client should then proceed to send the contents of the message, in accordance with the selected transmission format, then wait for the server's final reply.

  The server's final response may include an optional `* ADD` single line reply. A list of whitespace-delimited keywords follow. At this time, only the following keyword is defined by this specification:

  UID=`uid`

    Specifies the message's unique identifier, if the message is succesfully saved in a folder.

    NOTE:

    This keyword is not sent when the message is only mailed, without saving a copy in a folder. Furthermore, the `ADD` command is not limited to saving the message in the currenly open folder. The message may be saved in any folder. But if it is, the message will not be immediately accessible. The clients needs to issue a `NOOP`. Presumably the server will indicate that new messages were added to the folder, and additional `FETCH` commands will reveal that one of the messages has the same unique identifier that was specified in this reply.

    Of course, it is always possible that someone else deleted the new message before this client had a chance to issue a `NOOP`, so the new message is still not guaranteed to be there. Such is life in a multiprocessing environment, I suppose...

## The `RSET` command

C: RSET
S: +OK RSET completed

This command does absolutely nothing. Its main purpose is the side effect of aborting the current upload of a new message via the `ADD` command.

<<< Previous | Home | Next >>>
More comments on concurrency | Up | Copying and moving messages