Sending 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:

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.

Creating a WOMailDelivery object (Java)

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

Creating a WOMailDelivery object (Objective-C)

 
+ (WOMailDelivery *)sharedInstance

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.

Composing a plain text message (Java)

 
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?

Composing a plain text message (Objective-C)

 
-(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.

Composing a HTML message (Java)

 
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?

Composing a HTML message (Objective-C)

 
-(NSString *)composeEmailFrom:(NSString *)aSender 
    to:(NSArray *)somePeople 
    cc:(NSArray *)otherPeople 
    subject:(NSString *)aSubject 
    component:(WOComponent *)aComponent 
    send:(BOOL)sendNow

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.

The sendEMail method (Java)

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

The sendEMail method (Objective-C)

 
-(void)sendEmail:(NSString *)mailString

The mailed component should not contain any image or resource requiring a callback to the web server. 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.

Sending mail (Java)

 
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 <acme_app@acme.com>"; 
    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; 
}

Sending Mail (Objective-C)

 
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 <acme_app@acme.com>"; 
    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; 
}