SHTMLMailer Class

Properties   Methods   Events   Config Settings   Errors  

The SHTMLMailer Class is used to send HTML emails, including embedded images.

Syntax

class ipworkssmime.SHTMLMailer

Remarks

The SHTMLMailer Class supports both plaintext and Secure Sockets Layer/Transport Layer Security (SSL/TLS) connections (RFC 2487). When connecting over SSL/TLS the on_ssl_server_authentication event allows you to check the server identity and other security attributes. The on_ssl_status event provides information about the SSL handshake. Additional SSL related settings are also supported via the config method.

The class sends a message (provided in message_html and message_text). The HTML message may contain references to images that are automatically embedded into the message.

The message_html property contains the HTML version of the message. The corresponding plaintext version is provided in the message_text property.

When message_html is set, the class automatically computes a plaintext version of the text and puts it into message_text. You may choose to override this default text with your own version.

The recipients are specified by the send_to, cc, and b_cc properties, and the message subject by the subject property.

Once all the appropriate properties have been set, call the send method and your message will be sent to its intended recipient(s).

Other SMTP headers may be specified through the other_headers property. Information about interaction with the server is provided by the on_pi_trail event.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

attachment_count Property

The number of records in the Attachment arrays.

Syntax

def get_attachment_count() -> int: ...
def set_attachment_count(value: int) -> None: ...

attachment_count = property(get_attachment_count, set_attachment_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• attachment_file
• attachment_name

The array indices start at 0 and end at attachment_count - 1.

attachment_file Property

This property contains the path of a file on your system to be sent as an attachment with your message.

Syntax

def get_attachment_file(attachment_index: int) -> str: ...
def set_attachment_file(attachment_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the path of a file on your system to be sent as an attachment with your message.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

attachment_name Property

This property contains the name of the attachment to be sent.

Syntax

def get_attachment_name(attachment_index: int) -> str: ...
def set_attachment_name(attachment_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the name of the attachment to be sent.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

auth_mechanism Property

This property is used when connecting to the mail server.

Syntax

def get_auth_mechanism() -> int: ...
def set_auth_mechanism(value: int) -> None: ...

auth_mechanism = property(get_auth_mechanism, set_auth_mechanism)

Default Value

0

Remarks

This is the authentication mechanism property to be used when connecting to the mail server.

By default, this property is amUserPassword (0), and if the user and password properties are set, the AUTH command is sent to the server for authentication. If this property is set to amCRAMMD5 (1), CRAM-MD5 authentication is used instead.

If this property is set to amNTLM (2), NTLM authentication will be used.

If this property is set to amKerberos (6), Kerberos authentication will be used.

Note: This functionality is available only in Windows.

When set to amXOAUTH2 (7), set user to the username and AuthorizationIdentity to the OAuth token. See AuthorizationIdentity for details.

b_cc Property

This property includes a comma-separated list of addresses for blind carbon copies (optional).

Syntax

def get_b_cc() -> str: ...
def set_b_cc(value: str) -> None: ...

b_cc = property(get_b_cc, set_b_cc)

Default Value

""

Remarks

This property specifies a comma-separated list of destinations for blind carbon copies of the mail message. A copy of the message is sent to each destination. Because no BCc SMTP header is created containing the destination addresses, individual recipients never see the list of the other recipients.

The class will return an error if the mail_server returns an error code about any email address specified in send_to or cc but it will fire an on_error event only if the same thing happens with an email address specified in this property.

If the resulting header is longer than MaxHeaderLength, then it is folded according to RFC 822 specifications.

Note: You must clear the message_recipients properties before setting this property to remove previous recipients.

cc Property

This property includes a comma-separated list of addresses for carbon copies (optional).

Syntax

def get_cc() -> str: ...
def set_cc(value: str) -> None: ...

cc = property(get_cc, set_cc)

Default Value

""

Remarks

This property specifies a comma-separated list of destinations for carbon copies of the mail message. A copy of the message is sent to each destination, and a Cc SMTP header is created containing the destination addresses. This header is sent to every recipient of the message. If you don't want to copy this information to every recipient, then use blind carbon copies instead (see the description of the b_cc).

The class will return an error if the mail_server returns an error code about any email address specified in send_to or cc but it will fire an on_error event only if the same thing happens with an email address specified in b_cc.

If the resulting header is longer than MaxHeaderLength, then it is folded according to RFC 822 specifications.

Note: You must clear the message_recipients properties before setting this property to remove previous recipients.

cert_encoded Property

This is the certificate (PEM/base64 encoded).

Syntax

def get_cert_encoded() -> bytes: ...
def set_cert_encoded(value: bytes) -> None: ...

cert_encoded = property(get_cert_encoded, set_cert_encoded)

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The cert_store and cert_subject properties also may be used to specify a certificate.

When cert_encoded is set, a search is initiated in the current cert_store for the private key of the certificate. If the key is found, cert_subject is updated to reflect the full subject of the selected certificate; otherwise, cert_subject is set to an empty string.

cert_store Property

This is the name of the certificate store for the client certificate.

Syntax

def get_cert_store() -> bytes: ...
def set_cert_store(value: bytes) -> None: ...

cert_store = property(get_cert_store, set_cert_store)

Default Value

"MY"

Remarks

This is the name of the certificate store for the client certificate.

The cert_store_type property denotes the type of the certificate store specified by cert_store. If the store is password protected, specify the password in cert_store_password.

cert_store is used in conjunction with the cert_subject property to specify client certificates. If cert_store has a value, and cert_subject or cert_encoded is set, a search for a certificate is initiated. Please see the cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_cert_store_password() -> str: ...
def set_cert_store_password(value: str) -> None: ...

cert_store_password = property(get_cert_store_password, set_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

cert_store_type Property

This is the type of certificate store for this certificate.

Syntax

def get_cert_store_type() -> int: ...
def set_cert_store_type(value: int) -> None: ...

cert_store_type = property(get_cert_store_type, set_cert_store_type)

Default Value

0

Remarks

This is the type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

cert_subject Property

This is the subject of the certificate used for client authentication.

Syntax

def get_cert_subject() -> str: ...
def set_cert_subject(value: str) -> None: ...

cert_subject = property(get_cert_subject, set_cert_subject)

Default Value

""

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

command Property

This property is used to send additional commands directly to the server.

Syntax

def set_command(value: str) -> None: ...

command = property(None, set_command)

Default Value

""

Remarks

This property can be used to send additional commands directly to the server. Check the last_reply property or trap the on_pi_trail events coming from the server to get the response.

This property is write-only.

connected Property

This shows whether the class is connected.

Syntax

def get_connected() -> bool: ...
def set_connected(value: bool) -> None: ...

connected = property(get_connected, set_connected)

Default Value

FALSE

Remarks

This property is used to determine whether or not the class is connected to the remote host.

Note: It is recommended to use the connect or disconnect method instead of setting this property.

delivery_notification_to Property

This property includes the email address to which to send a delivery notification.

Syntax

def get_delivery_notification_to() -> str: ...
def set_delivery_notification_to(value: str) -> None: ...

delivery_notification_to = property(get_delivery_notification_to, set_delivery_notification_to)

Default Value

""

Remarks

This property contains the email address to send to which to send a delivery notification. When set, a Return-Receipt-To header is added to the message. This property should be set to an email address that can receive the delivery notification.

encrypting_algorithm Property

The property includes textual description of the encrypting algorithm.

Syntax

def get_encrypting_algorithm() -> str: ...
def set_encrypting_algorithm(value: str) -> None: ...

encrypting_algorithm = property(get_encrypting_algorithm, set_encrypting_algorithm)

Default Value

"3DES"

Remarks

This property contains either the name of the algorithm (such as 3DES or AES), or an object identifier (OID) string representing the algorithm.

Possible values are as follows:

• "3DES"
• "DES"
• "RC2CBC40"
• "RC2CBC64"
• "RC2CBC128" or "RC2"
• "AESCBC128" or "AES"
• "AESCBC192"
• "AESCBC256"
• "AESGCM128" or "AESGCM"
• "AESGCM192"
• "AESGCM256"

firewall_auto_detect Property

This property tells the class whether or not to automatically detect and use firewall system settings, if available.

Syntax

def get_firewall_auto_detect() -> bool: ...
def set_firewall_auto_detect(value: bool) -> None: ...

firewall_auto_detect = property(get_firewall_auto_detect, set_firewall_auto_detect)

Default Value

FALSE

Remarks

This property tells the class whether or not to automatically detect and use firewall system settings, if available.

firewall_type Property

This property determines the type of firewall to connect through.

Syntax

def get_firewall_type() -> int: ...
def set_firewall_type(value: int) -> None: ...

firewall_type = property(get_firewall_type, set_firewall_type)

Default Value

0

Remarks

This property determines the type of firewall to connect through. The applicable values are as follows:

firewall_host Property

This property contains the name or IP address of firewall (optional).

Syntax

def get_firewall_host() -> str: ...
def set_firewall_host(value: str) -> None: ...

firewall_host = property(get_firewall_host, set_firewall_host)

Default Value

""

Remarks

This property contains the name or IP address of firewall (optional). If a firewall_host is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the class fails with an error.

firewall_password Property

This property contains a password if authentication is to be used when connecting through the firewall.

Syntax

def get_firewall_password() -> str: ...
def set_firewall_password(value: str) -> None: ...

firewall_password = property(get_firewall_password, set_firewall_password)

Default Value

""

Remarks

This property contains a password if authentication is to be used when connecting through the firewall. If firewall_host is specified, the firewall_user and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

firewall_port Property

This property contains the transmission control protocol (TCP) port for the firewall Host .

Syntax

def get_firewall_port() -> int: ...
def set_firewall_port(value: int) -> None: ...

firewall_port = property(get_firewall_port, set_firewall_port)

Default Value

0

Remarks

This property contains the transmission control protocol (TCP) port for the firewall firewall_host. See the description of the firewall_host property for details.

Note: This property is set automatically when firewall_type is set to a valid value. See the description of the firewall_type property for details.

firewall_user Property

This property contains a user name if authentication is to be used connecting through a firewall.

Syntax

def get_firewall_user() -> str: ...
def set_firewall_user(value: str) -> None: ...

firewall_user = property(get_firewall_user, set_firewall_user)

Default Value

""

Remarks

This property contains a user name if authentication is to be used connecting through a firewall. If the firewall_host is specified, this property and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

from_ Property

The email address of the sender (required).

Syntax

def get_from() -> str: ...
def set_from(value: str) -> None: ...

from_ = property(get_from, set_from)

Default Value

""

Remarks

This property is used to create a From SMTP header. This header identifies the sender of the message. A valid email address is required. Examples of valid addresses are: "Friendly Name" <address@company.com> or address@company.com

If the resulting header is longer than MaxHeaderLength, then it is folded according to RFC 822 specifications.

html_file Property

This property includes the path to a local HTML file.

Syntax

def get_html_file() -> str: ...
def set_html_file(value: str) -> None: ...

html_file = property(get_html_file, set_html_file)

Default Value

""

Remarks

This property may contain the path to the local HTML file. If this property is not empty, the contents of the file with that name will be appended to the text in message_html.

Note: This means that if message_html is empty, html_file is what will be sent to the server.

idle Property

The current status of the class.

Syntax

def get_idle() -> bool: ...

idle = property(get_idle, None)

Default Value

TRUE

Remarks

idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.

This property is read-only.

image_count Property

The number of records in the Image arrays.

Syntax

def get_image_count() -> int: ...
def set_image_count(value: int) -> None: ...

image_count = property(get_image_count, set_image_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• image_data
• image_file
• image_id
• image_type

The array indices start at 0 and end at image_count - 1.

image_data Property

This property optionally specifies the image data.

Syntax

def get_image_data(image_index: int) -> bytes: ...
def set_image_data(image_index: int, value: bytes) -> None: ...

Default Value

""

Remarks

This property optionally specifies the image data. This may be used instead of specifying an image by file. The value specified here may be either the hex-encoded image data or the raw unencoded image data.

The image_index parameter specifies the index of the item in the array. The size of the array is controlled by the image_count property.

image_file Property

This property contains the name of the image files embedded into the HTML message.

Syntax

def get_image_file(image_index: int) -> str: ...
def set_image_file(image_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the name of the image files embedded into the HTML message. This value is updated every time message_html is set. You may change the file names before sending (e.g., if they don't point to valid files).

The image_index parameter specifies the index of the item in the array. The size of the array is controlled by the image_count property.

image_id Property

This property contains the content identifier for embedded images.

Syntax

def get_image_id(image_index: int) -> str: ...
def set_image_id(image_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the content identifier for embedded images. This value is computed automatically, unless parse_html is False, in which case you are responsible for providing it.

The image_index parameter specifies the index of the item in the array. The size of the array is controlled by the image_count property.

image_type Property

This property contains the content type for embedded images.

Syntax

def get_image_type(image_index: int) -> str: ...
def set_image_type(image_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the content type for embedded images. This value is determined automatically, unless parse_html is False, in which case you are responsible for providing it.

The image_index parameter specifies the index of the item in the array. The size of the array is controlled by the image_count property.

importance Property

Importance of the mail message (optional).

Syntax

def get_importance() -> int: ...
def set_importance(value: int) -> None: ...

importance = property(get_importance, set_importance)

Default Value

0

Remarks

This property indicates the importance of the mail message (optional). When set, an Importance header will be added to the message.

Importance is an indication to the recipient(s) about how important the message is. The possible values are Unspecified (0), High (1), Normal (2), and Low (3).

include_certificate Property

This property specifies whether to include the signer's certificate with the signed message.

Syntax

def get_include_certificate() -> bool: ...
def set_include_certificate(value: bool) -> None: ...

include_certificate = property(get_include_certificate, set_include_certificate)

Default Value

TRUE

Remarks

If this property is set to True, the certificate used to sign the message will be encoded and included in a message signature when calling sign or sign_and_encrypt.

Including a certificate is the preferred method of building signed messages. If you do not include a certificate, the message recipient may not be able to verify the sender's signature.

include_chain Property

This property specifies whether to include the signer's certificate chain with the signed message.

Syntax

def get_include_chain() -> bool: ...
def set_include_chain(value: bool) -> None: ...

include_chain = property(get_include_chain, set_include_chain)

Default Value

FALSE

Remarks

If this property is set to True, the entire certificate's chain that was used to sign the message will be encoded and included in the message signature when calling sign or sign_and_encrypt.

Note: To include the chain, the include_certificate property must also be set to true.

last_reply Property

The last reply from the server.

Syntax

def get_last_reply() -> str: ...

last_reply = property(get_last_reply, None)

Default Value

""

Remarks

This property indicates the last reply received from the server. It can be used for informational purposes. The same information and more can also be retrieved through the on_pi_trail event.

This property is read-only.

local_host Property

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

def get_local_host() -> str: ...
def set_local_host(value: str) -> None: ...

local_host = property(get_local_host, set_local_host)

Default Value

""

Remarks

The local_host property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

If the class is connected, the local_host property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: local_host is not persistent. You must always set it in code, and never in the property window.

mail_port Property

The server port for SMTP (default 25).

Syntax

def get_mail_port() -> int: ...
def set_mail_port(value: int) -> None: ...

mail_port = property(get_mail_port, set_mail_port)

Default Value

25

Remarks

This property contains the server port for SMTP (default 25). A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.

For implicit SSL, use port 465 (please refer to the ssl_start_mode property for more information).

mail_server Property

The name or address of a mail server (mail relay).

Syntax

def get_mail_server() -> str: ...
def set_mail_server(value: str) -> None: ...

mail_server = property(get_mail_server, set_mail_server)

Default Value

""

Remarks

This property specifies the IP address (IP number in dotted internet format) or Domain Name for a mail relay through which messages will be routed. It is set before a connection is attempted and cannot be changed once a connection is in progress.

The current version of the class does not provide a default value for the mail relay. You must provide a host name yourself. Generally, any internet host with an SMTP server will suffice (a UNIX host for example), but it is preferable to select a mail_server that is close to the machine sending mail.

If this property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, an error is returned.

If the class is configured to use a SOCKS firewall, the value assigned to this property may be preceded with an "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

message_date Property

Date of the mail message (optional).

Syntax

def get_message_date() -> str: ...
def set_message_date(value: str) -> None: ...

message_date = property(get_message_date, set_message_date)

Default Value

"*"

Remarks

If this property contains a non-empty string, then a Date SMTP header is created and attached to the message. If it is an empty string, then the date information is added by the mail relay(s) the message goes through.

Special case: if this property is set to the special value "*", a Date SMTP header reflecting the current date and time is generated when message_headers is computed and the message is sent. This is the default behavior of the class

RFC 822 contains detailed date format specifications. An example of a valid date is "Fri, 1 Mar 96 21:24:52 EST".

message_html Property

This property includes the HTML version of the message.

Syntax

def get_message_html() -> str: ...
def set_message_html(value: str) -> None: ...

message_html = property(get_message_html, set_message_html)

Default Value

""

Remarks

This property contains the HTML version of the message.

When this property is set, the class automatically computes a plaintext version of the text and puts it into message_text. You may choose to override this default text with your own version.

Example. Setting MessageHTML:

component.MessageHTML = "<b>Hello</b>, my name is <i>Tom</i>";

message_id Property

The Message Identifier for the message.

Syntax

def get_message_id() -> str: ...
def set_message_id(value: str) -> None: ...

message_id = property(get_message_id, set_message_id)

Default Value

"*"

Remarks

This property contains the Message Identifier for the message. When set, the value of message_id is used as the Message-ID header value of the message. A special value of "*" will automatically generate a random unique identifier for the message.

message_recipient_count Property

The number of records in the MessageRecipient arrays.

Syntax

def get_message_recipient_count() -> int: ...
def set_message_recipient_count(value: int) -> None: ...

message_recipient_count = property(get_message_recipient_count, set_message_recipient_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• message_recipient_address
• message_recipient_name
• message_recipient_options
• message_recipient_type

The array indices start at 0 and end at message_recipient_count - 1.

message_recipient_address Property

This property contains the email address of the recipient.

Syntax

def get_message_recipient_address(recipient_index: int) -> str: ...
def set_message_recipient_address(recipient_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the email address of the recipient.

The recipient_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_recipient_count property.

message_recipient_name Property

This property contains the name of the recipient.

Syntax

def get_message_recipient_name(recipient_index: int) -> str: ...
def set_message_recipient_name(recipient_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the name of the recipient.

The recipient_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_recipient_count property.

message_recipient_options Property

This property contains the recipient sending options (used only by SMTP).

Syntax

def get_message_recipient_options(recipient_index: int) -> str: ...
def set_message_recipient_options(recipient_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the recipient sending options (used only by SMTP). This must be a string of RFC-compliant recipient options (used by SMTP).

One type of option is a delivery status notification sent per recipient, which is specified by RFC 1891.

component.MessageRecipientOptions(0) = "NOTIFY SUCCESS,FAILURE,DELAY";

The recipient_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_recipient_count property.

message_recipient_type Property

This property contains the recipient type: To, Cc, or Bcc.

Syntax

def get_message_recipient_type(recipient_index: int) -> int: ...
def set_message_recipient_type(recipient_index: int, value: int) -> None: ...

Default Value

0

Remarks

This property contains the recipient type: To, Cc, or Bcc.

The recipient_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_recipient_count property.

message_text Property

This property includes the plaintext version of the message.

Syntax

def get_message_text() -> str: ...
def set_message_text(value: str) -> None: ...

message_text = property(get_message_text, set_message_text)

Default Value

""

Remarks

This property is a plaintext version of the HTML message. This is necessary for recipients with legacy mail readers that do not support HTML.

The message_html property contains the HTML version of the message. When message_html is set, the class automatically computes a plaintext version of the text and puts it into this property. You may choose to override this default text with your own version.

other_headers Property

An RFC 822 compliant string consisting of extra headers.

Syntax

def get_other_headers() -> str: ...
def set_other_headers(value: str) -> None: ...

other_headers = property(get_other_headers, set_other_headers)

Default Value

""

Remarks

This property contains a string of headers to be appended to the message headers created from other properties like send_to, subject, etc.

The headers must be of the format "header: value" as specified in RFC 822. Header lines should be separated by CRLF ("\r\n") .

Use this property with caution. If this property contains invalid headers, message delivery might not be successful.

This property is useful for extending the functionality of the class. A good example is delivery of MIME encoded messages.

SPECIAL CASE: if this property starts with an empty line (CRLF), then the value of this property is used instead of the normally computed message headers.

Example (Send an Email With Additional Header)

component.MailServer = "MyServer"; component.From = "me@server.com"; component.SendTo = "recipient@server.com"; component.Subject = "My Subject"; component.MessageText = "This is the message body."; component.OtherHeaders = "HeaderName: HeaderValue"; component.Send();

parse_html Property

This property controls the behavior of the MessageHTML property.

Syntax

def get_parse_html() -> bool: ...
def set_parse_html(value: bool) -> None: ...

parse_html = property(get_parse_html, set_parse_html)

Default Value

TRUE

Remarks

This property controls the behavior of the message_html property. If parse_html is set to False, you must provide valid values in message_html, message_text, and images.

password Property

A password for logon to the MailServer .

Syntax

def get_password() -> str: ...
def set_password(value: str) -> None: ...

password = property(get_password, set_password)

Default Value

""

Remarks

If this property is set to a non-empty string, then when connecting to the mail_server an AUTH or CRAM-MD5 (depending on the value of auth_mechanism) command is sent in order to provide authentication information for the user.

priority Property

Priority of the mail message (optional).

Syntax

def get_priority() -> int: ...
def set_priority(value: int) -> None: ...

priority = property(get_priority, set_priority)

Default Value

0

Remarks

When this property is set, a Priority header will be added to the message. Priority is an indication about the delivery priority of the message. The possible values are epNormal, epUrgent, and epNonUrgent.

read_receipt_to Property

Email address to send a read receipt to.

Syntax

def get_read_receipt_to() -> str: ...
def set_read_receipt_to(value: str) -> None: ...

read_receipt_to = property(get_read_receipt_to, set_read_receipt_to)

Default Value

""

Remarks

When this property is set, a Disposition-Notification-To header is added to the message. This property should be set to an email address which should receive the read-receipt.

reply_to Property

A mail address to which to reply (optional).

Syntax

def get_reply_to() -> str: ...
def set_reply_to(value: str) -> None: ...

reply_to = property(get_reply_to, set_reply_to)

Default Value

""

Remarks

If this property contains a non-empty string, a Reply-To SMTP header is created for the message. This header shows the address to use for replies (useful if this address is different from the one in from_).

If the resulting header is longer than MaxHeaderLength, then it is folded according to RFC 822 specifications.

send_to Property

A comma separated list of addresses for destinations (required).

Syntax

def get_send_to() -> str: ...
def set_send_to(value: str) -> None: ...

send_to = property(get_send_to, set_send_to)

Default Value

""

Remarks

This property specifies a comma separated list of destinations for the mail message. A copy of the message is sent to each of them, and a To SMTP header is created containing the destination addresses.

Examples of valid addresses are: "Friendly Name" <address@company.com> or address@company.com

The class will fail if the mail_server returns an error code about any email address specified in SendTo or cc but it will silently ignore the error if the same happens with an email address specified in b_cc.

If the resulting header is longer than MaxHeaderLength, then it is folded according to RFC 822 specifications.

NOTE: You must clear the message_recipients properties before setting this property to remove previous recipients.

sensitivity Property

Sensitivity of the mail message (optional).

Syntax

def get_sensitivity() -> int: ...
def set_sensitivity(value: int) -> None: ...

sensitivity = property(get_sensitivity, set_sensitivity)

Default Value

0

Remarks

This property is an indication of how sensitive it is to disclose the message to people other than the recipients of the message. When set, a Sensitivity header will added to the message. Possible values are: esPersonal (1), esPrivate (2), and esCompanyConfidential (3).

signing_algorithm Property

This property includes a textual description of the signature hash algorithm.

Syntax

def get_signing_algorithm() -> str: ...
def set_signing_algorithm(value: str) -> None: ...

signing_algorithm = property(get_signing_algorithm, set_signing_algorithm)

Default Value

"SHA256"

Remarks

This property specifies the hash algorithm used to prepare the message digest for signature.

This property must contain either the name of the algorithm (such as MD5 or SHA1), or an object Id (OID) string representing the hash algorithm. Possible values are as follows:

• sha1
• md5
• sha-256 (default)
• sha-384
• sha-512
• sha-224

When read, the value of the property always contains the OID of the algorithm, or an empty string if the algorithm is unknown.

ssl_accept_server_cert_encoded Property

This is the certificate (PEM/base64 encoded).

Syntax

def get_ssl_accept_server_cert_encoded() -> bytes: ...
def set_ssl_accept_server_cert_encoded(value: bytes) -> None: ...

ssl_accept_server_cert_encoded = property(get_ssl_accept_server_cert_encoded, set_ssl_accept_server_cert_encoded)

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_accept_server_cert_store and ssl_accept_server_cert_subject properties also may be used to specify a certificate.

When ssl_accept_server_cert_encoded is set, a search is initiated in the current ssl_accept_server_cert_store for the private key of the certificate. If the key is found, ssl_accept_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_accept_server_cert_subject is set to an empty string.

ssl_cert_encoded Property

This is the certificate (PEM/base64 encoded).

Syntax

def get_ssl_cert_encoded() -> bytes: ...
def set_ssl_cert_encoded(value: bytes) -> None: ...

ssl_cert_encoded = property(get_ssl_cert_encoded, set_ssl_cert_encoded)

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

ssl_cert_store Property

This is the name of the certificate store for the client certificate.

Syntax

def get_ssl_cert_store() -> bytes: ...
def set_ssl_cert_store(value: bytes) -> None: ...

ssl_cert_store = property(get_ssl_cert_store, set_ssl_cert_store)

Default Value

"MY"

Remarks

This is the name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

ssl_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_cert_store_password() -> str: ...
def set_ssl_cert_store_password(value: str) -> None: ...

ssl_cert_store_password = property(get_ssl_cert_store_password, set_ssl_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

ssl_cert_store_type Property

This is the type of certificate store for this certificate.

Syntax

def get_ssl_cert_store_type() -> int: ...
def set_ssl_cert_store_type(value: int) -> None: ...

ssl_cert_store_type = property(get_ssl_cert_store_type, set_ssl_cert_store_type)

Default Value

0

Remarks

This is the type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

ssl_cert_subject Property

This is the subject of the certificate used for client authentication.

Syntax

def get_ssl_cert_subject() -> str: ...
def set_ssl_cert_subject(value: str) -> None: ...

ssl_cert_subject = property(get_ssl_cert_subject, set_ssl_cert_subject)

Default Value

""

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

ssl_enabled Property

Whether TLS/SSL is enabled.

Syntax

def get_ssl_enabled() -> bool: ...
def set_ssl_enabled(value: bool) -> None: ...

ssl_enabled = property(get_ssl_enabled, set_ssl_enabled)

Default Value

FALSE

Remarks

This setting specifies whether TLS/SSL is enabled in the class. When False (default) the class operates in plaintext mode. When True TLS/SSL is enabled.

TLS/SSL may also be enabled by setting ssl_start_mode. Setting ssl_start_mode will automatically update this property value.

ssl_provider Property

This specifies the SSL/TLS implementation to use.

Syntax

def get_ssl_provider() -> int: ...
def set_ssl_provider(value: int) -> None: ...

ssl_provider = property(get_ssl_provider, set_ssl_provider)

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic) the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are:

In most cases using the default value (Automatic) is recommended. The class will select a provider depending on the current platform.

When Automatic is selected, on Windows the class will use the platform implementation. On Linux/macOS the class will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols the internal implementation is used on all platforms.

ssl_server_cert_encoded Property

This is the certificate (PEM/base64 encoded).

Syntax

def get_ssl_server_cert_encoded() -> bytes: ...

ssl_server_cert_encoded = property(get_ssl_server_cert_encoded, None)

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_server_cert_store and ssl_server_cert_subject properties also may be used to specify a certificate.

When ssl_server_cert_encoded is set, a search is initiated in the current ssl_server_cert_store for the private key of the certificate. If the key is found, ssl_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_server_cert_subject is set to an empty string.

This property is read-only.

ssl_start_mode Property

Determines how the class starts the SSL negotiation.

Syntax

def get_ssl_start_mode() -> int: ...
def set_ssl_start_mode(value: int) -> None: ...

ssl_start_mode = property(get_ssl_start_mode, set_ssl_start_mode)

Default Value

3

Remarks

The ssl_start_mode property may have one of the following values:

subject Property

The subject of the mail message (optional).

Syntax

def get_subject() -> str: ...
def set_subject(value: str) -> None: ...

subject = property(get_subject, set_subject)

Default Value

""

Remarks

The string in this property is sent with a Subject SMTP header to the mail recipient.

If the resulting header is longer than MaxHeaderLength, then it is folded according to RFC 822 specifications.

timeout Property

A timeout for the class.

Syntax

def get_timeout() -> int: ...
def set_timeout(value: int) -> None: ...

timeout = property(get_timeout, set_timeout)

Default Value

60

Remarks

If the timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If timeout is set to a positive value, the class will wait for the operation to complete before returning control.

The class will use do_events to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If timeout expires, and the operation is not yet complete, the class fails with an error.

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by timeout seconds when any amount of data is successfully sent or received.

The default value for the timeout property is 60 seconds.

user Property

A user identifier to login as in the MailServer .

Syntax

def get_user() -> str: ...
def set_user(value: str) -> None: ...

user = property(get_user, set_user)

Default Value

""

Remarks

If this property is set to a non-empty string, then when connecting to the mail_server an AUTH or CRAM-MD5 (depending on the value of auth_mechanism) command is sent in order to provide authentication information for the user.

add_attachment Method

This adds FileName as an attachment.

Syntax

def add_attachment(file_name: str) -> None: ...

Remarks

This method adds the file name as an attachment. The full list of attachments is contained in the attachments property.

Example 1: Adding an Attachment

component.AddAttachment("C:\file1.zip"); component.AddAttachment("C:\file2.zip"); component.Send(); Example 3: Using an Attachments Array

component.AttachmentCount = 1; component.AttachmentName(0) = "name"; component.AttachmentFile(0) = "C:\file.txt";

add_recipient_cert Method

This method is used to add recipient certificates used to encrypt messages.

Syntax

def add_recipient_cert(cert_encoded: bytes) -> None: ...

Remarks

This method is used to add recipient certificates to the internal message_recipients properties used to encrypt the message. The recipient certificate must be a valid PKCS-encoded certificate. If the certificate provided is Base64 encoded, it will be decoded first by the object.

The CertMgr class may be used to retrieve the appropriate certificate from the system.

calc_message_text Method

This method populates MessageText with the plaintext version of the message.

Syntax

def calc_message_text() -> None: ...

Remarks

This method parses message_html or html_file and calculates a plaintext version of the message. The plaintext version is stored in the message_text property.

Calling this method is optional. When the send method is called, the class will automatically calculate a plaintext version of the message. This may be called in cases in which the plaintext version will be set explicitly. For instance:

component.MessageHTML="<html><body><b>Test Message</b></body></html>"; component.CalcMessageText(); component.MessageText = "A new custom plaintext message";

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

connect Method

This method connects to the mail relay and sends the SMTP HELO command.

Syntax

def connect() -> None: ...

Remarks

This method connects to the mail relay and sends the SMTP HELO command, thus preparing to send messages. Any number of messages can later be sent using the send method.

Example. Connecting and Sending an Email:

control.MailServer = "MyServer" control.From = "me@server.com" control.SendTo = "recipient@server.com" control.Subject = "My Subject" control.MessageText = "This is the message body" control.Connect() control.Send() control.Disconnect()

disconnect Method

This method disconnects from the SMTP server.

Syntax

def disconnect() -> None: ...

Remarks

This method disconnects from the mail relay.

do_events Method

Processes events from the internal message queue.

Syntax

def do_events() -> None: ...

Remarks

When do_events is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

encrypt Method

This method encrypts the message.

Syntax

def encrypt() -> None: ...

Remarks

This method encrypts the input message in a Public Key Cryptography Standards (PKCS)-encoded envelope with all of the recipient certificates specified in the message_recipients properties.

Note: The message headers, including the Sender, Recipient(s), and Subject, are not encrypted. If this is sensitive information, consider including these headers in the message body as a MIME entity, and providing other headers for the S/MIME wrapper.

interrupt Method

Interrupt the current method.

Syntax

def interrupt() -> None: ...

Remarks

If there is no method in progress, interrupt simply returns, doing nothing.

process_queue Method

Sends the messages which have previously been queued into QueueDir .

Syntax

def process_queue(queue_dir: str) -> None: ...

Remarks

This method sends the messages which have previously been queued into QueueDir. The on_pi_trail event shows the interaction with the server as messages as are processed.

This method looks in the directory for files with extension ".queued" and starts processing them.

When processing starts, the file extension is changed to ".sending". If an error happens at this stage, the sending process is aborted, and the file extension is changed to ".failed".

If the file is successfully sent, the file is normally deleted, unless the KeepQueue configuration setting is set to True, in which case the file extension is instead changed to ".sent" and the queue file is not deleted.

queue Method

Queues the message into QueueDir .

Syntax

def queue(queue_dir: str) -> str: ...

Remarks

This method queues the message into QueueDir. The message is queued into a unique file into the directory QueueDir for future processing.

QueueDir must already exist, or an error will be generated. Alternatively, QueueDir may be set to "*" to return the result as a string instead of writing it to a file.

The method returns the name of the unique queue file created in QueueDir. The file extension is ".queued".

Please refer to the process_queue method for more information on email queue processing.

reset Method

Reset the class.

Syntax

def reset() -> None: ...

Remarks

This method will reset the class's properties to their default values.

reset_headers Method

Resets all the message headers to empty.

Syntax

def reset_headers() -> None: ...

Remarks

This method resets all the message headers to "" (empty string). Use this method before creating a new message, so that headers from the previous message are not carried over to the next one.

send Method

This method sends the current message and MIME-encoded attachment.

Syntax

def send() -> None: ...

Remarks

This method sends the current message and MIME-encoded attachment. If the class is not connected to the mail relay, a connection is created, the message is sent, and then the connection is closed unless an error occurs.

If the class is already connected (by use of the connect method), the connection will remain open after the message is sent. To disconnect, call the disconnect method.

Example. Send an HTML Email:

HTMLMailerControl.MailServer = "myserver" HTMLMailerControl.SendTo = "recipient@myserver.com" HTMLMailerControl.From = "me@myserver.com" HTMLMailerControl.Subject = "My Subject" HTMLMailerControl.MessageHTML = "<b>Hello</b>, my name is <i>Tom</i>" HTMLMailerControl.Send

send_command Method

Sends the exact command directly to the server.

Syntax

def send_command(command: str) -> None: ...

Remarks

This method sends the command specified by Command to the server exactly as it is provided. Use this method to send additional or custom commands directly to the server.

After calling this method check the last_reply property and/or monitor the on_pi_trail event to obtain the server's response.

sign Method

Signs the current message.

Syntax

def sign() -> None: ...

Remarks

This method digitally signs the input data with the certificate provided. Certificates are provided by specifying the certificate property. The include_certificate property allows you to specify whether to include the certificate when signing the message.

sign_and_encrypt Method

Signs and encrypts the current message.

Syntax

def sign_and_encrypt() -> None: ...

Remarks

This method both signs and encrypts the input message into a single PKCS encoded envelope.

Please note that the message headers, including the Sender, Recipient(s), and Subject, are not encrypted. If this is sensitive information, consider including these headers in the message body as a MIME entity, and providing other headers for the S/MIME wrapper.

on_connection_status Event

This event is fired to indicate changes in the connection state.

Syntax

class SHTMLMailerConnectionStatusEventParams(object):
  @property
  def connection_event() -> str: ...

  @property
  def status_code() -> int: ...

  @property
  def description() -> str: ...

# In class SHTMLMailer:
@property
def on_connection_status() -> Callable[[SHTMLMailerConnectionStatusEventParams], None]: ...
@on_connection_status.setter
def on_connection_status(event_hook: Callable[[SHTMLMailerConnectionStatusEventParams], None]) -> None: ...

Remarks

The on_connection_status event is fired when the connection state changes: for example, completion of a firewall or proxy connection or completion of a security handshake.

The ConnectionEvent parameter indicates the type of connection event. Values may include the following:

on_end_transfer Event

This event is fired when the message text completes transferring.

Syntax

class SHTMLMailerEndTransferEventParams(object):
  @property
  def direction() -> int: ...

# In class SHTMLMailer:
@property
def on_end_transfer() -> Callable[[SHTMLMailerEndTransferEventParams], None]: ...
@on_end_transfer.setter
def on_end_transfer(event_hook: Callable[[SHTMLMailerEndTransferEventParams], None]) -> None: ...

Remarks

If message_text is not empty, the on_end_transfer event is fired when the message_text finishes transferring from the local host to the mail_server. If message_text is empty, the event is not fired.

If a file is attached to the message_text via the attached_file property, then on_end_transfer fires again when the file finishes transferring. For more information, go to the description of the attached_file property.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_error Event

Information about errors during data delivery.

Syntax

class SHTMLMailerErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class SHTMLMailer:
@property
def on_error() -> Callable[[SHTMLMailerErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[SHTMLMailerErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_pi_trail Event

Traces the commands sent to the mail server, and the respective replies.

Syntax

class SHTMLMailerPITrailEventParams(object):
  @property
  def direction() -> int: ...

  @property
  def message() -> str: ...

# In class SHTMLMailer:
@property
def on_pi_trail() -> Callable[[SHTMLMailerPITrailEventParams], None]: ...
@on_pi_trail.setter
def on_pi_trail(event_hook: Callable[[SHTMLMailerPITrailEventParams], None]) -> None: ...

Remarks

The on_pi_trail event is useful for debugging purposes. It shows all the interaction between the client and the server, line by line, except for message header and body transfers.

The Message parameter contains the full text of the message. The Direction parameter shows the originator of the message:

on_ssl_server_authentication Event

Fired after the server presents its certificate to the client.

Syntax

class SHTMLMailerSSLServerAuthenticationEventParams(object):
  @property
  def cert_encoded() -> bytes: ...

  @property
  def cert_subject() -> str: ...

  @property
  def cert_issuer() -> str: ...

  @property
  def status() -> str: ...

  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...

# In class SHTMLMailer:
@property
def on_ssl_server_authentication() -> Callable[[SHTMLMailerSSLServerAuthenticationEventParams], None]: ...
@on_ssl_server_authentication.setter
def on_ssl_server_authentication(event_hook: Callable[[SHTMLMailerSSLServerAuthenticationEventParams], None]) -> None: ...

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

on_ssl_status Event

Shows the progress of the secure connection.

Syntax

class SHTMLMailerSSLStatusEventParams(object):
  @property
  def message() -> str: ...

# In class SHTMLMailer:
@property
def on_ssl_status() -> Callable[[SHTMLMailerSSLStatusEventParams], None]: ...
@on_ssl_status.setter
def on_ssl_status(event_hook: Callable[[SHTMLMailerSSLStatusEventParams], None]) -> None: ...

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

on_start_transfer Event

Fired when the message text starts transferring.

Syntax

class SHTMLMailerStartTransferEventParams(object):
  @property
  def direction() -> int: ...

# In class SHTMLMailer:
@property
def on_start_transfer() -> Callable[[SHTMLMailerStartTransferEventParams], None]: ...
@on_start_transfer.setter
def on_start_transfer(event_hook: Callable[[SHTMLMailerStartTransferEventParams], None]) -> None: ...

Remarks

If message_text is not empty, the on_start_transfer event is fired when the message_text starts transferring from the local host to the mail_server. If message_text is empty, the event is not fired.

If a file is attached to the message_text via the attached_file property, then on_start_transfer fires again when the file starts transferring. Please go to the description of the attached_file property for more information.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_transfer Event

Fired while the message text gets transferred to MailServer .

Syntax

class SHTMLMailerTransferEventParams(object):
  @property
  def direction() -> int: ...

  @property
  def bytes_transferred() -> int: ...

  @property
  def percent_done() -> int: ...

  @property
  def text() -> bytes: ...

# In class SHTMLMailer:
@property
def on_transfer() -> Callable[[SHTMLMailerTransferEventParams], None]: ...
@on_transfer.setter
def on_transfer(event_hook: Callable[[SHTMLMailerTransferEventParams], None]) -> None: ...

Remarks

One or more on_transfer events are fired during message delivery. Messages consist of message_text and an optional attached_file. The BytesTransferred parameter shows the number of bytes sent starting from the beginning of message_text and/or attached_file.

Text contains the current portion of the message being sent.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

Note: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

SHTMLMailer Config Settings

HTMLMailer Config Settings

SMTP Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Base Config Settings

SHTMLMailer Errors

HTMLMailer Errors

The class may also return one of the following error codes, which are inherited from other classes.

MIME Errors

SMTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

SSL Errors

TCP/IP Errors