MailWriter Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

TsbxMailWriter

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 component with short descriptions. Click on the links for further details.

Method List

---

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

Event List

---

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

Config Settings

---

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

AttachEncoding Property (MailWriter Component)

The encoding to be applied to the attachments.

Syntax

property AttachEncoding: TsbxMailEncodings read get_AttachEncoding write set_AttachEncoding;

TsbxMailEncodings = (
  meAuto,
  me8bit,
  meBase64,
  meQuotedPrintable
);

Default Value

meAuto

Remarks

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

Attachments Property (MailWriter Component)

Contains a list of attachments to the message.

Syntax

property Attachments: TsbxMailAttachmentList read get_Attachments write set_Attachments;

Remarks

Use this property to access all attachments added to the Message and tune up their properties.

This property is not available at design time.

Please refer to the MailAttachment type for a complete list of fields.

Bcc Property (MailWriter Component)

The BCC header of the Message.

Syntax

property Bcc: TsbxMailAddressList read get_Bcc write set_Bcc;

Remarks

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.

This property is not available at design time.

Please refer to the MailAddress type for a complete list of fields.

Cc Property (MailWriter Component)

The CC header of the Message.

Syntax

property Cc: TsbxMailAddressList read get_Cc write set_Cc;

Remarks

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

This property is not available at design time.

Please refer to the MailAddress type for a complete list of fields.

Charset Property (MailWriter Component)

The charset to apply to Message .

Syntax

property Charset: String read get_Charset write set_Charset;

Default Value

'utf-8'

Remarks

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

EncryptionCertificates Property (MailWriter Component)

The recipients' encryption certificates.

Syntax

property EncryptionCertificates: TsbxCertificateList read get_EncryptionCertificates write set_EncryptionCertificates;

Remarks

Use this property to provide certificates to be used for message encryption.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

ExternalCrypto Property (MailWriter Component)

Provides access to external signing and DC parameters.

Syntax

property ExternalCrypto: TsbxExternalCrypto read get_ExternalCrypto;

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

Please refer to the ExternalCrypto type for a complete list of fields.

FIPSMode Property (MailWriter Component)

Reserved.

Syntax

property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;

Default Value

false

Remarks

This property is reserved for future use.

From Property (MailWriter Component)

The From header of the Message.

Syntax

property From: TsbxMailAddressList read get_From write set_From;

Remarks

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

Please refer to the MailAddress type for a complete list of fields.

HeaderEncoding Property (MailWriter Component)

The encoding to be applied to the message header.

Syntax

property HeaderEncoding: TsbxMailEncodings read get_HeaderEncoding write set_HeaderEncoding;

TsbxMailEncodings = (
  meAuto,
  me8bit,
  meBase64,
  meQuotedPrintable
);

Default Value

meAuto

Remarks

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

Mailer Property (MailWriter Component)

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

Syntax

property Mailer: String read get_Mailer write set_Mailer;

Default Value

''

Remarks

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

Message Property (MailWriter Component)

The message that is currently being composed.

Syntax

property Message: TsbxMailMessage read get_Message write set_Message;

Remarks

This property accumulates the properties of the message that is being composed.

This property is not available at design time.

Please refer to the MailMessage type for a complete list of fields.

OtherHeaders Property (MailWriter Component)

Provides access to secondary message headers.

Syntax

property OtherHeaders: TsbxStringNameValuePairList read get_OtherHeaders write set_OtherHeaders;

Remarks

Use this property to access the headers of the message that are not available via first-level properties of the component

This property is not available at design time.

Please refer to the StringNameValuePair type for a complete list of fields.

Profile Property (MailWriter Component)

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

Syntax

property Profile: String read get_Profile write 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.

ReplyTo Property (MailWriter Component)

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

Syntax

property ReplyTo: TsbxMailAddressList read get_ReplyTo write set_ReplyTo;

Remarks

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 From field.

Please refer to the MailAddress type for a complete list of fields.

SecuritySettings Property (MailWriter Component)

A container for the message's security settings.

Syntax

property SecuritySettings: TsbxMailSecuritySettings read get_SecuritySettings;

Remarks

Use this property to tune up the message's security parameters.

This property is read-only.

Please refer to the MailSecuritySettings type for a complete list of fields.

Sender Property (MailWriter Component)

The value of the Sender header field of the Message.

Syntax

property Sender: TsbxMailAddress read get_Sender write set_Sender;

Remarks

This field specifies the mailbox of the agent responsible for the actual transmission of the message.

If the originator of the message can be indicated by a single mailbox, and the author and the transmitter is the same identity, the "Sender:" field should not be used.

This property is not available at design time.

Please refer to the MailAddress type for a complete list of fields.

SendTo Property (MailWriter Component)

The value of the To header field of the Message.

Syntax

property SendTo: TsbxMailAddressList read get_SendTo write set_SendTo;

Remarks

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

Please refer to the MailAddress type for a complete list of fields.

SigningCertificate Property (MailWriter Component)

The certificate to be used for signing.

Syntax

property SigningCertificate: TsbxCertificate read get_SigningCertificate write set_SigningCertificate;

Remarks

Use this property to specify the certificate that shall be used for signing the data. Note that this certificate should have a private key associated with it. Use SigningChain to supply the rest of the certificate chain for inclusion into the signature.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

SigningChain Property (MailWriter Component)

The signing certificate chain.

Syntax

property SigningChain: TsbxCertificateList read get_SigningChain write set_SigningChain;

Remarks

Use this property to provide the chain for the signing certificate. Use the SigningCertificate property, if it is available, to provide the signing certificate itself.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

TextEncoding Property (MailWriter Component)

The encoding to be applied to the message.

Syntax

property TextEncoding: TsbxMailEncodings read get_TextEncoding write set_TextEncoding;

TsbxMailEncodings = (
  meAuto,
  me8bit,
  meBase64,
  meQuotedPrintable
);

Default Value

meAuto

Remarks

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

AttachBytes Method (MailWriter Component)

Creates an attachment from a memory buffer.

Syntax

function AttachBytes(Data: TBytes): Integer;

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.

AttachFile Method (MailWriter Component)

Creates an attachment from a file.

Syntax

function AttachFile(Filename: String): Integer;

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.

AttachImage Method (MailWriter Component)

Creates an image attachment from a memory buffer.

Syntax

function AttachImage(ID: String; Data: TBytes): Integer;

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 (MailWriter Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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.

DoAction Method (MailWriter Component)

Performs an additional action.

Syntax

function DoAction(ActionID: String; ActionParams: String): String;

Remarks

DoAction is a generic method available in every component. 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 insensitive) 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;....

SaveToBytes Method (MailWriter Component)

Serializes the message to a byte array.

Syntax

function SaveToBytes(): TBytes;

Remarks

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

SaveToFile Method (MailWriter Component)

Serializes the message to a file.

Syntax

procedure SaveToFile(Filename: String);

Remarks

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

SaveToStream Method (MailWriter Component)

Serializes the message to a stream.

Syntax

procedure SaveToStream(Stream: TStream);

Remarks

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

Error Event (MailWriter Component)

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

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

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.

ExternalSign Event (MailWriter Component)

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

Syntax

type TExternalSignEvent = procedure (
  Sender: TObject;
  const OperationId: String;
  const HashAlgorithm: String;
  const Pars: String;
  const Data: String;
  var SignedData: String
) of Object;

property OnExternalSign: TExternalSignEvent read FOnExternalSign write FOnExternalSign;

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 the 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 contains algorithm-dependent parameters.

The component uses base16 (hex) encoding for the 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 the .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(); };

Notification Event (MailWriter Component)

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

Syntax

type TNotificationEvent = procedure (
  Sender: TObject;
  const EventID: String;
  const EventParam: String
) of Object;

property OnNotification: TNotificationEvent read FOnNotification write FOnNotification;

Remarks

The component 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 the 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.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

>

constructor Create();

Creates a new object with default field values.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

>

constructor Create();

Creates a new ExternalCrypto object with default field values.

MailAddress Type

A container for an e-mail addressee.

Remarks

This object is a container for an e-mail identity record. A typical e-mail address consists of an RFC822 e-mail address (john@doe.com), a friendly name (John Doe), and a group name (Officers).

Fields

Constructors

>

constructor Create(valAddress: String);

Creates a new e-mail address object.

>

constructor Create(valDisplayName: String; valAddress: String);

Creates a new e-mail address object from an address and a display name.

MailAttachment Type

Represents an attachment to an e-mail message.

Remarks

This object is a container for message attachments.

Fields

Constructors

>

constructor Create(valContentType: String);

Creates an empty mail attachment object.

MailMessage Type

Represents an e-mail message.

Remarks

This object is a container for an e-mail message.

A message consists of a header and a body. The header, in turn, consists of several header fields. The names, syntax, and expected contents of the header fields are standardized.

The message body can contain anything you like (a message may not even have a body at all).

Fields

Constructors

>

constructor Create();

Creates a new empty mail message object.

MailSecuritySettings Type

Provides access to the new message security settings.

Remarks

Use this object to tune up the security setting for the created message.

Fields

Constructors

>

constructor Create();

Creates a new MailSecuritySettings object.

StringNameValuePair Type

A simple name-value pair object.

Remarks

The component represents a name-value string pair used in a variety of network components.

Fields

Constructors

>

constructor Create(valName: String; valValue: String);

Creates a name-value pair from a name and a value.

>

constructor Create();

Creates an empty name-value object.

Config Settings (MailWriter Component)

The component 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 component, access to these internal properties is provided through the Config method.

MailWriter Config Settings

Base Config Settings

Trappable Errors (MailWriter Component)

MailWriter Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Component 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)