Message Enqueue API |
Messages are submitted to the IMTA by enqueuing them. Each enqueued message contains two required pieces and one optional piece, all of which can be generated using this API:
|
|
message envelope |
|
|
message header |
|
|
optional message body. |
The Message Enqueue API can be used only after the IMTA has been initialized with a previous call to imta_init, which specifies the channel from which messages will be enqueued.Prior to starting to enqueue messages, an enqueue context must be created by calling imme_init. An arbitrary number of messages can then be enqueued with this enqueue context. Finally, when the enqueueing session is over, the corresponding enqueue context should be destroyed by calling imme_end.
An enqueue context can be used to enqueue at most one message at a time; In other words, for a given enqueue context, messages have to be enqueued serially, one after the other. However, a program can create and manage several enqueue contexts in order to parallelize message enqueue operations.
Programs which run indefinitely should be made aware of configuration changes by calling imme_end/imme_init. periodically.
The message envelope defines the originator (envelope From:) and the list of recipients (envelope To:) addresses of the message being enqueued. These addresses must conform to RFC 822. For each recipient, the envelope may also contains Notary information (see RFC 1891).The Sun Internet Mail SDK allows programmers to create the message envelope and specify the envelope From: by calling imme_start_envelope. Each recipient is then specified with a call to imme_add_recipient.
Note that in the message envelope, no distinction is made between To:, Cc:, and Bcc: addresses. However, the type of recipient (To:, Cc:, and Bcc:) is recorded when imme_add_recipient is called, to be automatically included in the message header when it is created.
The message header contains RFC 822 style header lines. The program enqueuing the message can specify as many or as few header lines as it sees fit. A large number of header line types are pre-defined in rfc822_header.h. However, programs are not limited to this list; site-specific header line types can be created as long a they comply to the format defined in RFC 822. Note also that any addresses appearing in the message header should conform to RFC 822.The Message header API must be used to create a header object, which can then be written to the message being enqueued using imme_write_header.
If not present in the header, the Date: header line is automatically added by the SDK library.
If not specified, the From: header is created using the envelope From: address. Note that this may not always be appropriate. For instance, when mail is addressed to a mailing list which specifies an Errors-to: address, then the Errors-to: address should be used as the envelope From: address. In this case, it is not appropriate to derive the header From: line from the envelope From: address.
The To:, Cc:, and Bcc: headers are also added automatically, by using the information provided when the envelope was created.
The optional message body contains the content of the message. 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, the SIMS IMTA will ensure that the message body conforms to MIME (RFC 1521).Message body lines are written with imme_write_text. Note that it is left to the caller to include CRLF line terminators in the text being written. Failing to include CRLFs will result in no line breaks in the generated message, which might cause SMTP implementation to break if the maximum lenght of a message header line (998 bytes) is reached.
Once the message envelope, header and body have been successfully entered, the message can be enqueued, so that the IMTA can process and deliver it. This is done by calling imme_enqueue.If an unrecoverable error occurs anytime during the writing operations, the message can be aborted by calling imme_abort.
The example C program enqueue_a_message.c is another way to look at it.