Sending a Mail Message

In iOS 3.0 and later, you can use the MFMailComposeViewController class to present a standard mail composition interface inside your app. Prior to displaying the interface, you use the methods of the class to configure the email recipients, the subject, body, and any attachments you want to include. When you present the interface (using standard view controller techniques), the user has the option of editing the contents of the message before submitting it to the Mail app for delivery. The user also has the option to cancel the email altogether.

To use the mail composition interface, you must add MessageUI.framework to your Xcode project and link against it in any relevant targets. To access the classes and headers of the framework, include an #import <MessageUI/MessageUI.h> statement at the top of any relevant source files. For information on how to add frameworks to your project, see Files in Projects in Xcode Project Management Guide.

To use the MFMailComposeViewController class in your app, you create an instance and use its methods to set the initial email data. You must also assign an object to the mailComposeDelegateproperty of the view controller to handle the dismissal of the interface when the user accepts or cancels the email. The delegate object you specify must conform to the MFMailComposeViewControllerDelegateprotocol.

When specifying email addresses for the mail composition interface, you specify plain string objects. If you want to use email addresses from the user’s list of contacts, you can use the Address Book framework to retrieve that information. For more information on how to get email and other information using this framework, see Address Book Programming Guide for iOS.

Listing 1 shows the code for creating the MFMailComposeViewController object and displaying the mail composition interface modally in your app. You would include the displayComposerSheet method in one of your custom view controllers and call the method as needed to display the interface. In this example, the parent view controller assigns itself as the delegate and implements the mailComposeController:didFinishWithResult:error: method. The delegate method dismisses the delegate without taking any further actions. In your own app, you could use the delegate to track whether the user sent or canceled the email by examining the value in the result parameter.

Listing 1  Posting the mail composition interface

@implementation WriteMyMailViewController (MailMethods)

-(void)displayComposerSheet

{

    MFMailComposeViewController *picker = [[MFMailComposeViewController alloc] init];

    picker.mailComposeDelegate = self;

    [picker setSubject:@"Hello from California!"];

    // Set up the recipients.

    NSArray *toRecipients = [NSArray arrayWithObjects:@"first@example.com",

                                   nil];

    NSArray *ccRecipients = [NSArray arrayWithObjects:@"second@example.com",

                                   @"third@example.com", nil];

    NSArray *bccRecipients = [NSArray arrayWithObjects:@"four@example.com",

                                   nil];

    [picker setToRecipients:toRecipients];

    [picker setCcRecipients:ccRecipients];

    [picker setBccRecipients:bccRecipients];

    // Attach an image to the email.

    NSString *path = [[NSBundle mainBundle] pathForResource:@"ipodnano"

                                 ofType:@"png"];

    NSData *myData = [NSData dataWithContentsOfFile:path];

    [picker addAttachmentData:myData mimeType:@"image/png"

                                 fileName:@"ipodnano"];

    // Fill out the email body text.

    NSString *emailBody = @"It is raining in sunny California!";

    [picker setMessageBody:emailBody isHTML:NO];

    // Present the mail composition interface.

    [self presentModalViewController:picker animated:YES];

    [picker release]; // Can safely release the controller now.

}

// The mail compose view controller delegate method

- (void)mailComposeController:(MFMailComposeViewController *)controller

              didFinishWithResult:(MFMailComposeResult)result

              error:(NSError *)error

{

    [self dismissModalViewControllerAnimated:YES];

}

@end

For more information on the standard view controller techniques for displaying interfaces, see View Controller Programming Guide for iOS. For information about the classes of the Message UI framework, see Message UI Framework Reference.