PIMAP Class

Properties Methods Events Configuration Settings Errors

The PIMAP class is used to communicate with IMAP servers to retrieve and process OpenPGP encrypted and/or signed messages and any attachments.

Syntax

class ipworksopenpgp.PIMAP

Remarks

The PIMAP class offers an easy-to-use interface: it implements a standard IMAP client, as specified in RFC 1730 and RFC 2060, and supports decrypting and verifying signatures of encrypted and signed emails using OpenPGP. Additionally, it enables you to create messages bound for multiple recipients with different keys, simultaneously encrypt and compress with the most popular compression algorithms, and control other aspects such as the encrypting algorithm to use.

Connect to a Mail Server

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.

Examine a Mailbox

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 shows 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 and on_mailbox_list, and are also reflected in properties such as message_text, message_subject, etc.

Decrypt

To process an encrypted or signed message, first retrieve the message text and headers by calling fetch_message_headers and fetch_message_text. To decrypt a message specify the private key to be used for decryption by setting the Key* properties. For instance:

PIMAP1.KeyCount = 1
PIMAP1.KeyKeyring(0) = "c:\my_keyring_dir"
PIMAP1.KeyUserId(0) = "recipient@nsoftware.com"
PIMAP1.KeyPassphrase(0) = "password"

The specified private key will be used to decrypt the message when calling decrypt.

Verify

To verify the signature of a message specify the public key to be used for signature verification by setting the SignerKey* properties. For instance:

PIMAP1.SignerKeyCount = 1
PIMAP1.SignerKeyKeyring(0) = "c:\my_keyring_dir"
PIMAP1.SignerKeyUserId(0) = "sender@nsoftware.com"

The specified public key will be used to verify the signature when calling verify_signature. To decrypt and verify in one step call decrypt_and_verify_signature.

Retrieve MIME Message Parts

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.

Trace Client and Server Communication

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_mechanism	The authentication mechanism to be used when connecting to the mail server.
auto_decode_parts	Determines whether to automatically decode message parts.
command	Can be used to send additional commands directly to the server.
connected	Shows whether the class is connected.
end_byte	The byte index of the position where the transfer should end.
firewall_auto_detect	This property tells the class whether or not to automatically detect and use firewall system settings, if available.
firewall_type	This property determines the type of firewall to connect through.
firewall_host	This property contains the name or IP address of firewall (optional).
firewall_password	This property contains a password if authentication is to be used when connecting through the firewall.
firewall_port	This property contains the TCP port for the firewall Host .
firewall_user	This property contains a user name if authentication is to be used connecting through a firewall.
idle	The current status of the class.
key_count	The number of records in the Key arrays.
key_encoded	The key.
key_keyring	The location of the keyring.
key_passphrase	The passphrase for the key's secret key (if any).
key_user_id	The user Id of the key.
last_reply	The last reply from the server.
local_host	The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
mailbox	Name of the mailbox selected on the server.
mailbox_flags	Defines flags in the selected mailbox.
mailbox_list_count	The number of records in the MailboxList arrays.
mailbox_list_flags	The mailbox flags in a mailbox listing.
mailbox_list_name	The mailbox name in a mailbox listing.
mailbox_list_separator	The Separator property contains the character that separates the different parts in the mailbox path hierarchy.
mail_port	The port of the IMAP server (default is 143).
mail_server	The name or address of the mail server (IMAP server).
message	Provides the raw message content.
message_content_encoding	The ContentEncoding of the selected message.
message_content_type	The ContentType of the message.
message_count	The total number of messages on the Mailbox .
message_date	The time the message was created.
message_delivery_time	The time the message was delivered to the mail server.
message_flags	Contains the flags of the current message.
message_from	The address of the author of the message.
message_header_count	The number of records in the MessageHeader arrays.
message_header_field	This property contains the name of the HTTP header (same case as it is delivered).
message_header_value	This property contains the header contents.
message_headers_string	String version of RFC822-encoded headers of the message.
message_id	The message identifier of the current message.
message_info_count	The number of records in the MessageInfo arrays.
message_info_date	The date of a message in a message info listing.
message_info_flags	Message flag in a message info listing.
message_info_from	The sender of a message in a message info listing.
message_info_message_id	The unique identifier of a message in a message info listing.
message_info_size	The size of a message in a message info listing.
message_info_subject	The subject of a message in a message info listing.
message_in_reply_to	The unique message identifier of the message this one is in reply to.
message_net_id	The globally unique identifier of the message.
message_part_count	The number of records in the MessagePart arrays.
message_part_content_disposition	This property shows the value of the Content-Disposition header of the message part.
message_part_content_encoding	This property shows how the data is encoded.
message_part_content_id	This property shows the value of the Content-Id header of the message part.
message_part_content_type	This property shows the type of data contained in the message part.
message_part_filename	This property shows the filename corresponding to the part (if the part was included in the message as an attached file).
message_part_id	This property contains the identifier of a part listing which may be identified in other parts or messages.
message_part_multipart_mode	This property shows how this part relates to the message's whole multipart structure ('mixed', 'alternative', etc.
message_part_parameters	This property contains the additional parameters passed to the ContentType header such as the part charset etc.
message_part_size	This property contains the size of a part in a message part listing.
message_recipient_count	The number of records in the MessageRecipient arrays.
message_recipient_address	This property contains the email address of the recipient.
message_recipient_name	This property contains name of the recipient.
message_recipient_options	This property contains the recipient sending options (used only by SMTP).
message_recipient_type	This property contains the recipient type: To, Cc, or BCc.
message_reply_to	Email address(s) where replies to the message should be sent.
message_sender	The address of the sender of the message.
message_set	The set of messages to operate on.
message_size	The size of the selected message.
message_subject	The subject of the message.
message_text	The body of the retrieved message.
overwrite	Indicates whether or not the class should overwrite files during transfer.
password	The password used to authenticate to the MailServer .
peek_mode	When set to True, the message Seen flag is not changed during reading.
recent_message_count	Number of new messages in the Mailbox .
signer_key_count	The number of records in the SignerKey arrays.
signer_key_encoded	The key.
signer_key_keyring	The location of the keyring.
signer_key_user_id	The user Id of the key.
sort_criteria	Sorts criteria to use for message retrieval operations.
ssl_accept_server_cert_encoded	The certificate (PEM/base64 encoded).
ssl_cert_encoded	The certificate (PEM/base64 encoded).
ssl_cert_store	The name of the certificate store for the client certificate.
ssl_cert_store_password	If 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_type	The type of certificate store for this certificate.
ssl_cert_subject	The subject of the certificate used for client authentication.
ssl_enabled	Whether TLS/SSL is enabled.
ssl_server_cert_encoded	The certificate (PEM/base64 encoded).
ssl_start_mode	Determines how the class starts the SSL negotiation.
start_byte	The byte index of the position where the transfer should start.
timeout	A timeout for the class.
uid_mode	If true, permanent message identifiers are used instead of the default temporary identifiers.
uid_validity	The UIDValidity parameter sent from the server in response to SelectMailbox command.
user	The 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_flags	Adds the specified flags to the messages specified by MessageSet .
append_to_mailbox	Appends the message in MessageText to the mailbox specified by Mailbox .
check_mailbox	Sends a 'CHECK' command to the server.
close_mailbox	Removes all messages marked with 'Deleted' flag from the currently selected mailbox and unselect mailbox.
config	Sets or retrieves a configuration setting.
connect	Connects to an IMAP server.
copy_to_mailbox	Copies the messages specified by MessageSet to the mailbox specified by Mailbox .
create_mailbox	Creates a new mailbox specified by Mailbox .
decrypt	Decrypts the message.
decrypt_and_verify_signature	Decrypts and verifies the signature of the message.
delete_from_mailbox	Marks the messages specified by MessageSet as deleted.
delete_mailbox	Deletes a mailbox specified by Mailbox .
delete_mailbox_acl	Deletes mailbox access control rights for a specific user.
disconnect	Disconnects from an IMAP server.
do_events	Processes events from the internal message queue.
examine_mailbox	Selects a Mailbox (Read-only mode).
expunge_mailbox	Removes all messages marked with 'Deleted' flag from the currently selected mailbox.
fetch_message_headers	Retrieves the message headers of messages specified by the MessageSet property.
fetch_message_info	Retrieves information about messages specified by the MessageSet property.
fetch_message_part	Retrieves the message part specified by PartID.
fetch_message_part_headers	Retrieves the headers of message part specified by PartID.
fetch_message_text	Retrieves the message text of messages specified by the MessageSet property.
get_mailbox_acl	Retrieves mailbox access control rights.
interrupt	Interrupt the current method.
list_mailboxes	Lists all mailboxes matching all criteria in the Mailbox property.
list_subscribed_mailboxes	Lists all subscribed mailboxes matching all criteria in the Mailbox property.
localize_date	Converts a valid RFC 822 message date to local date and time.
move_to_mailbox	Moves the messages specified by MessageSet to the mailbox specified by Mailbox .
noop	Sends a 'NOOP' command to the server.
rename_mailbox	Change the name of Mailbox to NewName .
reset_message_flags	Replaces the flags of the messages specified by MessageSet with the flags specified by MessageFlags .
search_mailbox	Search selected mailbox for specified text.
select_mailbox	Select a Mailbox.
set_mailbox_acl	Sets mailbox access control rights for a specific user.
start_idle	Begins idling.
stop_idle	Stops idling.
subscribe_mailbox	Subscribes to the mailbox specified by Mailbox .
unset_message_flags	Removes the flags specified by MessageFlags from the messages specified by MessageSet .
unsubscribe_mailbox	Unsubscribes from the mailbox specified by Mailbox .
verify_signature	Verifies 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_status	Fired to indicate changes in connection state.
on_end_transfer	Fired when the message or the part data finishes transferring.
on_error	Information about errors during data delivery.
on_header	Fired every time a header line comes in.
on_idle_info	Fires whenever responses from the server are received while idling.
on_key_passphrase	Fired if the passphrase of current key is incorrect or empty.
on_mailbox_acl	Fires for each set of access control rights returned by the server.
on_mailbox_list	Fired for each mailbox received through the ListMailboxes and ListSubscribedMailboxes methods.
on_message_info	Fired with information for the message(s) retrieved by the server.
on_message_part	Fired for each message part when FetchMessageInfo is called.
on_pi_trail	Traces the commands sent to the mail server, and the respective replies.
on_progress	Fired as progress is made.
on_recipient_info	Fired for each recipient key of the encrypted message.
on_signature_info	Fired during verification of the signed message.
on_ssl_server_authentication	Fired after the server presents its certificate to the client.
on_ssl_status	Shows the progress of the secure connection.
on_start_transfer	Fired when the message or the part data starts transferring.
on_status	Shows the progress of the operation.
on_transfer	Fired while the message gets transferred from the MailServer .
on_verification_status	Fired after verification of the signed message.

Configuration Settings

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


Comment	The OpenPGP message comment.
LogLevel	Specifies the level of detail that is logged.
ProcessAttachments	Whether or not to process attachments.
RequireValidSignature	Specifies if an invalid signature is considered an error condition.
SymmetricPassphrase	The password used for symmetric encryption or decryption.
VersionHeader	The Version header value in the ASCII armored OpenPGP message.
RefetchHeaders	Whether or not to re-fetch the message headers when querying MessageEncrypted or MessageSigned.
AlwaysReturnUIDs	Instructs the server to return UIDs even if not in UIDMode.
AppendToMailboxDateTime	Specifies the date-time parameter used in the initial APPEND request.
AuthorizationIdentity	The value to use as the authorization identity when SASL authentication is used.
AutoDecodeSubject	Instructs the class to automatically decode message subjects.
AutoDecodeText	Whether to decode MessageText when AutoDecodeParts is True.
FetchAfterSearch	Determines if messages matching the SearchCriteria are fetched after calling SearchMailbox.
FetchTextAndHeaders	Specifies whether the message body and headers are fetched in a single request.
IncludeHeaders	Instructs the class to include the headers in the LocalFile.
MaskSensitive	Whether sensitive properties should be masked when logging.
SendIDCommand	Instructs class to send the ID command if the server advertises support for it.
UTF7MailboxNames	Specifies whether or not to automatically encode and decode UTF-7 mailbox names.
ConnectionTimeout	Sets a separate timeout value for establishing a connection.
FirewallAutoDetect	Tells the class whether or not to automatically detect and use firewall system settings, if available.
FirewallHost	Name or IP address of firewall (optional).
FirewallPassword	Password to be used if authentication is to be used when connecting through the firewall.
FirewallPort	The TCP port for the FirewallHost;.
FirewallType	Determines the type of firewall to connect through.
FirewallUser	A user name if authentication is to be used connecting through a firewall.
KeepAliveInterval	The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
KeepAliveTime	The inactivity time in milliseconds before a TCP keep-alive packet is sent.
Linger	When set to True, connections are terminated gracefully.
LingerTime	Time in seconds to have the connection linger.
LocalHost	The name of the local host through which connections are initiated or accepted.
LocalPort	The port in the local host where the class binds.
MaxLineLength	The maximum amount of data to accumulate when no EOL is found.
MaxTransferRate	The transfer rate limit in bytes per second.
ProxyExceptionsList	A semicolon separated list of hosts and IPs to bypass when using a proxy.
TCPKeepAlive	Determines whether or not the keep alive socket option is enabled.
TcpNoDelay	Whether or not to delay when sending packets.
UseIPv6	Whether to use IPv6.
LogSSLPackets	Controls whether SSL packets are logged when using the internal security API.
OpenSSLCADir	The path to a directory containing CA certificates.
OpenSSLCAFile	Name of the file containing the list of CA's trusted by your application.
OpenSSLCipherList	A string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedData	The data to seed the pseudo random number generator (PRNG).
ReuseSSLSession	Determines if the SSL session is reused.
SSLCACertFilePaths	The paths to CA certificate files on Unix/Linux.
SSLCACerts	A newline separated list of CA certificate to use during SSL client authentication.
SSLCheckCRL	Whether to check the Certificate Revocation List for the server certificate.
SSLCipherStrength	The minimum cipher strength used for bulk encryption.
SSLEnabledCipherSuites	The cipher suite to be used in an SSL negotiation.
SSLEnabledProtocols	Used to enable/disable the supported security protocols.
SSLEnableRenegotiation	Whether the renegotiation_info SSL extension is supported.
SSLIncludeCertChain	Whether the entire certificate chain is included in the SSLServerAuthentication event.
SSLNegotiatedCipher	Returns the negotiated ciphersuite.
SSLNegotiatedCipherStrength	Returns the negotiated ciphersuite strength.
SSLNegotiatedCipherSuite	Returns the negotiated ciphersuite.
SSLNegotiatedKeyExchange	Returns the negotiated key exchange algorithm.
SSLNegotiatedKeyExchangeStrength	Returns the negotiated key exchange algorithm strength.
SSLNegotiatedVersion	Returns the negotiated protocol version.
SSLProvider	The name of the security provider to use.
SSLSecurityFlags	Flags that control certificate verification.
SSLServerCACerts	A newline separated list of CA certificate to use during SSL server certificate validation.
TLS12SignatureAlgorithms	Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.
TLS12SupportedGroups	The supported groups for ECC.
TLS13KeyShareGroups	The groups for which to pregenerate key shares.
TLS13SignatureAlgorithms	The allowed certificate signature algorithms.
TLS13SupportedGroups	The supported groups for (EC)DHE key exchange.
AbsoluteTimeout	Determines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallData	Used to send extra data to the firewall.
InBufferSize	The size in bytes of the incoming queue of the socket.
OutBufferSize	The size in bytes of the outgoing queue of the socket.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
ProcessIdleEvents	Whether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPI	Tells the class whether or not to use the system security libraries or an internal implementation.