MailWriter Class

Properties   Methods   Events   Config Settings   Errors  

The MailWriter class composes, encrypts, and signs e-mail messages.

Syntax

class secureblackbox.MailWriter

Remarks

Use MailWriter to compose, sign, and encrypt e-mail messages, and prepare them for sending or saving.

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.

attach_encoding Property

The encoding to be applied to the attachments.

Syntax

def get_attach_encoding() -> int: ...
def set_attach_encoding(value: int) -> None: ...

attach_encoding = property(get_attach_encoding, set_attach_encoding)

Default Value

0

Remarks

Use this property to specify the encoding method for the attached files.

attach_count Property

The number of records in the Attach arrays.

Syntax

def get_attach_count() -> int: ...
def set_attach_count(value: int) -> None: ...

attach_count = property(get_attach_count, set_attach_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• attach_content_subtype
• attach_content_type
• attach_creation_date
• attach_data
• attach_description
• attach_filename
• attach_handle
• attach_id
• attach_modification_date
• attach_read_date
• attach_size

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

attach_content_subtype Property

Contains the content subtype of the attachment.

Syntax

def get_attach_content_subtype(attach_index: int) -> str: ...
def set_attach_content_subtype(attach_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the content subtype of the attachment.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_content_type Property

Contain the content type of the attachment.

Syntax

def get_attach_content_type(attach_index: int) -> str: ...
def set_attach_content_type(attach_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contain the content type of the attachment.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_creation_date Property

The creation date.

Syntax

def get_attach_creation_date(attach_index: int) -> str: ...
def set_attach_creation_date(attach_index: int, value: str) -> None: ...

Default Value

""

Remarks

The creation date.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_data Property

The content of the attachment.

Syntax

def get_attach_data(attach_index: int) -> bytes: ...
def set_attach_data(attach_index: int, value: bytes) -> None: ...

Remarks

The content of the attachment.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_description Property

Textual description of the attachment.

Syntax

def get_attach_description(attach_index: int) -> str: ...
def set_attach_description(attach_index: int, value: str) -> None: ...

Default Value

""

Remarks

Textual description of the attachment.

This property maps to the Content-Description e-mail header field. Although the field is optional, the ability to associate descriptive information with a given body is often desirable. One example is specifying the title of an image using this property.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_filename Property

Specifies the name of the attachment file.

Syntax

def get_attach_filename(attach_index: int) -> str: ...
def set_attach_filename(attach_index: int, value: str) -> None: ...

Default Value

""

Remarks

Specifies the name of the attachment file.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_handle Property

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

def get_attach_handle(attach_index: int) -> int: ...
def set_attach_handle(attach_index: int, value: int) -> None: ...

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_id Property

Contains the attachment's unique identifier.

Syntax

def get_attach_id(attach_index: int) -> str: ...
def set_attach_id(attach_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the attachment's unique identifier.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_modification_date Property

Specifies the date and time of the file's last modification.

Syntax

def get_attach_modification_date(attach_index: int) -> str: ...
def set_attach_modification_date(attach_index: int, value: str) -> None: ...

Default Value

""

Remarks

Specifies the date and time of the file's last modification.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_read_date Property

Specifies the file's last read date.

Syntax

def get_attach_read_date(attach_index: int) -> str: ...
def set_attach_read_date(attach_index: int, value: str) -> None: ...

Default Value

""

Remarks

Specifies the file's last read date.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

attach_size Property

Attachment's size in bytes.

Syntax

def get_attach_size(attach_index: int) -> int: ...
def set_attach_size(attach_index: int, value: int) -> None: ...

Default Value

0

Remarks

Attachment's size in bytes.

The attach_index parameter specifies the index of the item in the array. The size of the array is controlled by the attach_count property.

bcc_addr_count Property

The number of records in the BccAddr arrays.

Syntax

def get_bcc_addr_count() -> int: ...
def set_bcc_addr_count(value: int) -> None: ...

bcc_addr_count = property(get_bcc_addr_count, set_bcc_addr_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• bcc_addr_address
• bcc_addr_display_name
• bcc_addr_group_name

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

bcc_addr_address Property

Contains the e-mail address in the form of john@doe.

Syntax

def get_bcc_addr_address(bcc_addr_index: int) -> str: ...
def set_bcc_addr_address(bcc_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the e-mail address in the form of john@doe.com.

The bcc_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the bcc_addr_count property.

bcc_addr_display_name Property

Contains the friendly name of the user of this address, such as John Doe.

Syntax

def get_bcc_addr_display_name(bcc_addr_index: int) -> str: ...
def set_bcc_addr_display_name(bcc_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the friendly name of the user of this address, such as John Doe.

The bcc_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the bcc_addr_count property.

bcc_addr_group_name Property

The name of the group this address belongs to.

Syntax

def get_bcc_addr_group_name(bcc_addr_index: int) -> str: ...
def set_bcc_addr_group_name(bcc_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

The name of the group this address belongs to.

The bcc_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the bcc_addr_count property.

cc_addr_count Property

The number of records in the CcAddr arrays.

Syntax

def get_cc_addr_count() -> int: ...
def set_cc_addr_count(value: int) -> None: ...

cc_addr_count = property(get_cc_addr_count, set_cc_addr_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• cc_addr_address
• cc_addr_display_name
• cc_addr_group_name

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

cc_addr_address Property

Contains the e-mail address in the form of john@doe.

Syntax

def get_cc_addr_address(cc_addr_index: int) -> str: ...
def set_cc_addr_address(cc_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the e-mail address in the form of john@doe.com.

The cc_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the cc_addr_count property.

cc_addr_display_name Property

Contains the friendly name of the user of this address, such as John Doe.

Syntax

def get_cc_addr_display_name(cc_addr_index: int) -> str: ...
def set_cc_addr_display_name(cc_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the friendly name of the user of this address, such as John Doe.

The cc_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the cc_addr_count property.

cc_addr_group_name Property

The name of the group this address belongs to.

Syntax

def get_cc_addr_group_name(cc_addr_index: int) -> str: ...
def set_cc_addr_group_name(cc_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

The name of the group this address belongs to.

The cc_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the cc_addr_count property.

charset Property

The charset to apply to Message .

Syntax

def get_charset() -> str: ...
def set_charset(value: str) -> None: ...

charset = property(get_charset, set_charset)

Default Value

"utf-8"

Remarks

Use this property to specify the character set to use in the message.

encryption_cert_count Property

The number of records in the EncryptionCert arrays.

Syntax

def get_encryption_cert_count() -> int: ...
def set_encryption_cert_count(value: int) -> None: ...

encryption_cert_count = property(get_encryption_cert_count, set_encryption_cert_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• encryption_cert_bytes
• encryption_cert_handle

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

encryption_cert_bytes Property

Returns raw certificate data in DER format.

Syntax

def get_encryption_cert_bytes(encryption_cert_index: int) -> bytes: ...

Remarks

Returns raw certificate data in DER format.

The encryption_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the encryption_cert_count property.

This property is read-only.

encryption_cert_handle Property

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

def get_encryption_cert_handle(encryption_cert_index: int) -> int: ...
def set_encryption_cert_handle(encryption_cert_index: int, value: int) -> None: ...

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The encryption_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the encryption_cert_count property.

external_crypto_async_document_id Property

Specifies an optional document ID for SignAsyncBegin() and SignAsyncEnd() calls.

Syntax

def get_external_crypto_async_document_id() -> str: ...
def set_external_crypto_async_document_id(value: str) -> None: ...

external_crypto_async_document_id = property(get_external_crypto_async_document_id, set_external_crypto_async_document_id)

Default Value

""

Remarks

Specifies an optional document ID for SignAsyncBegin() and SignAsyncEnd() calls.

Use this property when working with multi-signature DCAuth requests and responses to uniquely identify documents signed within a larger batch. On the completion stage, this value helps the signing component identify the correct signature in the returned batch of responses.

If using batched requests, make sure to set this property to the same value on both pre-signing (SignAsyncBegin) and completion (SignAsyncEnd) stages.

external_crypto_custom_params Property

Custom parameters to be passed to the signing service (uninterpreted).

Syntax

def get_external_crypto_custom_params() -> str: ...
def set_external_crypto_custom_params(value: str) -> None: ...

external_crypto_custom_params = property(get_external_crypto_custom_params, set_external_crypto_custom_params)

Default Value

""

Remarks

Custom parameters to be passed to the signing service (uninterpreted).

external_crypto_data Property

Additional data to be included in the async state and mirrored back by the requestor.

Syntax

def get_external_crypto_data() -> str: ...
def set_external_crypto_data(value: str) -> None: ...

external_crypto_data = property(get_external_crypto_data, set_external_crypto_data)

Default Value

""

Remarks

Additional data to be included in the async state and mirrored back by the requestor

external_crypto_external_hash_calculation Property

Specifies whether the message hash is to be calculated at the external endpoint.

Syntax

def get_external_crypto_external_hash_calculation() -> bool: ...
def set_external_crypto_external_hash_calculation(value: bool) -> None: ...

external_crypto_external_hash_calculation = property(get_external_crypto_external_hash_calculation, set_external_crypto_external_hash_calculation)

Default Value

FALSE

Remarks

Specifies whether the message hash is to be calculated at the external endpoint. Please note that this mode is not supported by all components. In particular, components operating with larger objects (PDFSigner, CAdESSigner, XAdESSigner) do not support it.

external_crypto_hash_algorithm Property

Specifies the request's signature hash algorithm.

Syntax

def get_external_crypto_hash_algorithm() -> str: ...
def set_external_crypto_hash_algorithm(value: str) -> None: ...

external_crypto_hash_algorithm = property(get_external_crypto_hash_algorithm, set_external_crypto_hash_algorithm)

Default Value

"SHA256"

Remarks

Specifies the request's signature hash algorithm.

external_crypto_key_id Property

The ID of the pre-shared key used for DC request authentication.

Syntax

def get_external_crypto_key_id() -> str: ...
def set_external_crypto_key_id(value: str) -> None: ...

external_crypto_key_id = property(get_external_crypto_key_id, set_external_crypto_key_id)

Default Value

""

Remarks

The ID of the pre-shared key used for DC request authentication.

Asynchronous DCAuth-driven communication requires that parties authenticate each other with a secret pre-shared cryptographic key. This provides extra protection layer for the protocol and diminishes the risk of private key becoming abused by foreign parties. Use this property to provide the pre-shared key identifier, and use external_crypto_key_secret to pass the key itself.

The same KeyID/KeySecret pair should be used on the DCAuth side for the signing requests to be accepted.

Note: The KeyID/KeySecret scheme is very similar to the AuthKey scheme used in various Cloud service providers to authenticate users.

Example: signer.ExternalCrypto.KeyID = "MainSigningKey"; signer.ExternalCrypto.KeySecret = "abcdef0123456789";

external_crypto_key_secret Property

The pre-shared key used for DC request authentication.

Syntax

def get_external_crypto_key_secret() -> str: ...
def set_external_crypto_key_secret(value: str) -> None: ...

external_crypto_key_secret = property(get_external_crypto_key_secret, set_external_crypto_key_secret)

Default Value

""

Remarks

The pre-shared key used for DC request authentication. This key must be set and match the key used by the DCAuth counterpart for the scheme to work.

Read more about configuring authentication in the external_crypto_key_id topic.

external_crypto_method Property

Specifies the asynchronous signing method.

Syntax

def get_external_crypto_method() -> int: ...
def set_external_crypto_method(value: int) -> None: ...

external_crypto_method = property(get_external_crypto_method, set_external_crypto_method)

Default Value

0

Remarks

Specifies the asynchronous signing method. This is typically defined by the DC server capabilities and setup.

Available options:

external_crypto_mode Property

Specifies the external cryptography mode.

Syntax

def get_external_crypto_mode() -> int: ...
def set_external_crypto_mode(value: int) -> None: ...

external_crypto_mode = property(get_external_crypto_mode, set_external_crypto_mode)

Default Value

0

Remarks

Specifies the external cryptography mode.

Available options:

external_crypto_public_key_algorithm Property

Provide public key algorithm here if the certificate is not available on the pre-signing stage.

Syntax

def get_external_crypto_public_key_algorithm() -> str: ...
def set_external_crypto_public_key_algorithm(value: str) -> None: ...

external_crypto_public_key_algorithm = property(get_external_crypto_public_key_algorithm, set_external_crypto_public_key_algorithm)

Default Value

""

Remarks

Provide public key algorithm here if the certificate is not available on the pre-signing stage.

fips_mode Property

Reserved.

Syntax

def get_fips_mode() -> bool: ...
def set_fips_mode(value: bool) -> None: ...

fips_mode = property(get_fips_mode, set_fips_mode)

Default Value

FALSE

Remarks

This property is reserved for future use.

from_addr_count Property

The number of records in the FromAddr arrays.

Syntax

def get_from_addr_count() -> int: ...
def set_from_addr_count(value: int) -> None: ...

from_addr_count = property(get_from_addr_count, set_from_addr_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• from_addr_address
• from_addr_display_name
• from_addr_group_name

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

from_addr_address Property

Contains the e-mail address in the form of john@doe.

Syntax

def get_from_addr_address(from_addr_index: int) -> str: ...
def set_from_addr_address(from_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the e-mail address in the form of john@doe.com.

The from_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the from_addr_count property.

from_addr_display_name Property

Contains the friendly name of the user of this address, such as John Doe.

Syntax

def get_from_addr_display_name(from_addr_index: int) -> str: ...
def set_from_addr_display_name(from_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the friendly name of the user of this address, such as John Doe.

The from_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the from_addr_count property.

from_addr_group_name Property

The name of the group this address belongs to.

Syntax

def get_from_addr_group_name(from_addr_index: int) -> str: ...
def set_from_addr_group_name(from_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

The name of the group this address belongs to.

The from_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the from_addr_count property.

header_encoding Property

The encoding to be applied to the message header.

Syntax

def get_header_encoding() -> int: ...
def set_header_encoding(value: int) -> None: ...

header_encoding = property(get_header_encoding, set_header_encoding)

Default Value

0

Remarks

Use this property to specify the encoding to use with the message header.

mailer Property

The name of the software used to compose and/or send the message.

Syntax

def get_mailer() -> str: ...
def set_mailer(value: str) -> None: ...

mailer = property(get_mailer, set_mailer)

Default Value

""

Remarks

Use this property to specify the software that was used to compose and send this message.

msg_attachment_count Property

Returns the number of attachments in this message.

Syntax

def get_msg_attachment_count() -> int: ...

msg_attachment_count = property(get_msg_attachment_count, None)

Default Value

0

Remarks

Returns the number of attachments in this message.

This property is read-only.

msg_bcc Property

The contents of the BCC header property.

Syntax

def get_msg_bcc() -> str: ...
def set_msg_bcc(value: str) -> None: ...

msg_bcc = property(get_msg_bcc, set_msg_bcc)

Default Value

""

Remarks

The contents of the BCC header field.

The BCC header field contains the addresses of secondary recipients of the message whose addresses are not to be revealed to other recipients of the message. Mail servers remove the BCC header when processing the message and use its value for dispatching the message only.

msg_cc Property

The value of the CC header property.

Syntax

def get_msg_cc() -> str: ...
def set_msg_cc(value: str) -> None: ...

msg_cc = property(get_msg_cc, set_msg_cc)

Default Value

""

Remarks

The value of the CC header field.

The CC field contains the addresses of secondary recipients of the message.

msg_comments Property

Contains additional information about the message body.

Syntax

def get_msg_comments() -> str: ...
def set_msg_comments(value: str) -> None: ...

msg_comments = property(get_msg_comments, set_msg_comments)

Default Value

""

Remarks

Contains additional information about the message body.

msg_date Property

The date and time when the message entered the mail delivery system.

Syntax

def get_msg_date() -> str: ...
def set_msg_date(value: str) -> None: ...

msg_date = property(get_msg_date, set_msg_date)

Default Value

""

Remarks

The date and time when the message entered the mail delivery system.

This field contains the date and time at which the creator of the message posted the message to the mail delivery system.

The date is returned and accepted in UTC time zone.

msg_delivery_receipt Property

Enables delivery notification.

Syntax

def get_msg_delivery_receipt() -> bool: ...
def set_msg_delivery_receipt(value: bool) -> None: ...

msg_delivery_receipt = property(get_msg_delivery_receipt, set_msg_delivery_receipt)

Default Value

FALSE

Remarks

Enables delivery notification.

msg_from Property

Contains the value of the From header property.

Syntax

def get_msg_from() -> str: ...
def set_msg_from(value: str) -> None: ...

msg_from = property(get_msg_from, set_msg_from)

Default Value

""

Remarks

Contains the value of the From header field.

This field contains the address(es) of the message author(s). If the actual sender is not the author of the message, use msg_sender to specify the sender separately.

msg_handle Property

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

def get_msg_handle() -> int: ...
def set_msg_handle(value: int) -> None: ...

msg_handle = property(get_msg_handle, set_msg_handle)

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

msg_html_text Property

The HTML version of the message.

Syntax

def get_msg_html_text() -> str: ...
def set_msg_html_text(value: str) -> None: ...

msg_html_text = property(get_msg_html_text, set_msg_html_text)

Default Value

""

Remarks

The HTML version of the message.

msg_id Property

The contents of the Message-ID header property.

Syntax

def get_msg_id() -> str: ...
def set_msg_id(value: str) -> None: ...

msg_id = property(get_msg_id, set_msg_id)

Default Value

""

Remarks

The contents of the Message-ID header field.

This field contains a unique identifier that refers to a particular version of this message.

msg_in_reply_to Property

The value of the In-Reply-To header property.

Syntax

def get_msg_in_reply_to() -> str: ...
def set_msg_in_reply_to(value: str) -> None: ...

msg_in_reply_to = property(get_msg_in_reply_to, set_msg_in_reply_to)

Default Value

""

Remarks

The value of the In-Reply-To header field.

A reply message should have the "In-Reply-To:" header field which may be used to identify the message (or messages) to which the new message is a reply.

msg_keywords Property

The value of the Keywords header property.

Syntax

def get_msg_keywords() -> str: ...
def set_msg_keywords(value: str) -> None: ...

msg_keywords = property(get_msg_keywords, set_msg_keywords)

Default Value

""

Remarks

The value of the Keywords header field.

This field can be used to add some important words and phrases that might be useful for the recipient.

msg_mailer Property

The name of the software that was used to send the message.

Syntax

def get_msg_mailer() -> str: ...

msg_mailer = property(get_msg_mailer, None)

Default Value

""

Remarks

The name of the software that was used to send the message.

This property is read-only.

msg_plain_text Property

The plain text version of the message.

Syntax

def get_msg_plain_text() -> str: ...
def set_msg_plain_text(value: str) -> None: ...

msg_plain_text = property(get_msg_plain_text, set_msg_plain_text)

Default Value

""

Remarks

The plain text version of the message.

msg_priority Property

Specifies the message priority.

Syntax

def get_msg_priority() -> int: ...
def set_msg_priority(value: int) -> None: ...

msg_priority = property(get_msg_priority, set_msg_priority)

Default Value

2

Remarks

Specifies the message priority.

Available options:

msg_read_receipt Property

Enables a read notification.

Syntax

def get_msg_read_receipt() -> bool: ...
def set_msg_read_receipt(value: bool) -> None: ...

msg_read_receipt = property(get_msg_read_receipt, set_msg_read_receipt)

Default Value

FALSE

Remarks

Enables a read notification.

msg_references Property

The value of the References header property.

Syntax

def get_msg_references() -> str: ...
def set_msg_references(value: str) -> None: ...

msg_references = property(get_msg_references, set_msg_references)

Default Value

""

Remarks

The value of the References header field.

A reply message should include a "References:" header field which may be used to identify the "conversation thread". If the initial message is a reply itself, the References of the reply contain combined content of its "References:", "InReplyTo:" and "MessageID:" fields, subject to their presence in the original message.

msg_reply_to Property

The value of the Reply-To header property.

Syntax

def get_msg_reply_to() -> str: ...
def set_msg_reply_to(value: str) -> None: ...

msg_reply_to = property(get_msg_reply_to, set_msg_reply_to)

Default Value

""

Remarks

The value of the Reply-To header field.

This field contains the addresses to which the replies to this message should be sent. This field is optional. If not specified, the replies must be sent to the addresses specified in the msg_from field.

msg_return_path Property

The value of the Return-Path header property.

Syntax

def get_msg_return_path() -> str: ...
def set_msg_return_path(value: str) -> None: ...

msg_return_path = property(get_msg_return_path, set_msg_return_path)

Default Value

""

Remarks

The value of the Return-Path header field.

This field contains the address to which this message shall be returned in case of unsuccessful delivery.

msg_sender Property

The value of the Sender header property.

Syntax

def get_msg_sender() -> str: ...
def set_msg_sender(value: str) -> None: ...

msg_sender = property(get_msg_sender, set_msg_sender)

Default Value

""

Remarks

The value of the Sender header field.

This field specifies the mailbox of the agent responsible for the actual transmission of this message. If the originator of the message can be indicated by a single mailbox and both the author and the transmitter are identical, the "Sender:" field is deemed excessive and should not be used.

msg_send_to Property

The value of the To header property.

Syntax

def get_msg_send_to() -> str: ...
def set_msg_send_to(value: str) -> None: ...

msg_send_to = property(get_msg_send_to, set_msg_send_to)

Default Value

""

Remarks

The value of the To header field.

This field specifies the address(es) of the primary recipient(s) of the message.

msg_subject Property

Contains the subject property of this message.

Syntax

def get_msg_subject() -> str: ...
def set_msg_subject(value: str) -> None: ...

msg_subject = property(get_msg_subject, set_msg_subject)

Default Value

""

Remarks

Contains the subject field of this message.

header_field_count Property

The number of records in the HeaderField arrays.

Syntax

def get_header_field_count() -> int: ...
def set_header_field_count(value: int) -> None: ...

header_field_count = property(get_header_field_count, set_header_field_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• header_field_category
• header_field_format
• header_field_name
• header_field_value

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

header_field_category Property

Specifies the string category of the contained value.

Syntax

def get_header_field_category(header_field_index: int) -> str: ...
def set_header_field_category(header_field_index: int, value: str) -> None: ...

Default Value

""

Remarks

Specifies the string category of the contained value.

This property allows to check or set the category (or type) associated with the contained value. Depending on the format used to load or save the string, the category parameter may or may not be used.

For example, for ASN.1 property lists the category contains the ASN.1 tag of the contained data (OCTETSTRING, UTF8STRING, INTEGER, ...). For basic (name, value) pairs, such as HTTP headers, the category parameter is not used.

The header_field_index parameter specifies the index of the item in the array. The size of the array is controlled by the header_field_count property.

header_field_format Property

Specifies the format (encoding) of the value contained in the Value property.

Syntax

def get_header_field_format(header_field_index: int) -> int: ...
def set_header_field_format(header_field_index: int, value: int) -> None: ...

Default Value

0

Remarks

Specifies the format (encoding) of the value contained in the header_field_value property.

Use this property to check or set the format of the contained value. Remember to provide the actual value in the appropriate format that matches this setting: utils.NameValuePairs[0].Name = "key"; utils.NameValuePairs[0].Format = svfBinary; utils.NameValuePairs[0].Name = "0a1b2c3d4e5f6071";

The following formats are currently supported:

The header_field_index parameter specifies the index of the item in the array. The size of the array is controlled by the header_field_count property.

header_field_name Property

The name element in a (name, value) pair.

Syntax

def get_header_field_name(header_field_index: int) -> str: ...
def set_header_field_name(header_field_index: int, value: str) -> None: ...

Default Value

""

Remarks

The name element in a (name, value) pair.

The header_field_index parameter specifies the index of the item in the array. The size of the array is controlled by the header_field_count property.

header_field_value Property

The value element in a (name, value) pair.

Syntax

def get_header_field_value(header_field_index: int) -> str: ...
def set_header_field_value(header_field_index: int, value: str) -> None: ...

Default Value

""

Remarks

The value element in a (name, value) pair.

The header_field_index parameter specifies the index of the item in the array. The size of the array is controlled by the header_field_count property.

profile Property

Specifies a pre-defined profile to apply when creating the signature.

Syntax

def get_profile() -> str: ...
def set_profile(value: str) -> None: ...

profile = property(get_profile, set_profile)

Default Value

""

Remarks

Advanced signatures come in many variants, which are often defined by parties that needs to process them or by local standards. SecureBlackbox profiles are sets of pre-defined configurations which correspond to particular signature variants. By specifying a profile, you are pre-configuring the component to make it produce the signature that matches the configuration corresponding to that profile.

reply_to_addr_count Property

The number of records in the ReplyToAddr arrays.

Syntax

def get_reply_to_addr_count() -> int: ...
def set_reply_to_addr_count(value: int) -> None: ...

reply_to_addr_count = property(get_reply_to_addr_count, set_reply_to_addr_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• reply_to_addr_address
• reply_to_addr_display_name
• reply_to_addr_group_name

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

reply_to_addr_address Property

Contains the e-mail address in the form of john@doe.

Syntax

def get_reply_to_addr_address(reply_to_addr_index: int) -> str: ...
def set_reply_to_addr_address(reply_to_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the e-mail address in the form of john@doe.com.

The reply_to_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the reply_to_addr_count property.

reply_to_addr_display_name Property

Contains the friendly name of the user of this address, such as John Doe.

Syntax

def get_reply_to_addr_display_name(reply_to_addr_index: int) -> str: ...
def set_reply_to_addr_display_name(reply_to_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the friendly name of the user of this address, such as John Doe.

The reply_to_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the reply_to_addr_count property.

reply_to_addr_group_name Property

The name of the group this address belongs to.

Syntax

def get_reply_to_addr_group_name(reply_to_addr_index: int) -> str: ...
def set_reply_to_addr_group_name(reply_to_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

The name of the group this address belongs to.

The reply_to_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the reply_to_addr_count property.

sec_settings_claimed_signing_time Property

Specifies the signing time from the signer's computer.

Syntax

def get_sec_settings_claimed_signing_time() -> str: ...
def set_sec_settings_claimed_signing_time(value: str) -> None: ...

sec_settings_claimed_signing_time = property(get_sec_settings_claimed_signing_time, set_sec_settings_claimed_signing_time)

Default Value

""

Remarks

Specifies the signing time from the signer's computer.

Use this property to specify the signature production time. The claimed time is not covered by the signature, may be forfeited or wrong, and as such is usually taken by verifiers for informational purposes only.

sec_settings_encrypt Property

Whether to encrypt the message.

Syntax

def get_sec_settings_encrypt() -> bool: ...
def set_sec_settings_encrypt(value: bool) -> None: ...

sec_settings_encrypt = property(get_sec_settings_encrypt, set_sec_settings_encrypt)

Default Value

FALSE

Remarks

Whether to encrypt the message.

sec_settings_encryption_algorithm Property

Specifies the encryption algorithm to be used.

Syntax

def get_sec_settings_encryption_algorithm() -> str: ...
def set_sec_settings_encryption_algorithm(value: str) -> None: ...

sec_settings_encryption_algorithm = property(get_sec_settings_encryption_algorithm, set_sec_settings_encryption_algorithm)

Default Value

"AES128"

Remarks

Specifies the encryption algorithm to be used.

sec_settings_hash_algorithm Property

Specifies the hash algorithm to be used.

Syntax

def get_sec_settings_hash_algorithm() -> str: ...
def set_sec_settings_hash_algorithm(value: str) -> None: ...

sec_settings_hash_algorithm = property(get_sec_settings_hash_algorithm, set_sec_settings_hash_algorithm)

Default Value

"SHA256"

Remarks

Specifies the hash algorithm to be used.

sec_settings_sign Property

Whether to sign the message.

Syntax

def get_sec_settings_sign() -> bool: ...
def set_sec_settings_sign(value: bool) -> None: ...

sec_settings_sign = property(get_sec_settings_sign, set_sec_settings_sign)

Default Value

FALSE

Remarks

Whether to sign the message.

sec_settings_signature_format Property

Specifies the signature format to use for the signed message.

Syntax

def get_sec_settings_signature_format() -> int: ...
def set_sec_settings_signature_format(value: int) -> None: ...

sec_settings_signature_format = property(get_sec_settings_signature_format, set_sec_settings_signature_format)

Default Value

0

Remarks

Specifies the signature format to use for the signed message.

Available options:

sec_settings_sign_before_encrypt Property

Specifies the order of encryption and signing operations.

Syntax

def get_sec_settings_sign_before_encrypt() -> bool: ...
def set_sec_settings_sign_before_encrypt(value: bool) -> None: ...

sec_settings_sign_before_encrypt = property(get_sec_settings_sign_before_encrypt, set_sec_settings_sign_before_encrypt)

Default Value

TRUE

Remarks

Specifies the order of encryption and signing operations.

sec_settings_sign_message_header Property

Specifies whether to include the message header in the signature calculation.

Syntax

def get_sec_settings_sign_message_header() -> bool: ...
def set_sec_settings_sign_message_header(value: bool) -> None: ...

sec_settings_sign_message_header = property(get_sec_settings_sign_message_header, set_sec_settings_sign_message_header)

Default Value

FALSE

Remarks

Specifies whether to include the message header in the signature calculation.

sender_addr_address Property

Contains the e-mail address in the form of john@doe.

Syntax

def get_sender_addr_address() -> str: ...
def set_sender_addr_address(value: str) -> None: ...

sender_addr_address = property(get_sender_addr_address, set_sender_addr_address)

Default Value

""

Remarks

Contains the e-mail address in the form of john@doe.com.

sender_addr_display_name Property

Contains the friendly name of the user of this address, such as John Doe.

Syntax

def get_sender_addr_display_name() -> str: ...
def set_sender_addr_display_name(value: str) -> None: ...

sender_addr_display_name = property(get_sender_addr_display_name, set_sender_addr_display_name)

Default Value

""

Remarks

Contains the friendly name of the user of this address, such as John Doe.

sender_addr_group_name Property

The name of the group this address belongs to.

Syntax

def get_sender_addr_group_name() -> str: ...
def set_sender_addr_group_name(value: str) -> None: ...

sender_addr_group_name = property(get_sender_addr_group_name, set_sender_addr_group_name)

Default Value

""

Remarks

The name of the group this address belongs to.

send_to_addr_count Property

The number of records in the SendToAddr arrays.

Syntax

def get_send_to_addr_count() -> int: ...
def set_send_to_addr_count(value: int) -> None: ...

send_to_addr_count = property(get_send_to_addr_count, set_send_to_addr_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• send_to_addr_address
• send_to_addr_display_name
• send_to_addr_group_name

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

send_to_addr_address Property

Contains the e-mail address in the form of john@doe.

Syntax

def get_send_to_addr_address(send_to_addr_index: int) -> str: ...
def set_send_to_addr_address(send_to_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the e-mail address in the form of john@doe.com.

The send_to_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the send_to_addr_count property.

send_to_addr_display_name Property

Contains the friendly name of the user of this address, such as John Doe.

Syntax

def get_send_to_addr_display_name(send_to_addr_index: int) -> str: ...
def set_send_to_addr_display_name(send_to_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

Contains the friendly name of the user of this address, such as John Doe.

The send_to_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the send_to_addr_count property.

send_to_addr_group_name Property

The name of the group this address belongs to.

Syntax

def get_send_to_addr_group_name(send_to_addr_index: int) -> str: ...
def set_send_to_addr_group_name(send_to_addr_index: int, value: str) -> None: ...

Default Value

""

Remarks

The name of the group this address belongs to.

The send_to_addr_index parameter specifies the index of the item in the array. The size of the array is controlled by the send_to_addr_count property.

signing_cert_bytes Property

Returns raw certificate data in DER format.

Syntax

def get_signing_cert_bytes() -> bytes: ...

signing_cert_bytes = property(get_signing_cert_bytes, None)

Remarks

Returns raw certificate data in DER format.

This property is read-only.

signing_cert_handle Property

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

def get_signing_cert_handle() -> int: ...
def set_signing_cert_handle(value: int) -> None: ...

signing_cert_handle = property(get_signing_cert_handle, set_signing_cert_handle)

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

signing_chain_count Property

The number of records in the SigningChain arrays.

Syntax

def get_signing_chain_count() -> int: ...
def set_signing_chain_count(value: int) -> None: ...

signing_chain_count = property(get_signing_chain_count, set_signing_chain_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• signing_chain_bytes
• signing_chain_handle

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

signing_chain_bytes Property

Returns raw certificate data in DER format.

Syntax

def get_signing_chain_bytes(signing_chain_index: int) -> bytes: ...

Remarks

Returns raw certificate data in DER format.

The signing_chain_index parameter specifies the index of the item in the array. The size of the array is controlled by the signing_chain_count property.

This property is read-only.

signing_chain_handle Property

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

def get_signing_chain_handle(signing_chain_index: int) -> int: ...
def set_signing_chain_handle(signing_chain_index: int, value: int) -> None: ...

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The signing_chain_index parameter specifies the index of the item in the array. The size of the array is controlled by the signing_chain_count property.

text_encoding Property

The encoding to be applied to the message.

Syntax

def get_text_encoding() -> int: ...
def set_text_encoding(value: int) -> None: ...

text_encoding = property(get_text_encoding, set_text_encoding)

Default Value

0

Remarks

Use this property to specify the encoding to use for the content of the message.

attach_bytes Method

Creates an attachment from a memory buffer.

Syntax

def attach_bytes(data: bytes) -> int: ...

Remarks

Use this method to create an attachment from a memory buffer. Use attachments property to provide further attachment details.

The method returns the index of the new attachment in the attachments list.

attach_file Method

Creates an attachment from a file.

Syntax

def attach_file(filename: str) -> int: ...

Remarks

Use this method to create an attachment from a file. Use attachments property to provide further attachment details.

The method returns the index of the new attachment in the attachments list.

attach_image Method

Creates an image attachment from a memory buffer.

Syntax

def attach_image(id: str, data: bytes) -> int: ...

Remarks

Use this method to create a picture attachment from a memory buffer. Use attachments property to provide further attachment details.

The method returns the index of the new attachment in the attachments list.

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.

do_action Method

Performs an additional action.

Syntax

def do_action(action_id: str, action_params: str) -> str: ...

Remarks

do_action is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insencitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

save_to_bytes Method

Serializes the message to a byte array.

Syntax

def save_to_bytes() -> bytes: ...

Remarks

Use this method to assemble the message and save it to a byte array.

save_to_file Method

Serializes the message to a file.

Syntax

def save_to_file(filename: str) -> None: ...

Remarks

Use this method to assemble the message and save it to a file.

on_error Event

Reports information about errors during e-mail message assembling or saving.

Syntax

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

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

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

Remarks

The event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error.

on_external_sign Event

Handles remote or external signing initiated by the SignExternal method or other source.

Syntax

class MailWriterExternalSignEventParams(object):
  @property
  def operation_id() -> str: ...

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

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

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

  @property
  def signed_data() -> str: ...
  @signed_data.setter
  def signed_data(value) -> None: ...

# In class MailWriter:
@property
def on_external_sign() -> Callable[[MailWriterExternalSignEventParams], None]: ...
@on_external_sign.setter
def on_external_sign(event_hook: Callable[[MailWriterExternalSignEventParams], None]) -> None: ...

Remarks

Assign a handler to this event if you need to delegate a low-level signing operation to an external, remote, or custom signing engine. Depending on the settings, the handler will receive a hashed or unhashed value to be signed.

The event handler must pass the value of Data to the signer, obtain the signature, and pass it back to the component via SignedData parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact component being used, and may be empty. HashAlgorithm specifies the hash algorithm being used for the operation, and Pars contain algorithm-dependent parameters.

The component uses base16 (hex) encoding for Data, SignedData, and Pars parameters. If your signing engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the signing.

A sample MD5 hash encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

A sample event handler that uses a .NET RSACryptoServiceProvider class may look like the following: signer.OnExternalSign += (s, e) => { var cert = new X509Certificate2("cert.pfx", "", X509KeyStorageFlags.Exportable); var key = (RSACryptoServiceProvider)cert.PrivateKey; var dataToSign = e.Data.FromBase16String(); var signedData = key.SignHash(dataToSign, "2.16.840.1.101.3.4.2.1"); e.SignedData = signedData.ToBase16String(); };

on_notification Event

This event notifies the application about an underlying control flow event.

Syntax

class MailWriterNotificationEventParams(object):
  @property
  def event_id() -> str: ...

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

# In class MailWriter:
@property
def on_notification() -> Callable[[MailWriterNotificationEventParams], None]: ...
@on_notification.setter
def on_notification(event_hook: Callable[[MailWriterNotificationEventParams], None]) -> None: ...

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

MailWriter Config Settings

The class accepts one or more of the following configuration settings. Configuration 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.

MailWriter Config Settings

Base Config Settings

MailWriter Errors

MailWriter Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Class is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER)
	22020097   Failed to assemble a mail message (SB_ERROR_MAIL_ASSEMBLY_FAILED)
	22020098   Failed to parse a mail message (SB_ERROR_MAIL_PARSING_FAILED)
	22020099   Failed to decrypt a message because there is no decryption certificate provided (SB_ERROR_MAIL_NO_DECRYPTION_CERTIFICATE)