Messages are introduced to the PMDF mail system by enqueuing them. Each enqueued message contains two required pieces and one optional piece: the message envelope, the message header, and the optional message body. The contents of the first two pieces, envelope and header, must be provided by the program using the API. The third piece, the message body, is optional - a message does not need to contain a body. Briefly, these three pieces are as follows:

• Envelope: The message envelope contains the envelope From: address and the list of envelope To: addresses. The envelope is created by PMDF when the message is enqueued; the addresses to be placed in the envelope must conform to RFC 822. Note that in the message envelope no distinction is made between To:, Cc:, and Bcc: addresses. Consequently, the envelope To: addresses are often referred to as simply envelope recipient addresses. Programs should treat the message envelope as an opaque structure and rely solely upon the PMDF API routines to read and write information from and to the envelope. The format of the envelope is subject to change; the API routines insulate programmers from such changes. The routines PMDFstartMessageEnvelope, PMDFsetRecipientType, and PMDFaddRecipient are used to specify the message envelope.
• Header: The message header contains RFC 822-style header lines. The program enqueuing the message has nearly complete control over the contents of the header and can specify as many or as few header lines as it sees fit. The only header lines which a program using the API must explicitly generate are the From: and Date: header lines. If the From: header line is omitted, PMDF will construct it from the envelope From: address. Note that this may not always be appropriate.⁵ If the Date: header line is omitted, PMDF will supply it as well as a Date-warning: header line. These two header lines can be generated with PMDFwriteFrom and PMDFwriteDate. When the message is enqueued, PMDF will do its best to supply any mandatory header lines that are missing. PMDF will also take measures to ensure that the contents of the header lines conform to any relevant standards. Any addresses appearing in the message header should conform to RFC 822. The header is typically written line-by-line with the PMDFwriteLine or PMDFwriteText routines. It may also be built up and output with the header structure manipulation routines described in Section 1.6. The routines PMDFwriteFrom, PMDFwriteDate, and PMDFwriteSubject can be used to write From:, Date:, and Subject: header lines. Using information supplied via the routines PMDFstartMessageEnvelope and PMDFaddRecipient, PMDF will generate the From: and To: header lines automatically as well as any necessary Cc: and Bcc: header lines.
• Body: The optional message body contains the content of the message. As with the message header, the program enqueuing the message has nearly complete control over the contents of the message body. The only exception to this is when the message is structured with multiple parts or requires encoding (e.g., contains binary data, lines requiring wrapping, etc.). In such cases, PMDF will ensure that the message body conforms to the MIME standard (RFC 2045--2049). Message body lines are written with PMDFwriteLine or PMDFwriteText and read with PMDFreadLine or PMDFreadText.

Enqueued messages are ASCII text files located in the PMDF queue directories. ⁶ A sample message is shown in Example 1-1. The essential pieces in that example are: the message envelope, (1); the message header, (2); and the message body, (3).

Example 1-1 Sample Mail Message File

m;GONZALO@EXAMPLE.COM (1) ALONSO@EXAMPLE.COM Date: Sat, 4 May 2012 18:04 EDT (2) From: Gonzalo <GONZALO@EXAMPLE.COM> To: King Alonso <ALONSO@EXAMPLE.COM> Subject: Walking Alonso, (3) By'r lakin, I can go no further, sir; My old bones ache: here's a maze trod indeed Through forth-rights and meanders! By your patience, I needs must rest me. Gonzalo

The steps required to enqueue one or more messages are as follows:

1. Initialize PMDF resources and data structures with PMDFinitialize.
2. Initialize the PMDF enqueuing subsystem with PMDFenqueueInitialize.
3. For each message to enqueue, perform the following steps:
   1. specify the message envelope with PMDFstartMessageEnvelope and PMDFaddRecipient;
   2. specify the message header with PMDFstartMessageHeader, PMDFwriteFrom, PMDFwriteDate, PMDFwriteSubject, and PMDFwriteLine;
   3. specify the message body with PMDFstartMessageBody and PMDFwriteLine; and
   4. submit the message with PMDFenqueueMessage.
4. Deallocate PMDF resources and data structures with PMDFdone.

When calling PMDFstartMessageEnvelope, a channel name may be specified. The message is then enqueued under the context of the specified channel (i.e., submitted as though enqueued by that channel itself). Typically, the l (local) channel should be used. If you are writing your own channel, then you should specify the name of your channel as reported by PMDFgetChannelName. ⁷

If the message being enqueued is the result of dequeuing a message, then the envelope identification can be copied over from the old message to the new with PMDFgetEnvelopeId and PMDFsetEnvelopeId. Similarly, the NOTARY processing flags should be copied with PMDFgetRecipientFlags and PMDFsetRecipientFlags.

Examples 1-2, 1-3, 1-8 and 1-9 all illustrate how to enqueue a message.