PATH WebObjects 4.0 Documentation > WebObjects Programming Topics

Sending E-mail from a WebObjects Application

Synopsis

Describes how to compose and deliver e-mail from a WebObjects application.

Discussion

Composing and delivering e-mail from a WebObjects application is accomplished by using the WOMailDelivery class. WOMailDelivery has several methods for composing, addressing, and delivering e-mail messages.

Overview of WOMailDelivery

To perform e-mail delivery, WOMailDelivery uses a command-line tool that is compiled on all supported WebObjects platforms. The executable can be found in <NeXT_ROOT>\Library\WebObjects\Executables\WOSendMail[.exe]

This tool constructs an e-mail message from a file and uses SMTP to send it. It has a default SMTP server hostname (called "smtp"). However, you will most likely need to change it to reflect your site's SMTP server. This can be accomplished by setting the WOSMTPHost default for your application. Like all other WebObjects defaults, it can be set by either the "defaults" command-line tool, or by passing it as an argument when starting your WebObjects application.

Option 1 - Using the "defaults" tool to set WOSMTPHost

Assuming your WebObjects application is called "MyApp" and your SMTP host is called "postoffice.acme.com", type the following on the command line:

defaults write MyApp WOSMTPHost "postoffice.acme.com"

You could set this for all applications by setting the default on NSGlobalDomain rather than on MyApp:

defaults write NSGlobalDomain WOSMTPHost "postoffice.acme.com"

Option 2 - Passing WOSMTPHost as an argument

Assuming your WebObjects application is called MyApp and your SMTP host is called postoffice.acme.com, you would start your application as follows:

MyApp.exe [other misc. options] -WOSMTPHost "postoffice.acme.com"

Using WOMailDelivery in Source Code

Your source code, perhaps in an action method on one of your components, must perform the following steps to deliver e-mail:

1. Create an instance of the WOMailDelivery class. This is easily accomplished via the sharedInstance class method, which returns a shared instance of WOMailDelivery, creating the instance as necessary.

Figure 1. Java Code

public.static.native com.apple.yellow.webobjects.WOMailDelivery.sharedInstance()

Figure 2. Objective-C Code

+ (WOMailDelivery *)sharedInstance

2. Compose and send your WOMailDelivery object using plain text or HTML encoding. Separate methods are provided to compose messages in the two encodings.

Plain Text Message -- Composes an e-mail message setting the content type of the e-mail as (Content-type: TEXT/PLAIN; CHARSET=US-ASCII). If sendNow is true, the e-mail is sent at once.

Figure 3. Java Code

public native java.lang.string composePlainTextEmail (

    java.lang.String,						// From: string

    com.apple.yellow.foundation.NSArray,						// To: array of e-mail addresses

    com.apple.yellow.foundation.NSArray,						// Cc: array of e-mail addresses

    java.lang.String,						// Subject: string

    java.lang.String,						// MessageBody: string

    boolean)						// send it now?

Figure 4. Objective-C Code

-(NSString *)composeEmailFrom:(NSString *)aSender

    to:(NSArray *)somePeople

    cc:(NSArray *)otherPeople

    subject:(NSString *)aSubject

    plainText:(NSString *)aMessage

    send:(BOOL)sendNow

HTML Message -- Composes an e-mail message, calling generateResponse on the WOComponent argument and embedding the resulting HTML in the body of the message. This is convenient if you want to send the actual HTML generated by one of your custom WOComponents. It uses the WOCGIAdaptorURL default to complete all URLs in the page to be mailed. If sendNow is true, the e-mail is sent at once.

Figure 5. Java Code

public native java.lang.string composeComponentEmail (

    java.lang.String,						// From: string

    com.apple.yellow.foundation.NSArray,						// To: array of e-mail addresses

    com.apple.yellow.foundation.NSArray,						// Cc: array of e-mail addresses

    java.lang.String,						// Subject: string

    com.apple.yellow.webobjects.WOComponent,						// MessageBody: WOComponent

    boolean)						// send it now?

Figure 6. Objective-C Code

-(NSString *)composeEmailFrom:(NSString *)aSender

    to:(NSArray *)somePeople

    cc:(NSArray *)otherPeople

    subject:(NSString *)aSubject

    component:(WOComponent *)aComponent

    send:(BOOL)sendNow

3. If you specify true/YES as the "send" argument in step 2, then delivery will occur immediately. However, if you specify false/NO as the "send" argument, then you must explicitly tell the WOMailDelivery object to deliver the message. This is accomplished by calling the sendEmail method with the fully composed mailString (returned by one of the methods from Step 2) as the only argument.

Figure 7. Java Code

public native void sendEmail (java.lang.String) // mailString

Figure 8. Objective-C Code

-(void)sendEmail:(NSString *)mailString

The mailed component should not contain any image or resource requiring a callback to the web server at this point. Links and forms in e-mailed WOComponents will work correctly as long as the application is available to serve them.

Source Code Example

The following example composes and delivers two messages: one with plain text and one with HTML. This method could be the target of an action or WOForm submit.

Figure 9. Java Code

String message; // Bound to a WOText element in this component

// Remember to set the WOSMTPHost or this code will not work

public WOComponent sendEmail()

    String from = "ACME WebObjects Program ";

    Object tos[]={"acme_admin@acme.com", "acme_hr@acme.com>"};

    NSArray to = new NSArray(tos);

    NSArray cc = new NSArray("acme_support@acme.com");

    String htmlMessage;

    // Delivers a plain text message by grabbing the contents

    // of the WOText element bound to message. Delivers

    // immediately since the last argument is true.

    WOMailDelivery.sharedInstance().composePlainTextEmail(

        from, to, cc, "WebSite Feedback", message, true);

    // This delivers an HTML message created by passing this

    // as the WOComponent argument. generateResponse will be sent to

    // this and will result in a formatted HTML string. This time,

    // instead of delivering immdediately, the last argument is

    // false and we use the sendEmail method with the return

    // value from composeComponentEmail().

    htmlMessage = WOMailDelivery.sharedInstance().composeComponentEmail(

        from, to, cc, "WebSite Feedback", this, false);

    WOMailDelivery.sharedInstance().sendEmail(htmlMessage);

    return null;

Figure 10. Objective-C Code

NSString *message; // Bound to a WOText element in this component

// Remember to set the WOSMTPHost or this will not work

- (void)sendEmail

    NSString *from = @"ACME WebObjects Program ";

    NSArray *to = [NSArray arrayWithObject:@"acme_admin@acme.com"];

    NSArray *cc = [NSArray arrayWithObject:@"acme_support@acme.com"];

    NSString *htmlMessage;

    // This delivers a plain text message by grabbing the contents

    // of the WOText element bound to message. It also delivers

    // immediately since the last argument is true.

    [[WOMailDelivery sharedInstance]

        composeEmailFrom: from to: to cc: cc subject: @"WebSite Feedback"

        plainText: message send: YES];

    // This delivers an HTML message created by passing self

    // as the WOComponent argument. generateResponse will be sent to

    // self and will result in a formatted HTML string. This time,

    // instead of delivering immdediately, the last argument is

    // false and we use the sendEmail method with the return

    // value from composeEmailFrom:to:cc:subject:component:send:.

    htmlMessage = [[WOMailDelivery sharedInstance]

        composeEmailFrom: from to: to cc: cc subject: @"WebSite Feedback"

        component: self send: NO];

    [[WOMailDelivery sharedInstance] sendEmail:htmlMessage];

    return nil;

Questions

· How do I send e-mail from a WebObjects application?

· How do I send e-mail with WebObjects WOComponent generated HTML as its content?

· How do I specify the WOSMTPHost for my WebObjects application?

· Where do I find a command-line tool that delivers e-mail?

Keywords

· e-mail

· generateResponse

· WOMailDelivery

· WOSMTPHost

· SMTP

Revision History

24 July, 1998. Eric Seymour. First Draft.

19 November 1998. Clif Liu. Second Draft.

WebObjects 4.0 Developer Documentation