NewMail Object (CDONTS Library)

  • Article

 

NewMail Object (CDONTS Library)

The NewMail object provides for sending a message with very few lines of code.

At a Glance

Specified in type library:

CDONTS.DLL

First available in:

CDO for NTS Library version 1.2

Parent objects:

(none)

Child objects:

(none)

Default property:

Value

Note

In compliance with RFC 2557, Microsoft Exchange 2000 Server and later versions no longer emit Content-Base headers. Therefore, using the ContentBase setting will not result in the Content-Base header being set in the new mail represented by this NewMail object.

Properties

Name

Available since version

Type

Access

Bcc

1.2

String

Write-only

Body

1.2

IStream object or String

Write-only

BodyFormat

1.2

Long

Write-only

Cc

1.2

String

Write-only

ContentBase

1.2

String

Write-only

ContentLocation

1.2

String

Write-only

From

1.2

String

Write-only

Importance

1.2

Long

Write-only

MailFormat

1.2

Long

Write-only

Subject

1.2

String

Write-only

To

1.2

String

Write-only

Value

1.2

String

Write-only

Version

1.2

String

Read-only

Methods

Name

Available since version

Parameters

AttachFile

1.2

Source as Object or String, (optional) FileName as String, (optional) EncodingMethod as Long

AttachURL

1.2

Source as Object or String, ContentLocation as String, (optional) ContentBase as String, (optional) EncodingMethod as Long

Send

1.2

(optional) From as String, (optional) To as String, (optional) Subject as String, (optional) Body as Object or String, (optional) Importance as Long

SetLocaleIDs

1.2

CodePageID as Long

Remarks

The NewMail object is not built on the normal API architecture. It is meant for rapid generation of notification mail by an automated process running in the Microsoft® Windows NT® Server. No user interface is supplied, and no interaction with human users is expected during the generation and sending of the message. Therefore the NewMail object's properties are not designed to be read back and inspected. With the sole exception of Version, they can only be written.

The NewMail object is self-contained and does not expose any of the Properties Common to All CDO for NTS Library Objects.

Attachments and recipients, once added to the NewMail object, cannot be removed, and the NewMail object itself cannot be deleted. When the Send method completes successfully, the NewMail object is invalidated but not removed from memory. The programmer should Set the invalid object to Nothing to remove it from memory, or reassign it to another NewMail object. Attempted access to a sent NewMail object results in a return of CdoE_INVALID_OBJECT.

The NewMail object does not belong to the hierarchy encompassing the other CDO for NTS Library objects. It cannot access, nor can it be accessed from, any of the other objects. Like the Session object, it is considered a top-level object and is created directly from a Microsoft® Visual Basic® program. Its ProgID is CDONTS.NewMail. This code fragment creates a NewMail object through early binding:

  Dim objNewMail As CDONTS.NewMail
  Set objNewMail = CreateObject("CDONTS.NewMail")

The main advantage of the NewMail object is the ease and simplicity with which you can generate and send a message. You do not have to log on to a session nor deal with a folder or a messages collection. You have only to create the NewMail object, send it, and Set it to Nothing. You can supply critical information in the parameters of the Send method. In many cases you only need three lines of code:

  Set objNewMail = CreateObject("CDONTS.NewMail")
  objNewMail.Send "user2@example.com", "user1@example.com", "Hello", _
                  "I sent this in 3 statements!", 0 ' low importance
  Set objNewMail = Nothing '  DO NOT reuse the object for another message

Including an attachment can add as little as one statement to your code, because you can pass information in the parameters of the AttachFile method:

  Set objNewMail = CreateObject("CDONTS.NewMail")
  Call objNewMail.AttachFile("\\server\schedule\sched.xls", "SCHED.XLS")
  objNewMail.Send "Automated Schedule Generator", "user1@example.com", _
                  "Schedule", "Here's the new schedule", 0
  Set objNewMail = Nothing