EDMailAgent

Inherits From:

NSObject

Declared In:

EDMailAgent.h

Class Description

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:     
    
    NS_DURING
    mailAgent = [EDMailAgent mailAgentForRelayHostWithName:@"mail.example.com"];
    [mailAgent sendMailWithHeaders:headerFields andBody:@"Some text"];
    NS_HANDLER
    if([[[localException userInfo] objectForKey:EDBrokenSMPTServerHint] boolValue] == NO)
    [localException raise];
    mailAgent = [EDMailAgent mailAgentForRelayHostWithName:@"mail.example.com"];
    [mailAgent setSkipsExtensionTest:YES];
    [mailAgent sendMailWithHeaders:headerFields andBody:@"Some text"];
    NS_ENDHANDLER
    
    

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

Instance Variables

NSHost *relayHost;
struct EDMAFlags flags;

relayHost	All instance variables are private.
flags

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

mailAgentForRelayHostWithName:

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

Instance Methods

initWithRelayHost:

- (id)initWithRelayHost:(NSHost *)aHost

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

relayHost

- (NSHost *)relayHost

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

sendMailWithHeaders:andBody:

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

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

sendMailWithHeaders:body:andAttachment:withName:

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

sendMailWithHeaders:body:andAttachments:

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

sendMessage:

- (void)sendMessage:(EDInternetMessage *)message

Attempts to deliver message.

setRelayHost:

- (void)setRelayHost:(NSHost *)aHost

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

setRelayHostByName:

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

setSkipsExtensionTest:

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

skipsExtensionTest

- (BOOL)skipsExtensionTest

Returns whether the mail agent tries to negotiate SMTP extensions.