MailWriter Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

nsoftware.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 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

• C#
• VB.NET

public MailwriterAttachEncodings AttachEncoding { get; set; }

enum MailwriterAttachEncodings {
  meAuto,
  me8bit,
  meBase64,
  meQuotedPrintable
}

Public Property AttachEncoding As MailwriterAttachEncodings

Enum MailwriterAttachEncodings
  meAuto
  me8bit
  meBase64
  meQuotedPrintable
End Enum

Default Value

0

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

• C#
• VB.NET

public MailAttachmentList Attachments { get; }

Public Property Attachments As MailAttachmentList

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.

Bcc Property (MailWriter Component)

The BCC header of the Message.

Syntax

• C#
• VB.NET

public MailAddressList Bcc { get; }

Public Property Bcc As MailAddressList

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.

Cc Property (MailWriter Component)

The CC header of the Message.

Syntax

• C#
• VB.NET

public MailAddressList Cc { get; }

Public Property Cc As MailAddressList

Remarks

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

This property is not available at design time.

Charset Property (MailWriter Component)

The charset to apply to Message .

Syntax

• C#
• VB.NET

public string Charset { get; set; }

Public Property Charset As String

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

• C#
• VB.NET

public CertificateList EncryptionCertificates { get; }

Public Property EncryptionCertificates As CertificateList

Remarks

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

This property is not available at design time.

ExternalCrypto Property (MailWriter Component)

Provides access to external signing and DC parameters.

Syntax

• C#
• VB.NET

public ExternalCrypto ExternalCrypto { get; }

Public ReadOnly Property ExternalCrypto As 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.

FIPSMode Property (MailWriter Component)

Reserved.

Syntax

• C#
• VB.NET

public bool FIPSMode { get; set; }

Public Property FIPSMode As Boolean

Default Value

False

Remarks

This property is reserved for future use.

From Property (MailWriter Component)

The From header of the Message.

Syntax

• C#
• VB.NET

public MailAddressList From { get; }

Public Property From As MailAddressList

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.

HeaderEncoding Property (MailWriter Component)

The encoding to be applied to the message header.

Syntax

• C#
• VB.NET

public MailwriterHeaderEncodings HeaderEncoding { get; set; }

enum MailwriterHeaderEncodings {
  meAuto,
  me8bit,
  meBase64,
  meQuotedPrintable
}

Public Property HeaderEncoding As MailwriterHeaderEncodings

Enum MailwriterHeaderEncodings
  meAuto
  me8bit
  meBase64
  meQuotedPrintable
End Enum

Default Value

0

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

• C#
• VB.NET

public string Mailer { get; set; }

Public Property Mailer As String

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

• C#
• VB.NET

public MailMessage Message { get; set; }

Public Property Message As MailMessage

Remarks

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

This property is not available at design time.

OtherHeaders Property (MailWriter Component)

Provides access to secondary message headers.

Syntax

• C#
• VB.NET

public StringNameValuePairList OtherHeaders { get; }

Public Property OtherHeaders As StringNameValuePairList

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.

Profile Property (MailWriter Component)

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

Syntax

• C#
• VB.NET

public string Profile { get; set; }

Public Property Profile As String

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

• C#
• VB.NET

public MailAddressList ReplyTo { get; }

Public Property ReplyTo As MailAddressList

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.

SecuritySettings Property (MailWriter Component)

A container for the message's security settings.

Syntax

• C#
• VB.NET

public MailSecuritySettings SecuritySettings { get; }

Public ReadOnly Property SecuritySettings As MailSecuritySettings

Remarks

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

This property is read-only.

Sender Property (MailWriter Component)

The value of the Sender header field of the Message.

Syntax

• C#
• VB.NET

public MailAddress Sender { get; set; }

Public Property Sender As MailAddress

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.

SendTo Property (MailWriter Component)

The value of the To header field of the Message.

Syntax

• C#
• VB.NET

public MailAddressList SendTo { get; }

Public Property SendTo As MailAddressList

Remarks

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

SigningCertificate Property (MailWriter Component)

The certificate to be used for signing.

Syntax

• C#
• VB.NET

public Certificate SigningCertificate { get; set; }

Public Property SigningCertificate As Certificate

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.

SigningChain Property (MailWriter Component)

The signing certificate chain.

Syntax

• C#
• VB.NET

public CertificateList SigningChain { get; }

Public Property SigningChain As CertificateList

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.

TextEncoding Property (MailWriter Component)

The encoding to be applied to the message.

Syntax

• C#
• VB.NET

public MailwriterTextEncodings TextEncoding { get; set; }

enum MailwriterTextEncodings {
  meAuto,
  me8bit,
  meBase64,
  meQuotedPrintable
}

Public Property TextEncoding As MailwriterTextEncodings

Enum MailwriterTextEncodings
  meAuto
  me8bit
  meBase64
  meQuotedPrintable
End Enum

Default Value

0

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

• C#
• VB.NET

public int AttachBytes(byte[] data);

Public Function AttachBytes(ByVal Data As Byte()) As 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

• C#
• VB.NET

public int AttachFile(string filename);

Public Function AttachFile(ByVal Filename As String) As 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

• C#
• VB.NET

public int AttachImage(string ID, byte[] data);

Public Function AttachImage(ByVal ID As String, ByVal Data As Byte()) As 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

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As 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

• C#
• VB.NET

public string DoAction(string actionID, string actionParams);

Public Function DoAction(ByVal ActionID As String, ByVal ActionParams As String) As 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

• C#
• VB.NET

public byte[] SaveToBytes();

Public Function SaveToBytes() As Byte()

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

• C#
• VB.NET

public void SaveToFile(string filename);

Public Sub SaveToFile(ByVal Filename As 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

• C#
• VB.NET

public void SaveToStream(System.IO.Stream stream);

Public Sub SaveToStream(ByVal Stream As System.IO.Stream)

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

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, MailwriterErrorEventArgs e);

public class MailwriterErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As MailwriterErrorEventArgs)

Public Class MailwriterErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

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

• C#
• VB.NET

public event OnExternalSignHandler OnExternalSign;

public delegate void OnExternalSignHandler(object sender, MailwriterExternalSignEventArgs e);

public class MailwriterExternalSignEventArgs : EventArgs {
  public string OperationId { get; }
  public string HashAlgorithm { get; }
  public string Pars { get; }
  public string Data { get; }
  public string SignedData { get; set; }
}

Public Event OnExternalSign As OnExternalSignHandler

Public Delegate Sub OnExternalSignHandler(sender As Object, e As MailwriterExternalSignEventArgs)

Public Class MailwriterExternalSignEventArgs Inherits EventArgs
  Public ReadOnly Property OperationId As String
  Public ReadOnly Property HashAlgorithm As String
  Public ReadOnly Property Pars As String
  Public ReadOnly Property Data As String
  Public Property SignedData As String
End Class

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:

 
 Copy
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

• C#
• VB.NET

public event OnNotificationHandler OnNotification;

public delegate void OnNotificationHandler(object sender, MailwriterNotificationEventArgs e);

public class MailwriterNotificationEventArgs : EventArgs {
  public string EventID { get; }
  public string EventParam { get; }
}

Public Event OnNotification As OnNotificationHandler

Public Delegate Sub OnNotificationHandler(sender As Object, e As MailwriterNotificationEventArgs)

Public Class MailwriterNotificationEventArgs Inherits EventArgs
  Public ReadOnly Property EventID As String
  Public ReadOnly Property EventParam As String
End Class

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

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count, string password);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] certBytes, int certStartIndex, int certCount, byte[] keyBytes, int keyStartIndex, int keyCount, string password);

Public Certificate(ByVal CertBytes As Byte(), ByVal CertStartIndex As Integer, ByVal CertCount As Integer, ByVal KeyBytes As Byte(), ByVal KeyStartIndex As Integer, ByVal KeyCount As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

• C#
• VB.NET

public Certificate(string path, string password);

Public Certificate(ByVal Path As String, ByVal Password As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string certPath, string keyPath, string password);

Public Certificate(ByVal CertPath As String, ByVal KeyPath As String, ByVal Password As String)

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string path);

Public Certificate(ByVal Path As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream);

Public Certificate(ByVal Stream As System.IO.Stream)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream, string password);

Public Certificate(ByVal Stream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(System.IO.Stream certStream, System.IO.Stream keyStream, string password);

Public Certificate(ByVal CertStream As System.IO.Stream, ByVal KeyStream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate();

Public Certificate()

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

 
 Copy
  signer.ExternalCrypto.KeyID = "MainSigningKey";
  signer.ExternalCrypto.KeySecret = "abcdef0123456789";

Constructors

• C#
• VB.NET

public ExternalCrypto();

Public ExternalCrypto()

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

• C#
• VB.NET

public MailAddress(string address);

Public MailAddress(ByVal Address As String)

Creates a new e-mail address object.

• C#
• VB.NET

public MailAddress(string displayName, string address);

Public MailAddress(ByVal DisplayName As String, ByVal Address As 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

• C#
• VB.NET

public MailAttachment(string contentType);

Public MailAttachment(ByVal ContentType As 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

• C#
• VB.NET

public MailMessage();

Public MailMessage()

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

• C#
• VB.NET

public MailSecuritySettings();

Public MailSecuritySettings()

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

 
 Copy
  utils.NameValuePairs[0].Name = "key";
  utils.NameValuePairs[0].Format = svfBinary;
  utils.NameValuePairs[0].Name = "0a1b2c3d4e5f6071";

Constructors

• C#
• VB.NET

public StringNameValuePair(string name, string value);

Public StringNameValuePair(ByVal Name As String, ByVal Value As String)

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

• C#
• VB.NET

public StringNameValuePair();

Public StringNameValuePair()

Creates an empty name-value object.

Config Settings (MailWriter Component)

MailWriter Config Settings

Base Config Settings

Trappable Errors (MailWriter Component)

MailWriter Errors