|
Allegro CL version 11.0 | ||||||||
Function, net.post-office package
Arguments: structure
Certain components of an envelope include email addresses (such as envelope-to). These addresses are represented as lists of four items, the name, the mailbox, the host, and additional information. This function accesses the additional information of such an address.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
Certain components of an envelope include email addresses (such as envelope-to). These addresses are represented as lists of four items, the name, the mailbox, the host, and additional information. This function accesses the host of such an address.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
Certain components of an envelope include email addresses (such as envelope-to). These addresses are represented as lists of four items, the name, the mailbox, the host, and additional information. This function accesses the mailbox of such an address.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
Certain components of an envelope include email addresses (such as envelope-to). These addresses are represented as lists of four items, the name, the mailbox, the host, and additional information. This function accesses the name of such an address.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox messages &key flags add-flags remove-flags silent uid
This function changes the flags of the messages in the specified way. Exactly one of flags, add-flags, and remove-flags must be specified.
flags specifies the complete set of flags to be stored in the messages and the other two add or remove flags. If uid is true then messages will be interpreted as unique ids rather than message sequence numbers.
Normally alter-flags returns a data structure that describes the state of the flags after the alteration has been done. This data structure can be examined with the fetch-field function. But if silent is true then this data structure won't be created thus saving some time and space.
Removing a message from a mailbox is done by adding the :\deleted flag to the message and then either calling close-mailbox or expunge-mailbox.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This sends a logout command to the imap server and then closes the socket that's communicating with the imap server. mailbox is the object returned by make-imap-connection.
This function does not close the currently selected mailbox location before logging out, thus messages marked to be deleted in the currently selected mailbox location will not be removed from the mailbox. Use close-mailbox or expunge-mailbox before calling close-connection to ensure that messages to be deleted are deleted.
This function disconnects from the pop server. All messages marked for deletion will be deleted.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This function permanently removes all messages flagged as :\deleted from the currently selected mailbox and then un-selects the currently selected mailbox. After this command has finished there is no currently selected mailbox.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox messages destination &key uid
This function copies the specified messages from the currently selected mailbox to the mailbox named destination (given as a string). The flags are copied as well. The destination mailbox must already exist. The messages are not removed from the selected mailbox after the copy. If uid is true then the messages are considered to be unique ids rather than message sequence numbers.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox name
This function creates a new mailbox with the given name. It is an error if the mailbox already exists. If you want to create a mailbox in a hierarchy then you should be sure that it uses the correct hierarchy separator character string (see mailbox-separator). You do not have to create intermediate levels of the hierarchy yourself -- just provide the complete name and the imap server will create all necessary levels.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox messages &key expunge uid
When using an imap server, mailbox is the mailbox object returned by make-imap-connection. This function marks the messages for deletion and then removes them permanently (using expunge-mailbox) if expunge is true. expunge defaults to true. If uid is true then the message numbers are unique ids instead of message sequence numbers.
When using a pop server, only the mailbox and messages arguments are used. This function marks the specified messages for deletion. mailbox is the mailbox object returned by make-pop-connection. The messages are only marked for deletion. They are not removed until a close-connection is done. If the connection to the pop server is broken before a close-connection is done, the messages will not be deleted and they will no longer be marked for deletion either.
messages can either be a message number, a list of the form (:seq N M) meaning messages N through M or it can be a list of message numbers and/or :seq specifiers. The messages in a mailbox are numbered starting with one. Marking a message for deletion does not affect the numbering of other messages in the mailbox.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox name
This function deletes the mailbox with the given name.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
end-of-letter-p returns true if the end of the letter has been reached. This can be used to terminate a loop of fetch-letter-sequence calls.
end-of-letter-p is only implemented for pop mailboxes.
end-of-letter-p must only be used within a with-fetch-letter-sequence body.
See also with-fetch-letter-sequence and fetch-letter-sequence.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the bcc field of the envelope is returned by this function.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the cc field of the envelope is returned by this function.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the date of the envelope is returned by this function.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the from field of the envelope is returned by this function.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the in-reply-to field of the envelope is returned by this function.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the message-id field of the envelope is returned by this function.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the reply-to field of the envelope is returned by this function.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the sender of the envelope is returned by this function.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the subject of the envelope is returned by this function.
See imap.html for more information.
Function, net.post-office package
Arguments: structure
If the structure returned by fetch-parts contains an envelope, the to field of the envelope is returned by this function.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This function permanently removes all messages flagged as :\deleted from the currently selected mailbox. The currently selected mailbox stays selected.
See imap.html for more information.
Function, net.post-office package
Arguments: message part info &key uid
This function is used to extract the desired information from the value returned by fetch-letter. With fetch-letter, you can retrieve a variety of information about one or more messages and fetch-field can search through that information and return a particular piece of information about a particular letter.
message is the message number (it's assumed to be a message sequence number unless uid is true, in which case it's a unique id).
part is the type of information desired. It is a string just as used in the call to fetch-letter.
info is the result fetch-letter.
See imap.html for more information. The section Fetching a Letter is particularly relevant.
Generic Function, net.post-office package
Arguments: message part &key uid
This function returns the complete message, headers and body, as one big string. This is a combination of fetch-field and fetch-parts where the part specification is "body[]".
This function fetches from the pop server connection mailbox the letter numbered message. The letters in a mailbox are numbered starting with one. The entire message, including the headers, is returned as a string. It is an error to attempt to fetch a letter marked for deletion. See also with-fetch-letter-sequence.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox buffer &key start end
fetch-letter-sequence fills buffer with the next chunk of text read from the current letter (as established by with-fetch-letter-sequence). start specifies the index of the first element in the buffer in which to store, and end is one plus the index of the last element in which to store.
The return value will always be equal to end unless the end of the message was reached while reading, in which case the return value will be one plus the last index in the buffer filled.
fetch-letter-sequence is only implemented for pop mailboxes.
fetch-letter-sequence must only be used within a with-fetch-letter-sequence body.
See also with-fetch-letter-sequence and end-of-letter-p.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox messages parts &key uid
This function retrieves the specified parts of the specified messages. If uid is true then the messages are considered to be unique ids rather than message sequence numbers. The description of what can be specified for parts is quite complex. It is described in detail in Fetching a Letter in imap.html.
The return value from this function is a structure that can be examined with fetch-field.
When the result returned includes an envelope value the following functions can be used to extract the components of the envelope:
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This function returns a complete list of flags used in all the messages in this mailbox.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox &key reference pattern
This function returns a list of items describing the mailboxes that match the arguments. The reference is the root of the hierarchy to scan. By default it is the empty string (from which all mailboxes are reachable). The pattern is a string matched against all mailbox names reachable from reference. There are two special characters allowed in the pattern: an asterisk (*) matches all characters including hierarchy delimiters; a percent (%) matches all characters but not the hierarchy delimiter. Thus
(mailbox-list mailbox :pattern "*")returns a list of all mailboxes at all depths in the hierarchy.
The value returned is a list of lists. Accessing the inner lists can be done with the following accessor functions:
See imap.html for more information.
Function, net.post-office package
Arguments: mailbox-list
The argument mailbox-list is the list of lists returned by mailbox-list. This accessor function returns the flags describing this entry. The most important flag to check is :\noselect as this specifies that this is not a mailbox but instead just a directory in the hierarchy of mailboxes. The flag :\noinferiors specifies that you can't create a hierarchical mailbox name with this as a prefix. This flag is often associated with the special mailbox inbox.
See imap.html for more information.
Function, net.post-office package
Arguments: mailbox-list
The argument mailbox-list is the list of lists returned by mailbox-list. This accessor returns the name of the mailbox or directory (see mailbox-list-flags to determine which it is).
See imap.html for more information.
Function, net.post-office package
Arguments: mailbox-list
The argument mailbox-list is the list of lists returned by mailbox-list. This accessor returns a string containing the characters used to separate names in a hierarchical name.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This function returns the number of messages in the currently selected mailbox.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This function returns a list of flags that can be stored permanently in a message. If the flag :\* is present then it means that the client can create its own flags.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This function returns the number of messages that have just arrived in the mailbox.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This function returns the hierarchy separator string for this imap server.
See imap.html for more information.
Function, net.post-office package
Arguments: mailbox
This function returns the value predicated to be the unique id assigned to the next message.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This function returns the uidvalidity value for the currently selected mailbox.
See imap.html for more information.
Function, net.post-office package
Arguments: text
text is a string that is the first part of a mail message, including at least all of the headers lines and the blank line following the headers. Given this partial message, this function parses the header lines and returns an envelope structure containing information from the header. This is useful for parsing the headers of things returned by a pop server.
See imap.html for more information.
Function, net.post-office package
Arguments: host &key user password port timeout
This function creates a connection to the imap server on machine specified by host and returns a mailbox object which represents the connection. The host argument can encode additional information, as described below.
It logs in as user with password password. The port argument defaults to 143, which is the port on which the imap server normally listens.
The timeout argument defaults to 30 (seconds) and this value is used to limit the amount of time this imap interface code will wait for a response from the server before giving up. In certain circumstances the server may get so busy that you see timeout errors signaled in this code. In that case you should specify a larger timeout when connecting.
The make-imap-connection function returns a mailbox object which can then be passed to other functions in this interface. From this one connection you can access all of the mailbox locations owned by user.
After the connection is established a mailbox location is not selected. In this state attempting to execute message access functions may result in cryptic error messages from the imap server that won't tell you what you need to know -- that a mailbox location is not selected. Therefore be sure to select a mailbox location using select-mailbox shortly after connecting.
The host argument can serve several functions as well as just specifying the host, which it does in all cases. It can also specify a port number. And it can specify SSL and STARTTLS details. We discuss each use in turn.
The value can be a string naming a machine, or an IP address (in dotted form, as an integer for IPv4 addresses, or an IPv6 address structure).
By default, this function makes a connection to port 143 on host.
If you need to connect to a port other than the default (port 143), you can specify the host argument in one of the following two ways to specify the alternate port number (and, as described below, an alternate port can be specified along with SSL and STARTTLS information):
As a cons: if host is specified as a cons, the car should be the name or IP address of the host and the cdr should be the alternate port number. e.g. you could specify '("smtp.example.com" . 99) and port 99 will be used.
As a colon-separate string: the text before the colon specifies the hostname or IP address of the host and the text after the colon specifies the alternate port number. e.g. "smtp.example.com:99". Note that this form is not suitable if the host is specified as an IPv6 dotted address (because the dotted address uses colons as separators).
The most general form of the mail-server argument is a list of the form:
(server-name &key (port 143) (ssl nil) (starttls nil) ...ssl-client-keywords...)where
server-name is as described above for specifying the server only (i.e. a string or an IP address).
port allows for another way to specify the port to connect to. The default port for tcp connections is 143. When ssl is non-nil, the default port is 993.
If ssl is non-nil, make-ssl-client-stream will be called after establishing a connection to the smtp server. All ssl-client-keywords are passed to make-ssl-client-stream as well.
If starttls is non-nil, it allows for negotiation of a secure connection (TLSv1) if the server supports it. If the server supports both auth and starttls, starttls will be negotiated before attempting authentication.
make-ssl-client-stream are accepted. e.g. :method :ciphers, certificate related args, etc. They are only used if ssl is non-nil.
No error is signalled if both ssl and starttls are non-nil. The SSL connection is established before any starttls negotiation would begin.
See also with-imap-connection. See imap.html for additional information.
Function, net.post-office package
Arguments: &key content-type encoding external-format headers attachmentp name text start end file subparts id description parameters charset
This function returns a mime-part-constructed object with properties as specified by the arguments. There are many examples using this function in MIME support in imap.html.
Like many Lisp constructor functions, make-mime-part offers a lot of options and looks complicated but typically only a few of the many keyword arguments are actually necessary. make-mime-part supplies many defaults that are sufficient for the most common scenarios.
MIME parts have contents. The contents can be supplied in one of three ways: with the text argument, with the file argument, or with the subparts argument:
Using the text keyword argument: the text keyword argument specifies a string that will be used as the body of the new part. If one or both of the start and end keyword arguments are supplied, then the desired subsequence of the string will be used. The default content-type is "text/plain" when text is a string. See also the description of the external-format keyword argument.
The text keyword argument can also be an (unsigned-byte 8) array. The subsequence of the array bounded by the start and end keyword arguments (specified) will be used. The default content-type is "application/octet-stream" when text is an (unsigned-byte 8) array.
Using the file keyword argument: the file keyword argument specifies a filename or an input stream that will be used to populate the body of new part. Note that the file/stream is not read until the part is rendered. If the argument is an input stream, it must be a stream that is capable of being read in an octet-oriented manner (e.g., it cannot be a string-input-stream). The default content-type will be deduced based on the specified filename or the filename associated with the input stream (if possible). If no specific content-type can be deduced, "application/octet-stream" will be used as the default. See also the description of the external-format keyword argument.
Using the subparts keyword argument: this only applies to multipart parts. The contents of a multipart part are simply other parts. The subparts argument should be a list of parts (as constructed by make-mime-part). The default content-type when subparts is specified is "multipart/mixed".
The start and end keyword arguments can be used to specify a subsequence of a text string to use. See the description of the text argument just above.
The remaining keyword arguments allow you to augment and override default settings for the new part:
content-type is a string specifying the MIME content type of the part. Examples: "text/plain", "text/html", "multipart/mixed", "multipart/alternative", etc. If no content-type is supplied, a default is chosen based on the other arguments to the function. The descriptions of text file subparts above say how defaults are selected. If the content-type is text, make sure you supply the proper charset if necessary.
The external-format keyword argument is only used if the content-type is a text type (i.e., a content type of the form text/:utf-8. If the text of the part is being supplied from a file, make sure the external-format keyword argument corresponds to the external format of the file.
encoding is a string specifying how the part contents should be encoded (after any external format processing). Valid choices are "7bit", "8bit", "base64" and "quoted-printable". The default encoding is selected according to the following rules:
If the :text keyword argument is supplied and is a string, then the string is converted to a usb8 array (using the external-format specified in the :external-format keyword argument, which defaults to :utf-8). The usb8 array is then scanned to see if there are any bytes with the high bit set. If there are, "base64" is selected as the encoding. Otherwise "7bit" is selected.
Otherwise, "base64" is selected.
The attachmentp keyword argument controls the attachment disposition of the mime part. Generally, parts marked as "inline" are displayed (if possible) in the recipient's email client at their respective position within the messages. Parts marked as "attachment" are typically displayed as a link or button that the user must click on or otherwise manipulate in order to open, save, or view. Keep in mind that the attachment/inline disposition is only a suggestion and the behavior of email clients may vary with respect to the disposition. For content provided by file, the default disposition is "attachment". Otherwise, the default for non-text parts is "inline". The attachmentp keyword argument can be used to override the default. Note that text parts will never be marked "inline".
name is a string specifying the name of an attachment. For attachments provided using the file keyword argument, the name defaults to the basename of the pathname associated with the file. To override the default, or to provide information when it cannot be automatically deduced, use this keyword argument.
headers is an alist specifying additional headers that should be included with the part. This is most useful for specifying the standard email headers in the top level part (but see also send-letter for a simpler way to do this). The car of each entry should be a string naming the header. The cdr should be a string containing the contents of the header. For example: '(("Subject" . "This is a MIME-compliant message") ("Date" . "Mon, 9 Jan 2006 13:58:22 -0800")).
id is a string specifying the id for this part. This data will be used to construct the Content-Id header of the part.
description is a string specifying the description for this part. This data will be used to construct the Content-Description header of the part.
The charset keyword argument is only used if the content-type is a text type (i.e., a content type of the form text/
parameters is an alist specifying additional parameters that should be included in the Content-Type header for the part. The car of each entry should be a string naming the header. The cdr should be a string containing the contents of the header. For example: '(("format" . "flowed")).
See MIME support in imap.html for more information. That section contains examples.
Function, net.post-office package
Arguments: host &key user password port timeout
This function creates a connection to the pop server on machine host and logs in as user with password password. The port argument defaults to 110, which is the port on which the pop server normally listens. The timeout argument defaults to 30 (seconds) and this value is used to limit the amount of time this pop interface code will wait for a response from the server before giving up. In certain circumstances the server may get so busy that you see timeout errors signaled in this code. In that case you should specify a larger timeout when connecting.
See below for how to specify the host argument.
The value returned by this function is a mailbox object (such as is returned by make-imap-connection). You can call mailbox-message-count on the mailbox object to determine how many letters are currently stored in the mailbox.
The host argument can serve several functions as well as just specifying the host, which it does in all cases. It can also specify a port number. And it can specify SSL and STARTTLS details. We discuss each use in turn.
The value can be a string naming a machine, or an IP address (in dotted form, as an integer for IPv4 addresses, or an IPv6 address structure).
By default, this function makes a connection to port 110 on host.
If you need to connect to a port other than the default (port 110), you can specify the host argument in one of the following two ways to specify the alternate port number (and, as described below, an alternate port can be specified along with SSL and STARTTLS information):
As a cons: if host is specified as a cons, the car should be the name or IP address of the host and the cdr should be the alternate port number. e.g. you could specify '("smtp.example.com" . 99) and port 99 will be used.
As a colon-separate string: the text before the colon specifies the hostname or IP address of the host and the text after the colon specifies the alternate port number. e.g. "smtp.example.com:99". Note that this form is not suitable if the host is specified as an IPv6 dotted address (because the dotted address uses colons as separators).
The most general form of the mail-server argument is a list of the form:
(server-name &key (port 110) (ssl nil) (starttls nil) ...ssl-client-keywords...)where
server-name is as described above for specifying the server only (i.e. a string or an IP address).
port allows for another way to specify the port to connect to. The default port for tcp connections is 110. When ssl is non-nil, the default port is 995.
If ssl is non-nil, make-ssl-client-stream will be called after establishing a connection to the smtp server. All ssl-client-keywords are passed to make-ssl-client-stream as well.
If starttls is non-nil, it allows for negotiation of a secure connection (TLSv1) if the server supports it. If the server supports both auth and starttls, starttls will be negotiated before attempting authentication.
...ssl-client-keywords...: all keyword args to make-ssl-client-stream are accepted. e.g. :method :ciphers, certificate related args, etc. They are only used if ssl is non-nil.
No error is signalled if both ssl and starttls are non-nil. The SSL connection is established before any starttls negotiation would begin.
See also with-pop-connection. See imap.html for more information.
Generic Function, net.post-office package
Arguments: mime-part-object
Accesses the slot holding the string that will be used as the boundary for multipart parts. This is typically only used for mime-part-parsed objects which are not yet supported. The details of this accessor may change when support for that is added.
See MIME support in imap.html for more information.
Function, net.post-office package
Arguments: thing
Returns true if thing is a mime-part-constructed object (such as returned by make-mime-part).
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: mime-part-object
Accesses the slot holding the description of the part, as specified by the description argument to make-mime-part or as defaulted to (the default is nil). This is typically only used for mime-part-parsed objects which are not yet supported. The details of this accessor may change when support for that is added.
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: mime-part-object
Accesses the slot holding a string specifying the transfer encoding that will be used to encode the body of the part. This is typically only used for mime-part-parsed objects which are not yet supported. The details of this accessor may change when support for that is added.
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: mime-part-object
Accesses the slot holding a list of conses (i.e., an alist) which specify additional headers to be included in the MIME message. The car and the cdr of the cons should both be strings. The car is the name of the header and the cdr is the value. It is permissible to have multiple headers of the same name (however, depending on the header in question, you may end up constructing a non-compliant email message).
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: mime-part-object
Accesses the slot holding the id of the part, as specified by the id argument to make-mime-part or as defaulted to (the default is nil). This is typically only used for mime-part-parsed objects which are not yet supported. The details of this accessor may change when support for that is added.
See MIME support in imap.html for more information.
Function, net.post-office package
Arguments: thing
Returns true if thing is a mime-part object.
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: mime-part-object
Accesses the slot holding a list of conses (i.e, an alist) which specify additional parameters to be included in the Content-Type MIME header. The car and the cdr of the cons should both be strings. The car is the name of the parameter and the cdr is the value.
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: mime-part-object
This mime-part accessor returns the list of parts when mime-part-object is a multipart part. The value has no meaning when mime-part-object is not a multipart part.
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: mime-part-object
Accesses the slot holding a string specifying the MIME subtype of the part. For example "html", "plain", "mixed", "jpeg". This is typically only used for mime-part-parsed objects which are not yet supported. The details of this accessor may change when support for that is added.
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: mime-part-object
Accesses the slot holding a string specifying the MIME type of the part. For example "text", "multipart", "image", etc. This is typically only used for mime-part-parsed objects which are not yet supported. The details of this accessor may change when support for that is added.
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: part &key stream
This function causes the part to be rendered to the specified stream (default *terminal-io*). The side effects of this method are that the files associated with the part and subparts will be read. If the files were specified as streams (rather than filenames), the streams will be read until EOF, but they will not be closed and their file positions will not be reverted.
See MIME support in imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox
This function does nothing but remind the imap or pop server that this client is still active, thus resetting the timers used in the server that will automatically shut down this connection after a period of inactivity. Like all other commands if messages have been added to the currently selected mailbox, the server will return the new message count as a response to the noop command, and this can be checked using mailbox-message-count.
For a pop server, a stat command is sent by noop (rather than an actual noop command), so that, after this command is completed the mailbox-message-count will contain the current count of messages in the mailbox.
See imap.html for more information.
Function, net.post-office package
Arguments: text
text is a string that is the first part of a mail message, including at least all of the headers lines and the blank line following the headers. Given this partial text of a mail message, this function returns two values.
The first returned value is an assoc list of (header . content) items. Both the header and content are strings. Note that header names will most likely be mixed case (but this is not a requirement) so you'll want to use :test #'equalp when searching for a particular header with assoc.
The second returned value is a string that is everything after the headers (which is often referred to as the body of the message).
See imap.html for more information.
Function, net.post-office package
Arguments:
The symbol po-condition names an internal (not intended for use by programmers) operator in the Allegro CL net.post-office utility. However, since the symbol po-condition also names the class po-condition, the operator name is exported, making it incorrectly appear to be available for use.
Generic Function, net.post-office package
Arguments: po-condition
Accesses the identifier slot of a po-condition. The identifier is a keyword indicating the problem that caused the condition to be signaled. The description of po-condition includes a list of identifiers.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: po-condition
Accesses the server-string slot of a po-condition.
See imap.html for more information.
Function, net.post-office package
Arguments:
The symbol po-error names an internal (not intended for use by programmers) operator in the Allegro CL net.post-office utility. However, since the symbol po-error also names the class po-error, the operator name is exported, making it incorrectly appear to be available for use.
Generic Function, net.post-office package
Arguments: mailbox old-name new-name
This function changes the name of mailbox location in mailbox named by old-name to new-name. It's an error if new-name already exists. There's a special behavior if old-name is "inbox". In this case all of the messages in "inbox" are moved to new-name mailbox location, but the "inbox" mailbox location continues to exist. Note: not all imap servers support this special behavior of renaming "inbox".
See imap.html for more information.
Generic Function, net.post-office package
Arguments: pop-mailbox
This generic function is only implemented for pop mailboxes.
It sends the RSET command to the mailbox. That command removes deletion markers from any messages marked for deletion and removes the has been read indication from any messages first read during this connection to the pop server.
The return value is what the pop server returns from this command. This is typically just diagnostic information and can be ignored.
See imap.html for more information.
Function, net.post-office package
Arguments: mailbox search-expression &key uid
This function returns a list of messages in the mailbox that satisfy the search-expression. If uid is true then unique ids will be returned instead of message sequence numbers. See Searching for messages in imap.html for details on the search-expression.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: mailbox name
This function makes the mailbox location named by the string name be the current mailbox location and store statistics about that mailbox location in the mailbox object specified by mailbox, where they can be retrieved by accessors.
The selected mailbox is the source for all message manipulation functions.
Function, net.post-office package
Arguments: mail-server from to message &key subject reply-to cc bcc headers login password attachments
This function requests that a SMTP server send a message. The return value of this function is undefined. If this function returns rather than signaling an error, then it has "succeeded", where "success" means the SMTP server claimed that it received the message.
mail-server specifies the mail server and also additional information. It can specify the port number, details of an SSL connection, and whether to initiate STARTTLS negotiations. The value of the argument can be a string or an IP address (to specify just a server or a server and a port number), a cons (to specify a server and a port number) or a list (to provide value for all options). See below for details.
The mail-server is contacted and asked to send a message (a string) from the email address specified by from to the email address or list of addresses specified by to. The email addresses must be of the form "foo" or "foo@bar.com". You can not use addresses like "Joe foo@bar.com" or "(Joe) foo@bar.com".
message can be a string or a stream or a mime-part-constructed (see MIME support in imap.html). If it is a stream, the stream is read until an EOF is reached, but the stream is not closed nor is the file pointer reset.
A mail header is built and prepended to the message before it is sent. The mail header includes a From line and a To line and will optionally include a Subject and Reply-To line if those are given (as values of the subject and reply-to keyword arguments) in the call to send-letter. The value of the headers keyword argument should be a string or list of strings (or nil). These are raw header lines added to the header sent out with the letter.
cc and bcc can be either a string or a list of strings naming recipients. All cc's and bcc's are sent the message but the bcc's are not included in the header.
attachments, if non-nil, should be a list of filenames or streams (or a combination). Here is an example using attachments:
(send-letter "localhost" "from@franz.com" "user1"
"Here is the image you requested"
:attachments
"home/user1/src/sample/OTHER/jupiter.jpg")The text of the message should be lines separated by #\newline's. The smtp interface will automatically insert the necessary #\returns's when it transmits the message to the mail server.
The login and user keyword arguments can be used if the smtp server (specified by the mail-server argument) requires authentication.
The mail-server argument serves several functions. It specifies the mail server or a program that does delivery of the message. It can also specify a port number. And it can specify SSL and STARTTLS details. We discuss each use in turn.
The value can be a string naming a machine, or an IP address (in dotted form, as an integer for IPv4 addresses, or an IPv6 address structure).
By default, this function makes a connection to port 25 on mail-server.
If you need to connect to a port other than the default (port 25), you can specify the mail-server argument in one of the following two ways to specify the alternate port number (and, as described below, an alternate port can be specified along with SSL and STARTTLS information):
As a cons: if mail-server is specified as a cons, the car should be the name or IP address of the mail server (i.e. a value as described above for mail-server) and the cdr should be the alternate port number. e.g. you could specify '("smtp.example.com" . 99) and port 99 will be used.
As a colon-separate string: the text before the colon specifies the hostname or IP address of the mail server (i.e. a value as described above for mail-server) and the text after the colon specifies the alternate port number. e.g. "smtp.example.com:99". Note that this form is not suitable if the mail server is specified as an IPv6 dotted address (because the dotted address uses colons as separators).
The most general form of the mail-server argument (when you are not using the :program option described below) is a list of the form:
(server-name &key (port 25) (ssl nil) (starttls nil) ...ssl-client-keywords...)where
server-name is as described above for specifying the server only (i.e. a string or an IP address).
port allows for another way to specify the port to connect to. The default port for tcp connections is 25. When ssl is non-nil, the default port is 465.
If ssl is non-nil, make-ssl-client-stream will be called after establishing a connection to the smtp server. All ssl-client-keywords are passed to make-ssl-client-stream as well.
If starttls is non-nil, it allows for negotiation of a secure connection (TLSv1) if the server supports it. If the server supports both auth and starttls, starttls will be negotiated before attempting authentication.
...ssl-client-keywords...: all keyword args to make-ssl-client-stream are accepted. e.g. :method :ciphers, certificate related args, etc. They are only used if ssl is non-nil.
No error is signalled if both ssl and starttls are non-nil. The SSL connection is established before any starttls negotiation would begin.
If the mail-server argument is a cons of the form:
(:program . command-string)or
(:program . list-of-program-name-and-args-all-strings) ;; UNIX onlyHere are examples:
(:program . "/usr/sbin/sendmail -t")
(:program . ("/usr/sbin/sendmail" "-odq" "-t"))Using the first template, where the command-string names the program and possibly arguments, the system invokes the program with the arguments, "/usr/sbin/sendmail -t" in the example, and pipes the message, constructed from the other arguments to send-letter to it.
The second form will invoke run-shell-command with a first argument (vector command command arg1 arg2 ...), thus
(vector "/usr/sbin/sendmail" "/usr/sbin/sendmail" "-odq" "-t")from the second example. This allows the program to be executed without an intermediate shell. That type of call to run-shell-command is not supported on Windows.
See imap.html for more information.
Function, net.post-office package
Arguments: mail-server from to &rest message
This function requests that a SMTP server send a message. The return value of this function is undefined. If this function returns rather than signaling an error, then it has "succeeded", where "success" means the SMTP server claimed that it received the message.
mail-server specifies the mail server and also additional information. It can specify the port number, details of an SSL connection, and whether to initiate STARTTLS negotiations. The value of the argument can be a string or an IP address (to specify just a server or a server and a port number), a cons (to specify a server and a port number) or a list (to provide value for all options). See below for details.
If the server specified by mail-server requires authentication, you should use send-smtp-auth, which works just like this function but has additional required arguments login and password.
The mail-server is contacted and asked to send a message (a string) from the email address specified by from to the email address or list of addresses specified by to. The email addresses must be of the form "foo" or "foo@bar.com". You can not use addresses like "Joe foo@bar.com" or "(Joe) foo@bar.com".
The message sent is a concatenation of all of the message arguments (there can be as many as you like). messages should be strings or streams in any combination. message cannot be a mime-part-constructed object, though see MIME messages below.) When a message is a stream, note the stream is read until an EOF is reached, but the stream is not closed nor is the file pointer reset.
A header is not prepended to the message. This means that the application program can build its own header if it wants to include in that header more than send-letter supports (e.g. a Mime encoded attachment). If no header is provided then some mail servers (e.g. sendmail) will notice this fact and will automatically create a header.
The text of the message should be lines separated by #\newline's. The smtp interface will automatically insert the necessary #\returns's when it transmits the message to the mail server.
As said above, message cannot be a mime-part-constructed object (see MIME support in imap.html) but you can do something like this:
(setf p1 (make-mime-part
:text "This is a test message"
:headers '(("From" . "Test User <joe@example.com>")
("To" . "Recipient <jimmy@yahoo.com>")
("Subject" . "This is a test email"))))
(with-mime-part-constructed-stream (s p1)
(send-smtp mail-server "joe@example.com" "jimmy@yahoo.com" s))The mail-server argument serves several functions. In all cases, it specifies the mail server. It can also specify a port number. And it can specify SSL and STARTTLS details. We discuss each use in turn.
The value can be a string naming a machine, or an IP address (in dotted form, as an integer for IPv4 addresses, or an IPv6 address structure).
By default, this function makes a connection to port 25 on mail-server.
If you need to connect to a port other than the default (port 25), you can specify the mail-server argument in one of the following two ways to specify the alternate port number (and, as described below, an alternate port can be specified along with SSL and STARTTLS information):
As a cons: if mail-server is specified as a cons, the car should be the name or IP address of the mail server (i.e. a value as described above for mail-server) and the cdr should be the alternate port number. e.g. you could specify '("smtp.example.com" . 99) and port 99 will be used.
As a colon-separate string: the text before the colon specifies the hostname or IP address of the mail server (i.e. a value as described above for mail-server) and the text after the colon specifies the alternate port number. e.g. "smtp.example.com:99". Note that this form is not suitable if the mail server is specified as an IPv6 dotted address (because the dotted address uses colons as separators).
The most general form of the mail-server argument is a list of the form:
(server-name &key (port 25) (ssl nil) (starttls nil) ...ssl-client-keywords...)where
server-name is as described above for specifying the server only (i.e. a string or an IP address).
port allows for another way to specify the port to connect to. The default port for tcp connections is 25. When ssl is non-nil, the default port is 465.
If ssl is non-nil, make-ssl-client-stream will be called after establishing a connection to the smtp server. All ssl-client-keywords are passed to make-ssl-client-stream as well.
If starttls is non-nil, it allows for negotiation of a secure connection (TLSv1) if the server supports it. If the server supports both auth and starttls, starttls will be negotiated before attempting authentication.
...ssl-client-keywords...: all keyword args to make-ssl-client-stream are accepted. e.g. :method :ciphers, certificate related args, etc. They are only used if ssl is non-nil.
No error is signalled if both ssl and starttls are non-nil. The SSL connection is established before any starttls negotiation would begin.
(use-package :net.post-office)
(defparameter *smtp-host* "localhost")
(defparameter *smtp-user* "someuser")
(defparameter *smtp-password* "somepassword")
;; ssl with authentication
(let ((part (make-mime-part
:text "This is a test message sent via Secure smtp server with authentication."
:headers '(("From" . "Test User <joe@example.com>")
("To" . "Recipient <jimmy@yahoo.com>")
("Subject" . "This is a test email")))))
(with-mime-part-constructed-stream (s part)
(send-smtp-auth (list *smtp-host* :ssl t :method :sslv3+)
*smtp-user*
"jimmy@yahoo.com"
*smtp-user* *smtp-password*
s)))
;; with starttls negotiation
(let ((part (make-mime-part
:text "This is a test message sent possibly via a TLSv1 encrypted channel."
:headers '(("From" . "Test User <joe@example.com>")
("To" . "Recipient <jimmy@yahoo.com>")
("Subject" . "This is a test email")))))
(with-mime-part-constructed-stream (s part)
(send-smtp (list *smtp-host* :starttls t)
*smtp-user*
"jimmy@yahoo.com"
s)))See imap.html for more information.
Function, net.post-office package
Arguments: mail-server from to login password &rest message
This function is like send-smtp except it has two additional required arguments: login and password (whose values should be strings). This function can be used in place of send-smtp when the server (specified by the mail-server argument) requires authentication. See send-smtp for further details. See the description of send-smtp for details of the other arguments.
Like send-smtp, the return value of this function is undefined. If the function returns rather than signaling an error, then it has "succeeded", where "success" means the SMTP server claimed that it received the message.
See imap.html for more information.
Function, net.post-office package
Arguments: email-address
For reasons that are included in the discussion below, use of this function is deprecated. (The reasons include dependence on the VRFY feature which most mail servers no longer support, and the inadequate choice of server on which to test the address.)
This function attempts to determine whether email-address could be a valid email address on the machine it names. email-address should be a string like "user@machine.com". test-email-address contacts the mail server and uses the VRFY command from smtp and returns t if the address is verified. The mail server contacted is the machine to which the domain part of the email address resolves, or localhost if there is no domain part.
Note that most mail servers don't implement VRFY and test-email-address also returns t if VRFY doesn't work.
test-email-address returns nil if VRFY indicates the address is bad or if the machine cannot be contacted (which might be a transient problem, of course).
See imap.html for more information.
Generic Function, net.post-office package
Arguments: pb message lines
pb must be a pop mailbox. message is a message number (an integer). lines is a count of the number of lines (an integer). top-lines returns the header and the lines top lines of the message. To just retrieve the headers, specify lines to be zero. See the function make-envelope-from-text for a means of reading the information in the header.
See imap.html for more information.
Generic Function, net.post-office package
Arguments: pb &optional message
pb must be a pop mailbox. message must be a message number (an integer) or nil. If message is a message number, this function returns the unique id of that message. If message is nil or unspecified, this function returns a list of lists of the form (message unique-id) for all messages not marked as deleted.
See imap.html for more information.
Macro, net.post-office package
Arguments: (mailbox &rest args) &body body
with-fetch-letter-sequence prepares for retrieval of a letter in a memory efficient manner. It is useful in cases where it is inefficient or impossible to store a letter in memory as a string. This macro is implemented for pop mailboxes only.
args are arguments suitable for a call to fetch-letter.
Within body, fetch-letter-sequence calls may be made to retrieve the first and subsequent chunks of text from the desired letter.
with-fetch-letter-sequence calls cannot be nested.
See also fetch-letter-sequence and end-of-letter-p.
See imap.html for more information.
Macro, net.post-office package
Arguments: (mb &rest options) &body body
with-imap-connection applies make-imap-connection to options and then evaluates body with mb bound to the resulting mailbox object.
When control leaves the body, either normally or abnormally (such as by use of throw), the mailbox connection is automatically closed (via close-connection).
See imap.html for more information.
Macro, net.post-office package
Arguments: (var part) &body body
The forms of body are evaluated (in an implicit progn) with the variable var bound to an input stream that supplies the rendering of the part (as performed by mime-part-writer).
See MIME support in imap.html for more information.
Macro, net.post-office package
Arguments: (mb &rest options) &body body
with-pop-connection applies make-pop-connection to options and then evaluates body with mb bound to the resulting mailbox object.
When control leaves the body, either normally or abnormally (such as by use of throw), the mailbox connection is automatically closed (via close-connection).
See imap.html for more information.
Copyright (c) 2023, Franz Inc. Lafayette, CA., USA. All rights reserved.
|
Allegro CL version 11.0 | ||||||||