The cl-smtp Reference Manual

Table of Contents

The cl-smtp Reference Manual

This is the cl-smtp Reference Manual, version 20191031.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:10:14 2021 GMT+0.

1 Introduction

CL-SMTP is a simple lisp smtp client. 
It works in ACL, SBCL, CMUCL, OPENMCL, LISPWORKS, CLISP and ECL.

new with support for send attachments, thanks Brian Sorg for the implementation

with authentication support for PLAIN and LOGIN authentication method

and ssl support with cl+ssl package

used cl-base64 and usocket packages (cl-base64 isn't a requirement on ACL)

See INSTALL for prerequisites and build details.

To use cl-smtp:

(asdf:operate 'asdf:load-op 'cl-smtp)

------------------------------------------------

(cl-smtp:send-email host from to subject message
                    &key (port 25) cc bcc reply-to extra-headers html-message 
                    authentication attachments (buffer-size 256) ssl)
Send email.

Returns nil or error with message

 arguments:
  - host (String)                  : hostname or ip-address of the smtpserver
  - from (String)                  : email address 
  - to (String or List of Strings) : email address 
  - subject (String)               : subject text
  - message (String)               : message body
 keywords:
  - cc (String or List of Strings) : email adress carbon copy
  - bcc (String or List of Strings): email adress blind carbon copy
  - reply-to (String)              : email adress
  - display-name (String)          : displayname of the sender
  - extra-headers (List)           : extra headers as alist
  - html-message (String)          : message body formatted with HTML tags
  - authentication (List)          : list with 2 or elements
                                     ([:method] "username" "password")
                                     method is a keyword :plain or :login
                                     If the method is not specified, the
                                     proper method is determined automatically.
  - attachments (Attachment Instance or String or Pathname: attachments to send
                List of Attachment/String/Pathnames)
  - buffer-size (Number default 256): is no longer used, will remove in the future
  - ssl (or t :starttls :tls)       : if t or :STARTTLS: use the STARTTLS functionality
                                      if :TLS: use TLS directly
  - external-format                 : symbol, default :utf-8
  - envelope-sender                 : email adress, 
                                      if not set then envelope-sender = from

------------------------------------------------

(cl-smtp:rfc2045-q-encode-string str &key (external-format :utf8))

Decodes a string to an quoted-printable string.

Returns quoted-printable string

 arguments:
  - str                             : the string to encode
 keywords:
  - external-format                 : symbol, default :utf-8

------------------------------------------------

(cl-smtp:rfc2231-encode-string str &key (external-format :utf8))

Decodes a string to an rfc2231 encode string.

Returns  rfc2231 encode string

 arguments:
  - str                             : the string to encode
 keywords:
  - external-format                 : symbol, default :utf-8

------------------------------------------------

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

Writes a rfc8822 compatible email to the stream.

For arguments see the cl-smtp:send-email documentation.

------------------------------------------------
CLASS
cl-smtp:attachment 

 - accessor: attachment-name          : string 
 - accessor: attachment-data-pathname : pathname
 - accessor: attachment-mime-type     : string (mime-type)

It is now possible to send a file under a different name.
See cl-smtp:make-attachment.
------------------------------------------------

(cl-smtp:make-attachment data-pathname
			 &key (name (file-namestring data-pathname))
			      (mime-type (lookup-mime-type name)))

Create a instance of cl-smtp:attachment.

Returns cl-smtp:attachment

 arguments:
  - data-pathname                     : pathname
 keywords:
  - name                              : string, 
                                        default (file-namestring data-pathname)
  - mime-type                         : string,
                                        default (lookup-mime-type name)
------------------------------------------------

For debug output set the parameter *debug* to t (default nil)
(setf cl-smtp::*debug* t)

CL-SMTP set automatically the Date header and the X-Mailer header.
X-Mailer: cl-smtp ((lisp-implementation-type) (lisp-implementation-version))

You can change this with setting the parameter *x-mailer*
(setf cl-smtp::*x-mailer* "my x-mailer string)

If you find bugs or want to send patches for enhancements, by email to
Jan Idzikowski 

2 Systems

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

2.1 cl-smtp

Maintainer

Jan Idzikowski <jidzikowski@common-lisp.net>

Author

Jan Idzikowski <jidzikowski@common-lisp.net>

License

LLGPL

Description

Common Lisp smtp client.

Version

20191031.1

Dependencies

• usocket
• trivial-gray-streams
• flexi-streams
• cl-base64
• cl+ssl

Source

cl-smtp.asd (file)

Components

• package.lisp (file)
• attachments.lisp (file)
• cl-smtp.lisp (file)
• mime-types.lisp (file)

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.asd

Location

cl-smtp.asd

Systems

cl-smtp (system)

3.1.2 cl-smtp/package.lisp

Parent

cl-smtp (system)

Location

package.lisp

Packages

cl-smtp

Internal Definitions

• *debug* (special variable)
• print-debug (macro)

3.1.3 cl-smtp/attachments.lisp

Dependency

package.lisp (file)

Parent

cl-smtp (system)

Location

attachments.lisp

Exported Definitions

• attachment (class)
• attachment-data-pathname (method)
• attachment-data-pathname (method)
• attachment-data-pathname (method)
• (setf attachment-data-pathname) (method)
• attachment-mime-type (method)
• attachment-mime-type (method)
• attachment-mime-type (method)
• (setf attachment-mime-type) (method)
• attachment-name (method)
• attachment-name (method)
• attachment-name (method)
• (setf attachment-name) (method)
• make-attachment (function)
• rfc2231-encode-string (function)

Internal Definitions

• *boundary-chars* (special variable)
• base64-encode-file (function)
• escape-rfc822-quoted-string (function)
• generate-message-header (function)
• generate-multipart-header (function)
• make-random-boundary (function)
• send-attachment (function)
• send-attachment-header (function)
• send-end-marker (function)

3.1.4 cl-smtp/cl-smtp.lisp

Dependency

attachments.lisp (file)

Parent

cl-smtp (system)

Location

cl-smtp.lisp

Exported Definitions

• no-supported-authentication-method (condition)
• rcpt-failed (condition)
• rfc2045-q-encode-string (function)
• send-email (function)
• smtp-error (condition)
• smtp-protocol-error (condition)
• with-smtp-mail (macro)
• write-rfc8822-message (function)

Internal Definitions

• *return-newline* (special variable)
• *x-mailer* (special variable)
• check-arg (function)
• command (method)
• do-with-smtp-mail (function)
• expected-response-code (method)
• features (method)
• finish-smtp-mail (function)
• get-email-date-string (function)
• get-timezone-from-integer (function)
• initiate-smtp-mail (function)
• mask-dot (function)
• mask-dot-stream (function)
• read-from-smtp (function)
• recipient (method)
• response-code (method)
• response-message (method)
• rfc2045-q-encode-string-to-stream (function)
• send-mail-headers (function)
• send-multipart-headers (function)
• send-smtp (function)
• smtp-authenticate (function)
• smtp-command (function)
• smtp-handshake (function)
• string-has-non-ascii (function)
• string-to-base64-string (function)
• substitute-return-newline (function)
• write-blank-line (function)
• write-to-smtp (function)

3.1.5 cl-smtp/mime-types.lisp

Dependency

cl-smtp.lisp (file)

Parent

cl-smtp (system)

Location

mime-types.lisp

Internal Definitions

• *mime-type-descriptions* (special variable)
• *mime-types* (special variable)
• lookup-mime-type (function)

4 Packages

Packages are listed by definition order.

4.1 cl-smtp

Source

package.lisp (file)

Use List

• trivial-gray-streams
• flexi-streams
• common-lisp

Exported Definitions

• attachment (class)
• attachment-data-pathname (generic function)
• attachment-data-pathname (method)
• attachment-data-pathname (method)
• attachment-data-pathname (method)
• (setf attachment-data-pathname) (method)
• (setf attachment-data-pathname) (generic function)
• attachment-mime-type (generic function)
• attachment-mime-type (method)
• attachment-mime-type (method)
• attachment-mime-type (method)
• (setf attachment-mime-type) (method)
• (setf attachment-mime-type) (generic function)
• attachment-name (generic function)
• attachment-name (method)
• attachment-name (method)
• attachment-name (method)
• (setf attachment-name) (method)
• (setf attachment-name) (generic function)
• make-attachment (function)
• no-supported-authentication-method (condition)
• rcpt-failed (condition)
• rfc2045-q-encode-string (function)
• rfc2231-encode-string (function)
• send-email (function)
• smtp-error (condition)
• smtp-protocol-error (condition)
• with-smtp-mail (macro)
• write-rfc8822-message (function)

Internal Definitions

• *boundary-chars* (special variable)
• *debug* (special variable)
• *mime-type-descriptions* (special variable)
• *mime-types* (special variable)
• *return-newline* (special variable)
• *x-mailer* (special variable)
• base64-encode-file (function)
• check-arg (function)
• command (generic function)
• command (method)
• do-with-smtp-mail (function)
• escape-rfc822-quoted-string (function)
• expected-response-code (generic function)
• expected-response-code (method)
• features (generic function)
• features (method)
• finish-smtp-mail (function)
• generate-message-header (function)
• generate-multipart-header (function)
• get-email-date-string (function)
• get-timezone-from-integer (function)
• initiate-smtp-mail (function)
• lookup-mime-type (function)
• make-random-boundary (function)
• mask-dot (function)
• mask-dot-stream (function)
• print-debug (macro)
• read-from-smtp (function)
• recipient (generic function)
• recipient (method)
• response-code (generic function)
• response-code (method)
• response-message (generic function)
• response-message (method)
• rfc2045-q-encode-string-to-stream (function)
• send-attachment (function)
• send-attachment-header (function)
• send-end-marker (function)
• send-mail-headers (function)
• send-multipart-headers (function)
• send-smtp (function)
• smtp-authenticate (function)
• smtp-command (function)
• smtp-handshake (function)
• string-has-non-ascii (function)
• string-to-base64-string (function)
• substitute-return-newline (function)
• write-blank-line (function)
• write-to-smtp (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 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 (file)

5.1.2 Functions

Function: make-attachment DATA-PATHNAME &key NAME MIME-TYPE

Package

cl-smtp

Source

attachments.lisp (file)

Function: rfc2045-q-encode-string STR &key EXTERNAL-FORMAT

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: rfc2231-encode-string STRING &key EXTERNAL-FORMAT

Package

cl-smtp

Source

attachments.lisp (file)

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

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: write-rfc8822-message STREAM FROM TO SUBJECT MESSAGE &key CC REPLY-TO EXTRA-HEADERS HTML-MESSAGE DISPLAY-NAME ATTACHMENTS BUFFER-SIZE EXTERNAL-FORMAT

Package

cl-smtp

Source

cl-smtp.lisp (file)

5.1.3 Generic functions

Generic Function: attachment-data-pathname OBJECT

Generic Function: (setf attachment-data-pathname) NEW-VALUE OBJECT

Package

cl-smtp

Methods

Method: attachment-data-pathname (ATTACHMENT string)

Source

attachments.lisp (file)

Method: attachment-data-pathname (ATTACHMENT pathname)

Source

attachments.lisp (file)

Method: attachment-data-pathname (ATTACHMENT attachment)

automatically generated reader method

Source

attachments.lisp (file)

Method: (setf attachment-data-pathname) NEW-VALUE (ATTACHMENT attachment)

automatically generated writer method

Source

attachments.lisp (file)

Generic Function: attachment-mime-type OBJECT

Generic Function: (setf attachment-mime-type) NEW-VALUE OBJECT

Package

cl-smtp

Methods

Method: attachment-mime-type (ATTACHMENT string)

Source

attachments.lisp (file)

Method: attachment-mime-type (ATTACHMENT pathname)

Source

attachments.lisp (file)

Method: attachment-mime-type (ATTACHMENT attachment)

automatically generated reader method

Source

attachments.lisp (file)

Method: (setf attachment-mime-type) NEW-VALUE (ATTACHMENT attachment)

automatically generated writer method

Source

attachments.lisp (file)

Generic Function: attachment-name OBJECT

Generic Function: (setf attachment-name) NEW-VALUE OBJECT

Package

cl-smtp

Methods

Method: attachment-name (ATTACHMENT string)

Source

attachments.lisp (file)

Method: attachment-name (ATTACHMENT pathname)

Source

attachments.lisp (file)

Method: attachment-name (ATTACHMENT attachment)

automatically generated reader method

Source

attachments.lisp (file)

Method: (setf attachment-name) NEW-VALUE (ATTACHMENT attachment)

automatically generated writer method

Source

attachments.lisp (file)

5.1.4 Conditions

Condition: no-supported-authentication-method ()

Package

cl-smtp

Source

cl-smtp.lisp (file)

Direct superclasses

smtp-error (condition)

Direct methods

features (method)

Direct slots

Slot: features

Initargs

:features

Readers

features (generic function)

Condition: rcpt-failed ()

Package

cl-smtp

Source

cl-smtp.lisp (file)

Direct superclasses

smtp-protocol-error (condition)

Direct methods

recipient (method)

Direct slots

Slot: recipient

Initargs

:recipient

Readers

recipient (generic function)

Condition: smtp-error ()

Package

cl-smtp

Source

cl-smtp.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• smtp-protocol-error (condition)
• no-supported-authentication-method (condition)

Condition: smtp-protocol-error ()

Package

cl-smtp

Source

cl-smtp.lisp (file)

Direct superclasses

smtp-error (condition)

Direct subclasses

rcpt-failed (condition)

Direct methods

• response-message (method)
• response-code (method)
• expected-response-code (method)
• command (method)

Direct slots

Slot: command

Initargs

:command

Readers

command (generic function)

Slot: expected-response-code

Initargs

:expected-response-code

Readers

expected-response-code (generic function)

Slot: response-code

Initargs

:response-code

Readers

response-code (generic function)

Slot: response-message

Initargs

:response-message

Readers

response-message (generic function)

5.1.5 Classes

Class: attachment ()

Package

cl-smtp

Source

attachments.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• attachment-mime-type (method)
• attachment-mime-type (method)
• attachment-data-pathname (method)
• attachment-data-pathname (method)
• attachment-name (method)
• attachment-name (method)

Direct slots

Slot: name

Initargs

:name

Readers

attachment-name (generic function)

Writers

(setf attachment-name) (generic function)

Slot: data-pathname

Initargs

:data-pathname

Readers

attachment-data-pathname (generic function)

Writers

(setf attachment-data-pathname) (generic function)

Slot: mime-type

Initargs

:mime-type

Readers

attachment-mime-type (generic function)

Writers

(setf attachment-mime-type) (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *boundary-chars*

Package

cl-smtp

Source

attachments.lisp (file)

Special Variable: *debug*

Package

cl-smtp

Source

package.lisp (file)

Special Variable: *mime-type-descriptions*

Package

cl-smtp

Source

mime-types.lisp (file)

Special Variable: *mime-types*

Package

cl-smtp

Source

mime-types.lisp (file)

Special Variable: *return-newline*

Package

cl-smtp

Source

cl-smtp.lisp (file)

Special Variable: *x-mailer*

Package

cl-smtp

Source

cl-smtp.lisp (file)

5.2.2 Macros

Macro: print-debug STR

Package

cl-smtp

Source

package.lisp (file)

5.2.3 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 (file)

Function: check-arg ARG NAME

Package

cl-smtp

Source

cl-smtp.lisp (file)

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 (file)

Function: escape-rfc822-quoted-string STR

Package

cl-smtp

Source

attachments.lisp (file)

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 (file)

Function: generate-message-header SOCK &key BOUNDARY CONTENT-TYPE CONTENT-DISPOSITION CONTENT-TRANSFER-ENCODING INCLUDE-BLANK-LINE?

Package

cl-smtp

Source

attachments.lisp (file)

Function: generate-multipart-header SOCK BOUNDARY &key MULTIPART-TYPE

Package

cl-smtp

Source

attachments.lisp (file)

Function: get-email-date-string ()

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: get-timezone-from-integer X

Package

cl-smtp

Source

cl-smtp.lisp (file)

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 (file)

Function: lookup-mime-type FILE-NAME &optional DEFAULT

Extract mime type based on file-extension

Package

cl-smtp

Source

mime-types.lisp (file)

Function: make-random-boundary &optional LENGTH BOUNDARY-CHARS

Package

cl-smtp

Source

attachments.lisp (file)

Function: mask-dot STR

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

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: mask-dot-stream STR STREAM

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

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: read-from-smtp STREAM &optional LINES

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: rfc2045-q-encode-string-to-stream STR STREAM &key EXTERNAL-FORMAT COLUMNS

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: send-attachment SOCK ATTACHMENT BOUNDARY BUFFER-SIZE EXTERNAL-FORMAT

Package

cl-smtp

Source

attachments.lisp (file)

Function: send-attachment-header SOCK BOUNDARY ATTACHMENT EXTERNAL-FORMAT

Package

cl-smtp

Source

attachments.lisp (file)

Function: send-end-marker SOCK BOUNDARY

Package

cl-smtp

Source

attachments.lisp (file)

Function: send-mail-headers STREAM &key FROM TO CC REPLY-TO EXTRA-HEADERS DISPLAY-NAME SUBJECT EXTERNAL-FORMAT

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 (file)

Function: send-multipart-headers STREAM &key ATTACHMENT-BOUNDARY HTML-BOUNDARY

Package

cl-smtp

Source

cl-smtp.lisp (file)

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

Package

cl-smtp

Source

cl-smtp.lisp (file)

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 (file)

Function: smtp-command STREAM COMMAND EXPECTED-RESPONSE-CODE &key CONDITION-CLASS CONDITION-ARGUMENTS

Package

cl-smtp

Source

cl-smtp.lisp (file)

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 (file)

Function: string-has-non-ascii STR

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: string-to-base64-string STR &key EXTERNAL-FORMAT COLUMNS

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: substitute-return-newline STR

Replace all occurences of rn in STR with spaces

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: write-blank-line STREAM

Package

cl-smtp

Source

cl-smtp.lisp (file)

Function: write-to-smtp STREAM COMMAND

Package

cl-smtp

Source

cl-smtp.lisp (file)

5.2.4 Generic functions

Generic Function: command CONDITION

Package

cl-smtp

Methods

Method: command (CONDITION smtp-protocol-error)

Source

cl-smtp.lisp (file)

Generic Function: expected-response-code CONDITION

Package

cl-smtp

Methods

Method: expected-response-code (CONDITION smtp-protocol-error)

Source

cl-smtp.lisp (file)

Generic Function: features CONDITION

Package

cl-smtp

Methods

Method: features (CONDITION no-supported-authentication-method)

Source

cl-smtp.lisp (file)

Generic Function: recipient CONDITION

Package

cl-smtp

Methods

Method: recipient (CONDITION rcpt-failed)

Source

cl-smtp.lisp (file)

Generic Function: response-code CONDITION

Package

cl-smtp

Methods

Method: response-code (CONDITION smtp-protocol-error)

Source

cl-smtp.lisp (file)

Generic Function: response-message CONDITION

Package

cl-smtp

Methods

Method: response-message (CONDITION smtp-protocol-error)

Source

cl-smtp.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types