.. index:: single: smtp_protocol
.. _smtp_protocol/0:

.. rst-class:: right

**protocol**

``smtp_protocol``
=================

Protocol for portable SMTP clients.

| **Availability:** 
|    ``logtalk_load(smtp(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-09-11

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: send/5
.. _smtp_protocol/0::send/5:

``send/5``
^^^^^^^^^^

Opens an SMTP session, sends a message, and closes the session. Unicode ``Subject`` and ``Comments`` header values are serialized as RFC 2047 UTF-8 Base64 encoded words; all other header values must be ASCII.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``send(Host,Port,Message,Result,Options)``
| **Mode and number of proofs:**
|    ``send(+atom,+integer,+compound,--compound,+list)`` - ``one_or_error``

| **Exceptions:**
|    ``Host`` or ``Port`` is a variable:
|        ``instantiation_error``
|    ``Host`` is neither a variable nor an atom:
|        ``type_error(atom,Host)``
|    ``Port`` is neither a variable nor an integer:
|        ``type_error(integer,Port)``
|    ``Port`` is an integer but not positive:
|        ``domain_error(positive_integer,Port)``
|    ``Message`` is not an SMTP message term:
|        ``domain_error(smtp_message,Message)``
|    The envelope sender or a recipient is a variable:
|        ``instantiation_error``
|    The envelope sender or a recipient is neither a variable nor an atom:
|        ``type_error(atom,Mailbox)``
|    The envelope sender or a recipient is not a valid mailbox:
|        ``domain_error(smtp_mailbox,Mailbox)``
|    ``Recipients`` is not a non-empty list of mailboxes or a mailbox atom:
|        ``domain_error(smtp_recipients,Recipients)``
|    ``Headers`` is not a list:
|        ``type_error(list,Headers)``
|    A header name or value is a variable:
|        ``instantiation_error``
|    A header name or value is neither a variable nor an atom:
|        ``type_error(atom,HeaderComponent)``
|    ``Header`` is not a valid header pair:
|        ``domain_error(smtp_header,Header)``
|    ``Body`` is not a supported text representation:
|        ``domain_error(smtp_body,Body)``
|    A caller-supplied MIME header conflicts with UTF-8 Base64 serialization or duplicates another MIME header:
|        ``domain_error(smtp_mime_header,Header)``
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``
|    The SMTP connection cannot be opened:
|        ``smtp_error(connection_failed)``
|    OpenSSL terminates the secure connection while an SMTP response is expected:
|        ``smtp_error(secure_connection_failed(Status,Diagnostic))``
|    The SMTP server closes the connection while a response is expected at ``Stage``:
|        ``smtp_error(connection_closed(Stage))``
|    The SMTP server rejects the session greeting:
|        ``smtp_error(greeting_failed(Code,Lines))``
|    The SMTP server returns an invalid or unexpected response:
|        ``smtp_error(protocol_error(Response))``
|    Authentication is requested over an insecure connection without explicit permission:
|        ``permission_error(authenticate,insecure_smtp_connection,plain)``
|    The SMTP server does not advertise a supported authentication mechanism:
|        ``smtp_error(authentication_not_supported)``
|    The SMTP server rejects authentication:
|        ``smtp_error(auth_failed(Code,Lines))``
|    The SMTP server rejects the envelope sender:
|        ``smtp_error(sender_rejected(Code,Lines))``
|    The SMTP server rejects the DATA command or the submitted message:
|        ``smtp_error(send_failed(Code,Lines))``


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

.. index:: connect/4
.. _smtp_protocol/0::connect/4:

``connect/4``
^^^^^^^^^^^^^

Opens an SMTP session for sending one or more messages.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``connect(Host,Port,Connection,Options)``
| **Mode and number of proofs:**
|    ``connect(+atom,+integer,--compound,+list)`` - ``one_or_error``

| **Exceptions:**
|    ``Host`` or ``Port`` is a variable:
|        ``instantiation_error``
|    ``Host`` is neither a variable nor an atom:
|        ``type_error(atom,Host)``
|    ``Port`` is neither a variable nor an integer:
|        ``type_error(integer,Port)``
|    ``Port`` is an integer but not positive:
|        ``domain_error(positive_integer,Port)``
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``
|    ``Option`` is valid but is not a connection option:
|        ``domain_error(smtp_connection_option,Option)``
|    The SMTP connection cannot be opened:
|        ``smtp_error(connection_failed)``
|    OpenSSL terminates the secure connection while an SMTP response is expected:
|        ``smtp_error(secure_connection_failed(Status,Diagnostic))``
|    The SMTP server closes the connection while a response is expected at ``Stage``:
|        ``smtp_error(connection_closed(Stage))``
|    The SMTP server rejects the session greeting:
|        ``smtp_error(greeting_failed(Code,Lines))``
|    The SMTP server returns an invalid or unexpected response:
|        ``smtp_error(protocol_error(Response))``
|    Authentication is requested over an insecure connection without explicit permission:
|        ``permission_error(authenticate,insecure_smtp_connection,plain)``
|    The SMTP server does not advertise a supported authentication mechanism:
|        ``smtp_error(authentication_not_supported)``
|    The SMTP server rejects authentication:
|        ``smtp_error(auth_failed(Code,Lines))``


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

.. index:: disconnect/1
.. _smtp_protocol/0::disconnect/1:

``disconnect/1``
^^^^^^^^^^^^^^^^

Gracefully closes an SMTP session.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``disconnect(Connection)``
| **Mode and number of proofs:**
|    ``disconnect(+compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Connection`` is not an open SMTP connection handle:
|        ``domain_error(smtp_connection,Connection)``


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

.. index:: connection_alive/1
.. _smtp_protocol/0::connection_alive/1:

``connection_alive/1``
^^^^^^^^^^^^^^^^^^^^^^

Checks if the local streams for an SMTP connection are open.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``connection_alive(Connection)``
| **Mode and number of proofs:**
|    ``connection_alive(+compound)`` - ``zero_or_one``


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

.. index:: send/4
.. _smtp_protocol/0::send/4:

``send/4``
^^^^^^^^^^

Sends a message over an open SMTP session. Unicode ``Subject`` and ``Comments`` header values are serialized as RFC 2047 UTF-8 Base64 encoded words; all other header values must be ASCII.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``send(Connection,Message,Result,Options)``
| **Mode and number of proofs:**
|    ``send(+compound,+compound,--compound,+list)`` - ``one_or_error``

| **Exceptions:**
|    ``Connection`` is not an open SMTP connection handle:
|        ``domain_error(smtp_connection,Connection)``
|    ``Message`` is not an SMTP message term:
|        ``domain_error(smtp_message,Message)``
|    The envelope sender or a recipient is a variable:
|        ``instantiation_error``
|    The envelope sender or a recipient is neither a variable nor an atom:
|        ``type_error(atom,Mailbox)``
|    The envelope sender or a recipient is not a valid mailbox:
|        ``domain_error(smtp_mailbox,Mailbox)``
|    ``Recipients`` is not a non-empty list of mailboxes or a mailbox atom:
|        ``domain_error(smtp_recipients,Recipients)``
|    ``Headers`` is not a list:
|        ``type_error(list,Headers)``
|    A header name or value is a variable:
|        ``instantiation_error``
|    A header name or value is neither a variable nor an atom:
|        ``type_error(atom,HeaderComponent)``
|    ``Header`` is not a valid header pair:
|        ``domain_error(smtp_header,Header)``
|    ``Body`` is not a supported text representation:
|        ``domain_error(smtp_body,Body)``
|    A caller-supplied MIME header conflicts with UTF-8 Base64 serialization or duplicates another MIME header:
|        ``domain_error(smtp_mime_header,Header)``
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``
|    ``Option`` is valid but is not a transaction option:
|        ``domain_error(smtp_transaction_option,Option)``
|    The SMTP server closes the connection while a response is expected at ``Stage``:
|        ``smtp_error(connection_closed(Stage))``
|    The SMTP server returns an invalid or unexpected response:
|        ``smtp_error(protocol_error(Response))``
|    The SMTP server rejects the envelope sender:
|        ``smtp_error(sender_rejected(Code,Lines))``
|    The SMTP server rejects the DATA command or the submitted message:
|        ``smtp_error(send_failed(Code,Lines))``


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

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)