Platform SDK: CDO 1.2.1

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

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 "me@microsoft.com", "you@microsoft.com", "Hello", _ 
                  "I sent this in 3 statements!", 0 ' low importance 
  Set objNewMail = Nothing ' canNOT reuse it 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", "you@microsoft.com", _ 
                  "Schedule", "Here's the latest master schedule", 0 
  Set objNewMail = Nothing