Using the SMTP Message Envelope Fields

Using the SMTP Message Envelope Fields

The fields passed to an event sink in the IMessage.EnvelopeFields collection contain transport envelope values. These fields are present for a message only as it is being delivered (transported) to its final location. Each field name resides in the https://schemas.microsoft.com/cdo/smtpenvelope/ namespace. The following table describes these fields.

The https://schemas.microsoft.com/cdo/smtpenvelope/ Namespace

*The types listed are VARIANT subtypes. Each Microsoft® ActiveX® Data Objects (ADO) Field object stores the value for the field as a VARIANT value.

The messagestatus field can be altered by your sink and used either to abort the delivery or relay of the message. Specifically, you can:

• Abort the message's delivery or relay (cdoStatAbortDelivery = 2).
• Send it to the bad mail directory (cdoStatBadMail=3).
• Let it be delivered or relayed (cdoStatSuccess=0).

You can indicate one of the proceeding actions to the SMTP service by updating the messagestatus field in the collection. As shown earlier in this topic, the CdoMessageStat enumeration can be used to set these values.

Note

If the messagestatus field is used to abort the message (cdoStatAbortDelivery ) or to send the message to the bad-mail location (cdoStatBadMail), the effect is not immediate unless you set cdoSkipRemainingSinks (0) as the value for the second argument to the ISMTPOnArrival.OnArrival method. (This argument is passed by reference.) This value indicates to the dispatcher thread that sink processing is complete and all remaining sinks are to be skipped. At this point, the SMTP service examines the messagestatus envelope field for the message and takes the indicated action.

The recipientlist field contains the e-mail address of each intended recipient. If the message was submitted over the network through the SMTP protocol, each recipient corresponds to a RCPT TO: protocol command. If the message was submitted through the local SMTP service pickup directory, each recipient corresponds to an x-receiver header at the top of the message file. You can alter this list when executing; for example, you can expand a custom distribution list by substituting the alias address with each member of the list.

The senderemailaddress field contains the address of the message's sender. If the message was submitted over the network using the SMTP, this address corresponds to the transmitted MAIL FROM SMTP command. If the message was submitted using the SMTP service pickup directory, this address corresponds to the x-senderheader at the top of the message file.

Note

The recipientlist and senderemailaddress envelope fields and the various message header fields such as (urn:schemas:mailheader:) To, From, Cc, and Bcc are different attributes of the message. The SMTP does not use the mail header fields to route the message; it routes the message based upon the RCPT TO and MAIL FROM protocol commands if a message is submitted using the SMTP, or the x-receiver and x-sender headers if a message is submitted to the local SMTP pickup directory. The envelope fields are not transmitted or stored with the message and exist only for the message's lifetime in SMTP transport.

' Reference to Microsoft ActiveX Data Objects 2.5 Library
' Reference to Microsoft CDO for Windows 2000 Library

Implements CDO.ISMTPOnArrival
Implements IEventIsCacheable

Private Sub IEventIsCacheable_IsCacheable()
 ' just returns S_OK
End Sub

Private Sub ISMTPOnArrival_OnArrival(ByVal iMsg As CDO.Message, EventStatus As CDO.CdoEventStatus)
  Dim Flds as ADODB.Fields
  Dim RecipList as String
  Set Flds = iMsg.EnvelopeFields

  ' Read Recipient List
  RecipList = _
     Flds("https://schemas.microsoft.com/cdo/smtpenvelope/recipientlist")

  ' Add Administrator to the list
  RecipList = RecipList & "SMTP:administrator@server.example.com;"

  ' Update the envelope field with the augmented list
  Flds("https://schemas.microsoft.com/cdo/smtpenvelope/recipientlist") = RecipList
  Flds.Update

  ' Add disclaimer to textbody
  ' (Should check for HTMLBody, but this is omitted for brevity)
  iMsg.TextBody = iMsg.TextBody & _
    vbCrLf & _
    "-- This message has been forwarded to the administrator" & _
    vbCrLf

  ' Commit the content changes to the transport ADO Stream object
  iMsg.DataSource.Save
  EventStatus = cdoRunNextSink
End Sub

<SCRIPT LANGUAGE="VBScript">

Const cdoRunNextSink = 0
Const cdoSkipRemainingSinks = 1

Sub IEventIsCacheable_IsCacheable()
 ' just returns S_OK
End Sub

Sub ISMTPOnArrival_OnArrival(iMsg, EventStatus)
  Dim Flds
  Dim RecipList
  Set Flds = iMsg.EnvelopeFields
  ' Read Recipient List
  RecipList = _
     Flds("https://schemas.microsoft.com/cdo/smtpenvelope/recipientlist")

  ' Add Administrator to the list
  RecipList = RecipList & "SMTP:administrator@server.example.com;"

  ' Update the envelope field with the augmented list
  Flds("https://schemas.microsoft.com/cdo/smtpenvelope/recipientlist") = RecipList
  Flds.Update

  ' Add disclaimer to textbody
  ' (Should check for HTMLBody, but this is omitted for brevity)
  iMsg.TextBody = iMsg.TextBody & _
    vbCrLf & _
    "-- This message has been forwarded to the administrator" & _
    vbCrLf

  ' Commit the content changes to the transport ADO Stream object
  iMsg.DataSource.Save
  EventStatus = cdoRunNextSink
End Sub
</SCRIPT>

See Also

Concepts

CdoMessageStat Enum
https://schemas.microsoft.com/cdo/smtpenvelope/ Namespace