IPWorks S/MIME 2020 Python Edition

Questions / Feedback?

SIMAP Class

Properties   Methods   Events   Configuration Settings   Errors  

The SIMAP Class is used to communicate with IMAP servers using the IMAP (Internet Message Access) protocol.

Syntax

class ipworkssmime.SIMAP

Remarks

The SIMAP Class is the S/MIME enabled equivalent of the IPWorks IMAP class. In addition to standard IMAP functions the SIMAP class can decrypt and/or verify message signatures. The methods and properties for decrypting, and verifying signatures are identical to those provided with the S/MIME Class. When attempting to verify a signed message or when decrypting a message call the decrypt, verify_signature, or decrypt_and_verify_signature methods and the resulting text will be replaced in message.

The SIMAP Class implements a standard IMAP client as specified in RFC 1730 and RFC 2060.

The first step in using the class is specifying a mail_server, a user to connect as, and a password to authenticate with. After that, one or more requests may be sent to the server via the class's methods. Results are retrieved through events and a number of key properties.

Normally, after connecting to the server a mailbox is selected (or examined) using the examine_mailbox method. After the mailbox is selected, message_count and recent_message_count show the number of messages in the mailbox, and mailbox_flags show the flags pertaining to the mailbox.

A number of operations may be performed by the server in response to commands sent via the class's methods. The primary arguments for most commands are the mailbox property and the message_set property. The message_set property denotes either a single message, or a range of messages. Other arguments are specified through other properties such as sort_criteria, message_flags, etc.

Responses are received through events such as on_message_info, on_mailbox_list, and also reflected to properties such as message_text, message_subject, etc.

The on_message_part event describes the MIME structure of retrieved messages. One on_message_part event is fired for every message part, giving information about the particular part. Later on, message parts may be retrieved separately through the fetch_message_part method. This speeds up processing by avoiding the need to retrieve full messages from the server.

The on_pi_trail event traces the interaction between the client and the server. It includes all exchanges except for transfers of messages, message parts, and message headers.

Property List


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

auth_mechanismThe authentication mechanism to be used when connecting to the mail server.
auto_decode_partsDetermines whether to automatically decode message parts.
cert_encodedThe certificate (PEM/base64 encoded).
cert_storeThe name of the certificate store for the client certificate.
cert_store_passwordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
cert_store_typeThe type of certificate store for this certificate.
cert_subjectThe subject of the certificate used for client authentication.
commandCan be used to send additional commands directly to the server.
connectedShows whether the class is connected.
end_byteThe byte index of the position where the transfer should end.
firewall_auto_detectThis property tells the class whether or not to automatically detect and use firewall system settings, if available.
firewall_typeThis property determines the type of firewall to connect through.
firewall_hostThis property contains the name or IP address of firewall (optional).
firewall_passwordThis property contains a password if authentication is to be used when connecting through the firewall.
firewall_portThis property contains the TCP port for the firewall Host .
firewall_userThis property contains a user name if authentication is to be used connecting through a firewall.
idleThe current status of the class.
last_replyThe last reply from the server.
local_fileThe path to a local file for downloading the message body. If the file exists, it is overwritten (optional).
local_hostThe name of the local host or user-assigned IP interface through which connections are initiated or accepted.
mailboxName of the mailbox selected on the server.
mailbox_flagsDefines flags in the selected mailbox.
mailbox_list_countThe number of records in the MailboxList arrays.
mailbox_list_flagsThe mailbox flags in a mailbox listing.
mailbox_list_nameThe mailbox name in a mailbox listing.
mailbox_list_separatorThe Separator property contains the character that separates the different parts in the mailbox path hierarchy.
mail_portThe port of the IMAP server (default is 143).
mail_serverThe name or address of the mail server (IMAP server).
messageProvides the raw message content.
message_content_encodingThe ContentEncoding of the selected message.
message_content_typeThe ContentType of the message.
message_countThe total number of messages on the Mailbox .
message_dateThe time the message was created.
message_delivery_timeThe time the message was delivered to the mail server.
message_encryptedWhether or not the current message is encrypted.
message_flagsContains the flags of the current message.
message_fromThe address of the author of the message.
message_header_countThe number of records in the MessageHeader arrays.
message_header_fieldThis property contains the name of the HTTP header (same case as it is delivered).
message_header_valueThis property contains the header contents.
message_headers_stringString version of RFC822-encoded headers of the message.
message_idThe message identifier of the current message.
message_info_countThe number of records in the MessageInfo arrays.
message_info_dateThe date of a message in a message info listing.
message_info_flagsMessage flag in a message info listing.
message_info_fromThe sender of a message in a message info listing.
message_info_message_idThe unique identifier of a message in a message info listing.
message_info_sizeThe size of a message in a message info listing.
message_info_subjectThe subject of a message in a message info listing.
message_in_reply_toThe unique message identifier of the message this one is in reply to.
message_net_idThe globally unique identifier of the message.
message_part_countThe number of records in the MessagePart arrays.
message_part_content_dispositionThis property shows the value of the Content-Disposition header of the message part.
message_part_content_encodingThis property shows how the data is encoded.
message_part_content_idThis property shows the value of the Content-Id header of the message part.
message_part_content_typeThis property shows the type of data contained in the message part.
message_part_filenameThis property shows the filename corresponding to the part (if the part was included in the message as an attached file).
message_part_idThis property contains the identifier of a part listing which may be identified in other parts or messages.
message_part_multipart_modeThis property shows how this part relates to the message's whole multipart structure ('mixed', 'alternative', etc.
message_part_parametersThis property contains the additional parameters passed to the ContentType header such as the part charset etc.
message_part_sizeThis property contains the size of a part in a message part listing.
message_recipient_countThe number of records in the MessageRecipient arrays.
message_recipient_addressThis property contains the email address of the recipient.
message_recipient_nameThis property contains name of the recipient.
message_recipient_optionsThis property contains the recipient sending options (used only by SMTP).
message_recipient_typeThis property contains the recipient type: To, Cc, or BCc.
message_reply_toEmail address(s) where replies to the message should be sent.
message_senderThe address of the sender of the message.
message_setThe set of messages to operate on.
message_signedWhether or not the current message is signed.
message_sizeThe size of the selected message.
message_subjectThe subject of the message.
message_textThe body of the retrieved message.
overwriteIndicates whether or not the class should overwrite files during transfer.
passwordThe password used to authenticate to the MailServer .
peek_modeWhen set to True, the message Seen flag is not changed during reading.
recent_message_countNumber of new messages in the Mailbox .
signer_cert_encodedThe certificate (PEM/base64 encoded).
signer_cert_issuerThe issuer of the certificate.
signer_cert_serial_numberThe serial number of the certificate encoded as a string.
signer_cert_storeThe name of the certificate store for the client certificate.
signer_cert_store_passwordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
signer_cert_store_typeThe type of certificate store for this certificate.
signer_cert_subjectThe subject of the certificate used for client authentication.
signer_cert_chain_countThe number of records in the SignerCertChain arrays.
signer_cert_chain_encodedThe certificate (PEM/base64 encoded).
signing_algorithmTextual description of the signature hash algorithm.
sort_criteriaSorts criteria to use for message retrieval operations.
ssl_accept_server_cert_encodedThe certificate (PEM/base64 encoded).
ssl_cert_encodedThe certificate (PEM/base64 encoded).
ssl_cert_storeThe name of the certificate store for the client certificate.
ssl_cert_store_passwordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
ssl_cert_store_typeThe type of certificate store for this certificate.
ssl_cert_subjectThe subject of the certificate used for client authentication.
ssl_enabledWhether TLS/SSL is enabled.
ssl_server_cert_encodedThe certificate (PEM/base64 encoded).
ssl_start_modeDetermines how the class starts the SSL negotiation.
start_byteThe byte index of the position where the transfer should start.
timeoutA timeout for the class.
uid_modeIf true, permanent message identifiers are used instead of the default temporary identifiers.
uid_validityThe UIDValidity parameter sent from the server in response to SelectMailbox command.
userThe user name used to authenticate to the MailServer .

Method List


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

add_message_flagsAdds the specified flags to the messages specified by MessageSet .
append_to_mailboxAppends the message in MessageText to the mailbox specified by Mailbox .
check_mailboxSends a 'CHECK' command to the server.
close_mailboxRemoves all messages marked with 'Deleted' flag from the currently selected mailbox and unselect mailbox.
configSets or retrieves a configuration setting.
connectConnects to an IMAP server.
copy_to_mailboxCopies the messages specified by MessageSet to the mailbox specified by Mailbox .
create_mailboxCreates a new mailbox specified by Mailbox .
decryptDecrypts the current Message .
decrypt_and_verify_signatureDecrypts and verifies the signature of the current message.
delete_from_mailboxMarks the messages specified by MessageSet as deleted.
delete_mailboxDeletes a mailbox specified by Mailbox .
delete_mailbox_aclDeletes mailbox access control rights for a specific user.
disconnectDisconnects from an IMAP server.
do_eventsProcesses events from the internal message queue.
examine_mailboxSelects a Mailbox (Read-only mode).
expunge_mailboxRemoves all messages marked with 'Deleted' flag from the currently selected mailbox.
fetch_message_headersRetrieves the message headers of messages specified by the MessageSet property.
fetch_message_infoRetrieves information about messages specified by the MessageSet property.
fetch_message_partRetrieves the message part specified by PartID.
fetch_message_part_headersRetrieves the headers of message part specified by PartID.
fetch_message_textRetrieves the message text of messages specified by the MessageSet property.
get_mailbox_aclRetrieves mailbox access control rights.
interruptInterrupt the current method.
list_mailboxesLists all mailboxes matching all criteria in the Mailbox property.
list_subscribed_mailboxesLists all subscribed mailboxes matching all criteria in the Mailbox property.
localize_dateConverts a valid RFC 822 message date to local date and time.
move_to_mailboxMoves the messages specified by MessageSet to the mailbox specified by Mailbox .
noopSends a 'NOOP' command to the server.
rename_mailboxChange the name of Mailbox to NewName .
resetReset the class.
reset_message_flagsReplaces the flags of the messages specified by MessageSet with the flags specified by MessageFlags .
search_mailboxSearch selected mailbox for specified text.
select_mailboxSelect a Mailbox.
set_mailbox_aclSets mailbox access control rights for a specific user.
start_idleBegins idling.
stop_idleStops idling.
subscribe_mailboxSubscribes to the mailbox specified by Mailbox .
unset_message_flagsRemoves the flags specified by MessageFlags from the messages specified by MessageSet .
unsubscribe_mailboxUnsubscribes from the mailbox specified by Mailbox .
verify_signatureVerifies the signature of the current message.

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.

on_connection_statusFired to indicate changes in connection state.
on_end_transferFired when the message or the part data finishes transferring.
on_errorInformation about errors during data delivery.
on_headerFired every time a header line comes in.
on_idle_infoFires whenever responses from the server are received while idling.
on_mailbox_aclFires for each set of access control rights returned by the server.
on_mailbox_listFired for each mailbox received through the ListMailboxes and ListSubscribedMailboxes methods.
on_message_infoFired with information for the message(s) retrieved by the server.
on_message_partFired for each message part when FetchMessageInfo is called.
on_pi_trailTraces the commands sent to the mail server, and the respective replies.
on_ssl_server_authenticationFired after the server presents its certificate to the client.
on_ssl_statusShows the progress of the secure connection.
on_start_transferFired when the message or the part data starts transferring.
on_transferFired while the message gets transferred from the MailServer .

Configuration Settings


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

RefetchHeadersWhether or not to re-fetch the message headers when querying MessageEncrypted or MessageSigned.
AlwaysReturnUIDsInstructs the server to return UIDs even if not in UIDMode.
AppendToMailboxDateTimeSpecifies the date-time parameter used in the initial APPEND request.
AuthorizationIdentityThe value to use as the authorization identity when SASL authentication is used.
AutoDecodeSubjectInstructs the class to automatically decode message subjects.
AutoDecodeTextWhether to decode MessageText when AutoDecodeParts is True.
FetchAfterSearchDetermines if messages matching the SearchCriteria are fetched after calling SearchMailbox.
FetchTextAndHeadersSpecifies whether the message body and headers are fetched in a single request.
IncludeHeadersInstructs the class to include the headers in the LocalFile.
MaskSensitiveWhether sensitive properties should be masked when logging.
SendIDCommandInstructs class to send the ID command if the server advertises support for it.
UTF7MailboxNamesSpecifies whether or not to automatically encode and decode UTF-7 mailbox names.
ConnectionTimeoutSets a separate timeout value for establishing a connection.
FirewallAutoDetectTells the class whether or not to automatically detect and use firewall system settings, if available.
FirewallHostName or IP address of firewall (optional).
FirewallPasswordPassword to be used if authentication is to be used when connecting through the firewall.
FirewallPortThe TCP port for the FirewallHost;.
FirewallTypeDetermines the type of firewall to connect through.
FirewallUserA user name if authentication is to be used connecting through a firewall.
KeepAliveIntervalThe retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
KeepAliveTimeThe inactivity time in milliseconds before a TCP keep-alive packet is sent.
LingerWhen set to True, connections are terminated gracefully.
LingerTimeTime in seconds to have the connection linger.
LocalHostThe name of the local host through which connections are initiated or accepted.
LocalPortThe port in the local host where the class binds.
MaxLineLengthThe maximum amount of data to accumulate when no EOL is found.
MaxTransferRateThe transfer rate limit in bytes per second.
ProxyExceptionsListA semicolon separated list of hosts and IPs to bypass when using a proxy.
TCPKeepAliveDetermines whether or not the keep alive socket option is enabled.
TcpNoDelayWhether or not to delay when sending packets.
UseIPv6Whether to use IPv6.
LogSSLPacketsControls whether SSL packets are logged when using the internal security API.
OpenSSLCADirThe path to a directory containing CA certificates.
OpenSSLCAFileName of the file containing the list of CA's trusted by your application.
OpenSSLCipherListA string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedDataThe data to seed the pseudo random number generator (PRNG).
ReuseSSLSessionDetermines if the SSL session is reused.
SSLCACertFilePathsThe paths to CA certificate files on Unix/Linux.
SSLCACertsA newline separated list of CA certificate to use during SSL client authentication.
SSLCheckCRLWhether to check the Certificate Revocation List for the server certificate.
SSLCipherStrengthThe minimum cipher strength used for bulk encryption.
SSLEnabledCipherSuitesThe cipher suite to be used in an SSL negotiation.
SSLEnabledProtocolsUsed to enable/disable the supported security protocols.
SSLEnableRenegotiationWhether the renegotiation_info SSL extension is supported.
SSLIncludeCertChainWhether the entire certificate chain is included in the SSLServerAuthentication event.
SSLProviderThe name of the security provider to use.
SSLSecurityFlagsFlags that control certificate verification.
TLS12SignatureAlgorithmsDefines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.
TLS12SupportedGroupsThe supported groups for ECC.
TLS13KeyShareGroupsThe groups for which to pregenerate key shares.
TLS13SignatureAlgorithmsThe allowed certificate signature algorithms.
TLS13SupportedGroupsThe supported groups for (EC)DHE key exchange.
AbsoluteTimeoutDetermines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallDataUsed to send extra data to the firewall.
InBufferSizeThe size in bytes of the incoming queue of the socket.
OutBufferSizeThe size in bytes of the outgoing queue of the socket.
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
ProcessIdleEventsWhether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillisThe length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPITells the class whether or not to use the system security libraries or an internal implementation.

Copyright (c) 2021 /n software inc. - All rights reserved.
IPWorks S/MIME 2020 Python Edition - Version 20.0 [Build 7941]