Chapter 4 Messaging Server Specific Information

Event Notification Types and Parameters

For Messaging Server, there is only one event reference, which can be composed of several
parameters. There are various types of event notifications. Table 4–1 lists the event types supported by Messaging Server and gives a description
of each:

Table 4–1 Event Types

Event Types

Description

DeleteMsg

Messages marked as “Deleted” are removed from the mailbox. This
is the equivalent to IMAP expunge.

Login

User logged in from IMAP, HTTP, or POP.

Logout

User logged out from IMAP, HTTP, or POP.

NewMsg

New message was received by the system into the user’s mailbox. Can have
a payload of message headers and body.

OverQuota

Operation failed because the user’s mailbox exceeded one of the quotas
(diskquota, msgquota). The MTA channel holds the message until the quota changes or
the user’s mail box count goes below the quota. If the message expires while
it is being held by the MTA, it will be expunged.

PurgeMsg

Message expunged (as a result of an expired date) from the mailbox by the server
process imexpire. This is a server side expunge, whereas DeleteMsg is a client side
expunge. This is not a purge in the true sense of the word.

ReadMsg

Message in the mailbox was read (in the IMAP protocol, the message was marked
Seen).

TrashMsg

Message was marked for deletion by IMAP or HTTP. The user may still see the
message in the folder, depending on the mail client’s configuration. The messages
are to be removed from the folder when an expunge is performed.

UnderQuota

Quota went back to normal from OverQuota state.

UpdateMsg

Message was appended to the mailbox (other than by NewMsg). for example, the
user copied an email message to the mailbox. Can have a payload of message headers
and body.

The following applies to the above supported event types:

For NewMsg and UpdateMsg, message
pay load is turned off by default to prevent overloading ENS. For information on how
to enable the payload, see Payload. No other event
types support a payload.

Event notifications can be generated for changes to the INBOX alone, or to the INBOX and all other folders. The
following configuration variable allows for INBOX only (value = 0), or for both the INBOX and all other folders (value
= 1):

local.store.notifyplugin.noneInbox.enable

The default setting is for INBOX only (value = 0).

Note –

There is no mechanism to select folders; all folders are included when
the variable is enabled (value = 1).

The NewMsg notification is issued only after the
message is deposited in the user mailbox (as opposed to “after it was accepted
by the server and queued in the message queue”).

Every notification carries several pieces of information (called parameters)
depending on the event type, for example, NewMsg indicates the
IMAP uid of the new message. For details on the parameters each
event type takes, see Table 4–4.

Events are not generated for POP3 client access.

All event types can be suppressed by issuing XNOTNOTIFY.
For example, an IMAP script used for housekeeping only (the users are not meant to
be notified) might issue it to suppress all events.

Parameters

iBiff uses the following format for the ENS event reference:

enp://127.0.0.1/store?param=value&param1=value1&param2=value2

The event key enp://127.0.0.1/store has no significance other
than its uniqueness as a string. For example, the hostname portion of the event key
has no significance as a hostname. It is simply a string that is part of the URI.
However, the event key is user configurable. The list of iBiff event reference parameters
is listed in Table 4–2 and Table 4–3 that follow.

The second part of the event reference consists of parameter-value pairs. This
part of the event reference is separated from the event key by a question mark (?). The parameter and value are separated by an equals sign (=). The parameter-value pairs are separated by an ampersand (&). Note that there can be empty values, for which the value simply does
not exist.

Table 4–2 describes the mandatory event
reference parameters that need to be included in every notification.

Table 4–2 Mandatory Event Reference
Parameters

Parameter

Data Type

Description

evtType

string

Specifies the event type.

hostname

string

The hostname of the machine that generated the event.

mailboxName

string

Specifies the mailbox name in the message store. The mailboxName has the format uid@domain, where uid is the user’s unique identifier,
and domain is the domain the user belongs to. The @domain portion is added only when the user does not belong to the default domain
(i.e. the user is in a hosted domain).

pid

integer

ID of the process that generated the event.

process

string

Specifies the name of the process that generated the event.

timestamp

64-bit integer

Specifies the number of milliseconds since the epoch (midnight GMT, January
1, 1970).

Table 4–3 describes optional event reference
parameters, which might be seen in the event depending on the event type (see Table 4–4).

Table 4–3 Optional Event Reference
Parameters

Parameter

Data Type

Description

client

IP address

The IP address of the client logging in or out.

diskQuota

signed 32-bit integer

Specifies the disk space quota in kilobytes. The value is set to -1 to indicate
no quotas.

diskUsed

signed 32-bit integer

Specifies the amount of disk space used in kilobytes.

hdrLen

unsigned 32-bit integer

Specifies the size of the message header. Note that this might not be the size
of the header in the payload, because it might have been truncated.

imapUid

unsigned 32-bit integer

Specifies the IMAP uid parameter.

lastUid

unsigned 32-bit integer

Specifies the last IMAP uid value that was used.

numDel

unsigned 32-bit integer

Specifies the number of messages marked as deleted in the mailbox.

numMsgs

unsigned 32-bit integer

Specifies the number of total messages in the mailbox.

numMsgsMax

signed 32-bit integer

Specifies the quota for the maximum number of messages. The value is set to
-1 to indicate no quotas.

numSeen

unsigned 32-bit integer

Specifies the number of messages in the mailbox marked as seen (read).

size

unsigned 32-bit integer

Specifies the size of the message. Note that this may not be the size of payload,
since the payload is typically a truncated version of the message.

uidValidity

unsigned 32-bit integer

Specifies the IMAP uid validity parameter.

Note –

Subscribers should allow for undocumented parameters when parsing the
event reference. This allows for future compatibility when new parameters are added.

Table 4–4 shows the parameters that are
available for each event type. For example, to see which parameters apply to a TrashMsg event, look in the column header for “ReadMsg, TrashMsg”
and then note that these events can use numDel, numMsgs, numSeen, and userValidity.

Table 4–4 Available Parameters for
Each Event Type

Parameter

NewMsg, UpdateMsg

ReadMsg, TrashMsg

DeleteMsg, PurgeMsg

Login, Logout

OverQuota, UnderQuota

client

No

No

No

Yes

No

diskQuota

No

No

No

No

Yes

diskUsed

No

No

No

No

Yes

hdrLen

Yes

No

No

No

No

imapUid

Yes

No

Yes

No

No

lastUid

No

No

Yes

No

No

numDel

No

Yes

No

No

No

numMsgs

Yes

Yes

Yes

No

Yes

numMsgsMax

No

No

No

No

Yes

numSeen

No

Yes

No

No

No

size

Yes

No

No

No

No

uidValidity

Yes

Yes

Yes

No

No

userid

No

No

No

Yes

No

Payload

ENS allows a payload for two event types: NewMsg, and UpdateMsg; the other event types do not carry a payload. The payload portion
of these two notifications can contain any of the following data:

No header or body data (default setting)

Message header data only

Message body data only

Both message header and body data

The amount and type of data sent as the payload of the ENS event is determined
by the configuration parameters found in Table 4–5.

Table 4–5 Payload Configuration
Parameters

Configuration Parameter

Description

local.store.notifyplugin.maxBodySize

Specifies the maximum size (in bytes) of the body that will be transmitted with
the notification. Default setting is zero (0).

local.store.notifyplugin.maxHeaderSize

Specifies the maximum size (in bytes) of the header that will be transmitted
with the notification. Default setting is zero (0).

Note that both parameters are set to zero as the default so that no header or
body data is sent with ENS notifications.

Examples

The following example shows a NewMsg event reference (it
is actually a single line that is broken up to several lines for readability):

Implementation Notes

The current implementation does not provide security on events that can be subscribed
to. Thus, a user could register for all events, and portions of all other users’
mail. Because of this it is strongly recommended that the ENS subscriber be on the “safe”
side of the firewall at the very least.