The cl-smtp Reference Manual

This is the cl-smtp Reference Manual, version 20191031.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 05:23:56 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 cl-smtp

Common Lisp smtp client.

Maintainer

Jan Idzikowski <>

Author

Jan Idzikowski <>

License

LLGPL

Version

20191031.1

Dependencies
  • alexandria (system).
  • usocket (system).
  • flexi-streams (system).
  • frugal-uuid/non-frugal (system).
  • cl-base64 (system).
  • cl+ssl (system).
Source

cl-smtp.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 cl-smtp/cl-smtp.asd

Source

cl-smtp.asd.

Parent Component

cl-smtp (system).

ASDF Systems

cl-smtp.


3.1.2 cl-smtp/package.lisp

Source

cl-smtp.asd.

Parent Component

cl-smtp (system).

Packages

cl-smtp.

Public Interface

*debug* (special variable).

Internals

print-debug (macro).


3.1.3 cl-smtp/attachments.lisp

Dependency

package.lisp (file).

Source

cl-smtp.asd.

Parent Component

cl-smtp (system).

Public Interface
Internals

3.1.4 cl-smtp/cl-smtp.lisp

Dependency

attachments.lisp (file).

Source

cl-smtp.asd.

Parent Component

cl-smtp (system).

Public Interface
Internals

3.1.5 cl-smtp/mime-types.lisp

Dependency

cl-smtp.lisp (file).

Source

cl-smtp.asd.

Parent Component

cl-smtp (system).

Internals

4 Packages

Packages are listed by definition order.


4.1 cl-smtp

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *debug*
Package

cl-smtp.

Source

package.lisp.

Special Variable: *x-mailer*

Default value for the X-Mailer header, inserted by default in all outgoing e-mails. Bind to a string to customize the header’s value. If NIL, no X-Mailer header is generated at all.

Package

cl-smtp.

Source

cl-smtp.lisp.


5.1.2 Macros

Macro: with-smtp-mail ((stream-var host envelope-sender to &key ssl port authentication local-hostname external-format) &body body)

Encapsulate a SMTP MAIl conversation. A connection to the SMTP server on HOST and PORT is established and a MAIL command is initiated with FROM being the mail sender and TO being the list of recipients. BODY is evaluated with STREAM-VAR being the stream connected to the remote SMTP server. BODY is expected to write the RFC2821 message (headers and body) to STREAM-VAR.

Package

cl-smtp.

Source

cl-smtp.lisp.


5.1.3 Ordinary functions

Function: make-attachment (data-pathname &key name mime-type)
Package

cl-smtp.

Source

attachments.lisp.

Function: rfc2045-q-encode-string (str &key external-format)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: rfc2231-encode-string (string &key external-format)
Package

cl-smtp.

Source

attachments.lisp.

Function: send-email (host from to subject message &key ssl port cc bcc reply-to extra-headers html-message display-name authentication attachments buffer-size envelope-sender external-format local-hostname message-id)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: write-rfc5322-message (stream from to subject message &key cc reply-to extra-headers html-message display-name attachments buffer-size external-format message-id)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: write-rfc8822-message (stream from to subject message &key cc reply-to extra-headers html-message display-name attachments buffer-size external-format)

Deprecated function. Please change to write-rfc5322-message.

Package

cl-smtp.

Source

cl-smtp.lisp.


5.1.4 Generic functions

Generic Function: attachment-data-pathname (object)
Package

cl-smtp.

Methods
Method: attachment-data-pathname ((attachment string))
Source

attachments.lisp.

Method: attachment-data-pathname ((attachment pathname))
Source

attachments.lisp.

Reader Method: attachment-data-pathname ((attachment attachment))

automatically generated reader method

Source

attachments.lisp.

Target Slot

data-pathname.

Generic Writer: (setf attachment-data-pathname) (object)
Package

cl-smtp.

Methods
Writer Method: (setf attachment-data-pathname) ((attachment attachment))

automatically generated writer method

Source

attachments.lisp.

Target Slot

data-pathname.

Generic Function: attachment-mime-type (object)
Package

cl-smtp.

Methods
Method: attachment-mime-type ((attachment string))
Source

attachments.lisp.

Method: attachment-mime-type ((attachment pathname))
Source

attachments.lisp.

Reader Method: attachment-mime-type ((attachment attachment))

automatically generated reader method

Source

attachments.lisp.

Target Slot

mime-type.

Generic Writer: (setf attachment-mime-type) (object)
Package

cl-smtp.

Methods
Writer Method: (setf attachment-mime-type) ((attachment attachment))

automatically generated writer method

Source

attachments.lisp.

Target Slot

mime-type.

Generic Function: attachment-name (object)
Package

cl-smtp.

Methods
Method: attachment-name ((attachment string))
Source

attachments.lisp.

Method: attachment-name ((attachment pathname))
Source

attachments.lisp.

Reader Method: attachment-name ((attachment attachment))

automatically generated reader method

Source

attachments.lisp.

Target Slot

name.

Generic Writer: (setf attachment-name) (object)
Package

cl-smtp.

Methods
Writer Method: (setf attachment-name) ((attachment attachment))

automatically generated writer method

Source

attachments.lisp.

Target Slot

name.


5.1.5 Conditions

Condition: no-supported-authentication-method
Package

cl-smtp.

Source

cl-smtp.lisp.

Direct superclasses

smtp-error.

Direct methods

features.

Direct slots
Slot: features
Initargs

:features

Readers

features.

Writers

This slot is read-only.

Condition: rcpt-failed
Package

cl-smtp.

Source

cl-smtp.lisp.

Direct superclasses

smtp-protocol-error.

Direct methods

recipient.

Direct slots
Slot: recipient
Initargs

:recipient

Readers

recipient.

Writers

This slot is read-only.

Condition: smtp-error
Package

cl-smtp.

Source

cl-smtp.lisp.

Direct superclasses

error.

Direct subclasses
Condition: smtp-protocol-error
Package

cl-smtp.

Source

cl-smtp.lisp.

Direct superclasses

smtp-error.

Direct subclasses

rcpt-failed.

Direct methods
Direct slots
Slot: command
Initargs

:command

Readers

command.

Writers

This slot is read-only.

Slot: expected-response-code
Initargs

:expected-response-code

Readers

expected-response-code.

Writers

This slot is read-only.

Slot: response-code
Initargs

:response-code

Readers

response-code.

Writers

This slot is read-only.

Slot: response-message
Initargs

:response-message

Readers

response-message.

Writers

This slot is read-only.


5.1.6 Classes

Class: attachment
Package

cl-smtp.

Source

attachments.lisp.

Direct methods
Direct slots
Slot: name
Initargs

:name

Readers

attachment-name.

Writers

(setf attachment-name).

Slot: data-pathname
Initargs

:data-pathname

Readers

attachment-data-pathname.

Writers

(setf attachment-data-pathname).

Slot: mime-type
Initargs

:mime-type

Readers

attachment-mime-type.

Writers

(setf attachment-mime-type).


5.2 Internals


5.2.1 Constants

Constant: +message-id-header-key+
Package

cl-smtp.

Source

cl-smtp.lisp.


5.2.2 Special variables

Special Variable: *boundary-chars*
Package

cl-smtp.

Source

attachments.lisp.

Special Variable: *message-id-generator*
Package

cl-smtp.

Source

cl-smtp.lisp.

Special Variable: *mime-type-descriptions*
Package

cl-smtp.

Source

mime-types.lisp.

Special Variable: *mime-types*
Package

cl-smtp.

Source

mime-types.lisp.

Special Variable: *return-newline*
Package

cl-smtp.

Source

cl-smtp.lisp.


5.2.3 Macros

Macro: print-debug (str)
Package

cl-smtp.

Source

package.lisp.


5.2.4 Ordinary functions

Function: base64-encode-file (file-in sock &key buffer-size wrap-at-column)

Encodes the file contents given by file-in, which can be of any form appropriate to with-open-file, and write the base-64 encoded version to sock, which is a socket.

Buffer-size is ignored

Wrap-at-column controls where the encode string is divided for line breaks,
it is always set to a multiple of 3.

Package

cl-smtp.

Source

attachments.lisp.

Function: check-arg (arg name)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: do-with-smtp-mail (host envelope-sender to thunk &key port authentication ssl local-hostname external-format)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: escape-rfc822-quoted-string (str)
Package

cl-smtp.

Source

attachments.lisp.

Function: extract-domain-from-email-address (address)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: finish-smtp-mail (stream)

Finish sending an email to the SMTP server connected to on STREAM. The server is expected to be inside of the DATA SMTP command. The connection is then terminated by sending a QUIT command.

Package

cl-smtp.

Source

cl-smtp.lisp.

Function: generate-email-message-id (domain-name)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: generate-email-message-id-random-part ()
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: generate-message-header (sock &key boundary content-type content-disposition content-transfer-encoding include-blank-line?)
Package

cl-smtp.

Source

attachments.lisp.

Function: generate-message-id-uuidv7@domain (sender-address)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: generate-multipart-header (sock boundary &key multipart-type)
Package

cl-smtp.

Source

attachments.lisp.

Function: get-email-date-string ()
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: get-timezone-from-integer (x)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: initiate-smtp-mail (stream envelope-sender to)

Initiate an SMTP MAIL command, sending a MAIL FROM command for the email address in FROM and RCPT commands for all receipients in TO, which is expected to be a list.

If any of the TO addresses is not accepted, a RCPT-FAILED condition is signalled. This condition may be handled by the caller in order to send the email anyway.

Package

cl-smtp.

Source

cl-smtp.lisp.

Function: lookup-mime-type (file-name &optional default)

Extract mime type based on file-extension

Package

cl-smtp.

Source

mime-types.lisp.

Function: make-random-boundary (&optional length boundary-chars)
Package

cl-smtp.

Source

attachments.lisp.

Function: mask-dot (str)

Replace all occurences of single line #. with #.#.

Package

cl-smtp.

Source

cl-smtp.lisp.

Function: mask-dot-stream (str stream)

Replace all occurences of single line #. with #.#.

Package

cl-smtp.

Source

cl-smtp.lisp.

Function: read-from-smtp (stream &optional lines)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: rfc2045-q-encode-string-to-stream (str stream &key external-format columns)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: send-attachment (sock attachment boundary buffer-size external-format)
Package

cl-smtp.

Source

attachments.lisp.

Function: send-attachment-header (sock boundary attachment external-format)
Package

cl-smtp.

Source

attachments.lisp.

Function: send-end-marker (sock boundary)
Package

cl-smtp.

Source

attachments.lisp.

Function: send-mail-headers (stream &key from to cc reply-to extra-headers display-name subject external-format message-id)

Send email headers according to the given arguments to the SMTP server connected to on STREAM. The server is expected to have previously accepted the DATA SMTP command.

Package

cl-smtp.

Source

cl-smtp.lisp.

Function: send-multipart-headers (stream &key attachment-boundary html-boundary)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: send-smtp (host from to subject message &key ssl port cc bcc reply-to extra-headers html-message display-name authentication attachments buffer-size local-hostname envelope-sender external-format message-id)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: smtp-authenticate (stream authentication features)

Authenticate to the SMTP server connected on STREAM.
AUTHENTICATION is a list of two or three elements. If the first element is a keyword, it specifies the desired authentication method (:PLAIN or :LOGIN), which is currently ignored. The actual method used is determined by looking at the advertised features of the SMTP server. The (other) two elements of the AUTHENTICATION list are the login username and password. FEATURES is the list of features announced by the SMTP server.

If the server does not announce any compatible authentication scheme, the NO-SUPPORTED-AUTHENTICATION-METHOD error is signalled.

Package

cl-smtp.

Source

cl-smtp.lisp.

Function: smtp-command (stream command expected-response-code &key condition-class condition-arguments)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: smtp-handshake (stream &key authentication ssl local-hostname)

Perform the initial SMTP handshake on STREAM. Returns the stream to use further down in the conversation, which may be different from the original stream if we switched to SSL.

Package

cl-smtp.

Source

cl-smtp.lisp.

Function: string-has-non-ascii (str)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: string-to-base64-string (str &key external-format columns)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: substitute-return-newline (str)

Replace all occurences of rn in STR with spaces

Package

cl-smtp.

Source

cl-smtp.lisp.

Function: write-blank-line (stream)
Package

cl-smtp.

Source

cl-smtp.lisp.

Function: write-to-smtp (stream command)
Package

cl-smtp.

Source

cl-smtp.lisp.


5.2.5 Generic functions

Generic Reader: command (condition)
Package

cl-smtp.

Methods
Reader Method: command ((condition smtp-protocol-error))
Source

cl-smtp.lisp.

Target Slot

command.

Generic Reader: expected-response-code (condition)
Package

cl-smtp.

Methods
Reader Method: expected-response-code ((condition smtp-protocol-error))
Source

cl-smtp.lisp.

Target Slot

expected-response-code.

Generic Reader: features (condition)
Package

cl-smtp.

Methods
Reader Method: features ((condition no-supported-authentication-method))
Source

cl-smtp.lisp.

Target Slot

features.

Generic Function: generate-message-id-header (generator sender-address)
Package

cl-smtp.

Source

cl-smtp.lisp.

Methods
Method: generate-message-id-header ((generator (eql :uuidv7)) sender-address)
Method: generate-message-id-header ((generator (eql :uuidv7@domain)) sender-address)
Method: generate-message-id-header ((generator null) sender-address)
Method: generate-message-id-header ((generator string) sender-address)
Generic Reader: recipient (condition)
Package

cl-smtp.

Methods
Reader Method: recipient ((condition rcpt-failed))
Source

cl-smtp.lisp.

Target Slot

recipient.

Generic Reader: response-code (condition)
Package

cl-smtp.

Methods
Reader Method: response-code ((condition smtp-protocol-error))
Source

cl-smtp.lisp.

Target Slot

response-code.

Generic Reader: response-message (condition)
Package

cl-smtp.

Methods
Reader Method: response-message ((condition smtp-protocol-error))
Source

cl-smtp.lisp.

Target Slot

response-message.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   B   C   D   E   F   G   I   L   M   P   R   S   W  
Index Entry  Section

(
(setf attachment-data-pathname): Public generic functions
(setf attachment-data-pathname): Public generic functions
(setf attachment-mime-type): Public generic functions
(setf attachment-mime-type): Public generic functions
(setf attachment-name): Public generic functions
(setf attachment-name): Public generic functions

A
attachment-data-pathname: Public generic functions
attachment-data-pathname: Public generic functions
attachment-data-pathname: Public generic functions
attachment-data-pathname: Public generic functions
attachment-mime-type: Public generic functions
attachment-mime-type: Public generic functions
attachment-mime-type: Public generic functions
attachment-mime-type: Public generic functions
attachment-name: Public generic functions
attachment-name: Public generic functions
attachment-name: Public generic functions
attachment-name: Public generic functions

B
base64-encode-file: Private ordinary functions

C
check-arg: Private ordinary functions
command: Private generic functions
command: Private generic functions

D
do-with-smtp-mail: Private ordinary functions

E
escape-rfc822-quoted-string: Private ordinary functions
expected-response-code: Private generic functions
expected-response-code: Private generic functions
extract-domain-from-email-address: Private ordinary functions

F
features: Private generic functions
features: Private generic functions
finish-smtp-mail: Private ordinary functions
Function, base64-encode-file: Private ordinary functions
Function, check-arg: Private ordinary functions
Function, do-with-smtp-mail: Private ordinary functions
Function, escape-rfc822-quoted-string: Private ordinary functions
Function, extract-domain-from-email-address: Private ordinary functions
Function, finish-smtp-mail: Private ordinary functions
Function, generate-email-message-id: Private ordinary functions
Function, generate-email-message-id-random-part: Private ordinary functions
Function, generate-message-header: Private ordinary functions
Function, generate-message-id-uuidv7@domain: Private ordinary functions
Function, generate-multipart-header: Private ordinary functions
Function, get-email-date-string: Private ordinary functions
Function, get-timezone-from-integer: Private ordinary functions
Function, initiate-smtp-mail: Private ordinary functions
Function, lookup-mime-type: Private ordinary functions
Function, make-attachment: Public ordinary functions
Function, make-random-boundary: Private ordinary functions
Function, mask-dot: Private ordinary functions
Function, mask-dot-stream: Private ordinary functions
Function, read-from-smtp: Private ordinary functions
Function, rfc2045-q-encode-string: Public ordinary functions
Function, rfc2045-q-encode-string-to-stream: Private ordinary functions
Function, rfc2231-encode-string: Public ordinary functions
Function, send-attachment: Private ordinary functions
Function, send-attachment-header: Private ordinary functions
Function, send-email: Public ordinary functions
Function, send-end-marker: Private ordinary functions
Function, send-mail-headers: Private ordinary functions
Function, send-multipart-headers: Private ordinary functions
Function, send-smtp: Private ordinary functions
Function, smtp-authenticate: Private ordinary functions
Function, smtp-command: Private ordinary functions
Function, smtp-handshake: Private ordinary functions
Function, string-has-non-ascii: Private ordinary functions
Function, string-to-base64-string: Private ordinary functions
Function, substitute-return-newline: Private ordinary functions
Function, write-blank-line: Private ordinary functions
Function, write-rfc5322-message: Public ordinary functions
Function, write-rfc8822-message: Public ordinary functions
Function, write-to-smtp: Private ordinary functions

G
generate-email-message-id: Private ordinary functions
generate-email-message-id-random-part: Private ordinary functions
generate-message-header: Private ordinary functions
generate-message-id-header: Private generic functions
generate-message-id-header: Private generic functions
generate-message-id-header: Private generic functions
generate-message-id-header: Private generic functions
generate-message-id-header: Private generic functions
generate-message-id-uuidv7@domain: Private ordinary functions
generate-multipart-header: Private ordinary functions
Generic Function, (setf attachment-data-pathname): Public generic functions
Generic Function, (setf attachment-mime-type): Public generic functions
Generic Function, (setf attachment-name): Public generic functions
Generic Function, attachment-data-pathname: Public generic functions
Generic Function, attachment-mime-type: Public generic functions
Generic Function, attachment-name: Public generic functions
Generic Function, command: Private generic functions
Generic Function, expected-response-code: Private generic functions
Generic Function, features: Private generic functions
Generic Function, generate-message-id-header: Private generic functions
Generic Function, recipient: Private generic functions
Generic Function, response-code: Private generic functions
Generic Function, response-message: Private generic functions
get-email-date-string: Private ordinary functions
get-timezone-from-integer: Private ordinary functions

I
initiate-smtp-mail: Private ordinary functions

L
lookup-mime-type: Private ordinary functions

M
Macro, print-debug: Private macros
Macro, with-smtp-mail: Public macros
make-attachment: Public ordinary functions
make-random-boundary: Private ordinary functions
mask-dot: Private ordinary functions
mask-dot-stream: Private ordinary functions
Method, (setf attachment-data-pathname): Public generic functions
Method, (setf attachment-mime-type): Public generic functions
Method, (setf attachment-name): Public generic functions
Method, attachment-data-pathname: Public generic functions
Method, attachment-data-pathname: Public generic functions
Method, attachment-data-pathname: Public generic functions
Method, attachment-mime-type: Public generic functions
Method, attachment-mime-type: Public generic functions
Method, attachment-mime-type: Public generic functions
Method, attachment-name: Public generic functions
Method, attachment-name: Public generic functions
Method, attachment-name: Public generic functions
Method, command: Private generic functions
Method, expected-response-code: Private generic functions
Method, features: Private generic functions
Method, generate-message-id-header: Private generic functions
Method, generate-message-id-header: Private generic functions
Method, generate-message-id-header: Private generic functions
Method, generate-message-id-header: Private generic functions
Method, recipient: Private generic functions
Method, response-code: Private generic functions
Method, response-message: Private generic functions

P
print-debug: Private macros

R
read-from-smtp: Private ordinary functions
recipient: Private generic functions
recipient: Private generic functions
response-code: Private generic functions
response-code: Private generic functions
response-message: Private generic functions
response-message: Private generic functions
rfc2045-q-encode-string: Public ordinary functions
rfc2045-q-encode-string-to-stream: Private ordinary functions
rfc2231-encode-string: Public ordinary functions

S
send-attachment: Private ordinary functions
send-attachment-header: Private ordinary functions
send-email: Public ordinary functions
send-end-marker: Private ordinary functions
send-mail-headers: Private ordinary functions
send-multipart-headers: Private ordinary functions
send-smtp: Private ordinary functions
smtp-authenticate: Private ordinary functions
smtp-command: Private ordinary functions
smtp-handshake: Private ordinary functions
string-has-non-ascii: Private ordinary functions
string-to-base64-string: Private ordinary functions
substitute-return-newline: Private ordinary functions

W
with-smtp-mail: Public macros
write-blank-line: Private ordinary functions
write-rfc5322-message: Public ordinary functions
write-rfc8822-message: Public ordinary functions
write-to-smtp: Private ordinary functions


A.3 Variables

Jump to:   *   +  
C   D   E   F   M   N   R   S  
Index Entry  Section

*
*boundary-chars*: Private special variables
*debug*: Public special variables
*message-id-generator*: Private special variables
*mime-type-descriptions*: Private special variables
*mime-types*: Private special variables
*return-newline*: Private special variables
*x-mailer*: Public special variables

+
+message-id-header-key+: Private constants

C
command: Public conditions
Constant, +message-id-header-key+: Private constants

D
data-pathname: Public classes

E
expected-response-code: Public conditions

F
features: Public conditions

M
mime-type: Public classes

N
name: Public classes

R
recipient: Public conditions
response-code: Public conditions
response-message: Public conditions

S
Slot, command: Public conditions
Slot, data-pathname: Public classes
Slot, expected-response-code: Public conditions
Slot, features: Public conditions
Slot, mime-type: Public classes
Slot, name: Public classes
Slot, recipient: Public conditions
Slot, response-code: Public conditions
Slot, response-message: Public conditions
Special Variable, *boundary-chars*: Private special variables
Special Variable, *debug*: Public special variables
Special Variable, *message-id-generator*: Private special variables
Special Variable, *mime-type-descriptions*: Private special variables
Special Variable, *mime-types*: Private special variables
Special Variable, *return-newline*: Private special variables
Special Variable, *x-mailer*: Public special variables