make-imap-connection

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

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.

Using host to specify the server only

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.

Specifing a server and a port number

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):

1. 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.
2. 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).

Specifying the server, the port, and SSL and STARTTLS information

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.
• ...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-imap-connection. See imap.htm for additional information.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.