Inherits From:
Declared In:

Class Description

The mail agent class allows to deliver mail messages to an SMTP server. It also provides convenience methods to construct EDInternetMessages so that for simple applications the message API is not required. The mail agent can (and will by default) use 8-BIT delivery and pipelining if the SMTP server allows it.

Example to send a simple mail:     
    NSString *text; // assume this exists
    headerFields = [NSMutableDictionary dictionary];
    [headerFields setObject:@"Joe User <joe@example.com>" forKey:@"To"];
    [headerFields setObject:@"Hi there" forKey:@"Subject"];
    text = [text stringWithCanonicalLinebreaks];
    mailAgent = [EDMailAgent mailAgentForRelayHostWithName:@"mail.example.com"];
    [mailAgent sendMailWithHeaders:headerFields andBody:text];

Example to send a mail with two attachments:     
    NSData *documentData, *logoData; // assume these exist
    headerFields = [NSMutableDictionary dictionary];
    [headerFields setObject:@"Joe User <joe@example.com>" forKey:@"To"];
    [headerFields setObject:@"Your weekly report" forKey:@"Subject"];
    text = @"Here they are:\r\n";
    attachmentList = [NSMutableArray array];
    [attachmentList addObject:[EDObjectPair pairWithObjects:documentData:@"report.pdf"]];
    [attachmentList addObject:[EDObjectPair pairWithObjects:logoData:@"logo.jpg"]];
    mailAgent = [EDMailAgent mailAgentForRelayHostWithName:@"mail.example.com"];
    [mailAgent sendMailWithHeaders:headerFields body:text andAttachments:attachmentList];

If you do not know at compile time which SMTP server your application will use you should be prepared for broken SMTP servers that cannot even do the extensions check. In this case you must either disable the extensions or, if you want to use them when available, catch the error and retry as follows:     
    mailAgent = [EDMailAgent mailAgentForRelayHostWithName:@"mail.example.com"];
    [mailAgent sendMailWithHeaders:headerFields andBody:@"Some text"];
    if([[[localException userInfo] objectForKey:EDBrokenSMPTServerHint] boolValue] == NO)
    [localException raise];
    mailAgent = [EDMailAgent mailAgentForRelayHostWithName:@"mail.example.com"];
    [mailAgent setSkipsExtensionTest:YES];
    [mailAgent sendMailWithHeaders:headerFields andBody:@"Some text"];

For this you need to import EDSMTPStream to get the declaration of EDBrokenSMPTServerHint.

Instance Variables

NSHost *relayHost;
struct EDMAFlags flags;

relayHostAll instance variables are private.

Method Types

Creating mail agent instances
+ mailAgentForRelayHostWithName:
- initWithRelayHost:
Configuring the mail agent
- setRelayHostByName:
- setRelayHost:
- relayHost
- setSkipsExtensionTest:
- skipsExtensionTest
Sending messages
- sendMailWithHeaders:andBody:
- sendMailWithHeaders:body:andAttachment:withName:
- sendMailWithHeaders:body:andAttachments:
- sendMessage:

Class Methods


+ (id)mailAgentForRelayHostWithName:(NSString *)aName

Creates and returns a mail agent which will use the SMTP server on host name to deliver messages.

Instance Methods


- (id)initWithRelayHost:(NSHost *)aHost

Initialises a newly allocated mail agent and sets the relay host to aHost.


- (NSHost *)relayHost

Returns the host on which the SMTP server is running that the mail agent uses to deliver messages.


- (void)sendMailWithHeaders:(NSDictionary *)userHeaders andBody:(NSString *)body

Calls sendMailWithHeaders:body:andAttachments: with an empty attachment list.


- (void)sendMailWithHeaders:(NSDictionary *)userHeaders body:(NSString *)body andAttachment:(NSData *)attData withName:(NSString *)attName

Calls sendMailWithHeaders:body:andAttachments: with an attachment list containing the attachment attData with the name attName.


- (void)sendMailWithHeaders:(NSDictionary *)userHeaders body:(NSString *)body andAttachments:(NSArray *)attList

Composes and attempts to deliver a mail message. The message is built from the body and the attachments in attachmentList. The latter is an array of EDObjectPairs containing the attachment data and name respectively. The userHeaders must include at a minimum some recipient specification, e.g. the key "To" with a string value containing the recipient addresses; comma-separated.


- (void)sendMessage:(EDInternetMessage *)message

Attempts to deliver message.


- (void)setRelayHost:(NSHost *)aHost

Sets the host on which the SMTP server is running that the mail agent uses to deliver messages to aHost.


- (void)setRelayHostByName:(NSString *)hostname

Sets the host on which the SMTP server is running that the mail agent uses to deliver messages to the host with the name hostname.


- (void)setSkipsExtensionTest:(BOOL)flag

If set to YES the mail agent will not try to negotiate SMTP extensions with the server on the relay host.


- (BOOL)skipsExtensionTest

Returns whether the mail agent tries to negotiate SMTP extensions.

Version 2.1 Copyright ©2002 by Erik Doernenburg. All Rights Reserved.