MFMailComposeViewController Class Reference

Inherits from	UINavigationController : UIViewController : UIResponder : NSObject
Conforms to	NSCoding (UIViewController) UIAppearanceContainer (UIViewController) NSObject (NSObject)
Availability	Available in iOS 3.0 and later.
Declared in	MFMailComposeViewController.h
Related sample code	MessageComposer MVCNetworking Table View Animations and Gestures

Overview

The MFMailComposeViewController class provides a standard interface that manages the editing and sending an email message. You can use this view controller to display a standard email view inside your application and populate the fields of that view with initial values, such as the subject, email recipients, body text, and attachments. The user can edit the initial contents you specify and choose to send the email or cancel the operation.

Using this interface does not guarantee immediate delivery of the corresponding email message. The user may cancel the creation of the message, and if the user does choose to send the message, the message is only queued in the Mail application outbox. This allows you to generate emails even in situations where the user does not have network access, such as in airplane mode. This interface does not provide a way for you to verify whether emails were actually sent.

Before using this class, you must always check to see if the current device is configured to send email at all using the canSendMail method. If the user’s device is not set up for the delivery of email, you can notify the user or simply disable the email dispatch features in your application. You should not attempt to use this interface if the canSendMail method returns NO.

To display the view managed by this view controller, you can use any of the standard techniques for displaying view controllers. However, the most common way to present this interface is do so modally using the presentModalViewController:animated: method. Figure 1 shows the view that is displayed when you present the mail composition interface, with some of the fields already filled in. For more information on displaying the views associated with view controllers, see View Controller Programming Guide for iOS.

**Figure 1** The mail composition interface

Tasks

Determining Mail Availability

Setting Mail Fields Programmatically

Accessing the Delegate

Properties

mailComposeDelegate

The mail composition view controller’s delegate.

@property(nonatomic,assign) id<MFMailComposeViewControllerDelegate> mailComposeDelegate;

Discussion

The delegate object is responsible for dismissing the view presented by this view controller at the appropriate time. Therefore, you should always provide a delegate and that object should implement the methods of the MFMailComposeViewControllerDelegate protocol.

Availability

Available in iOS 3.0 and later.

Related Sample Code

Declared In

MFMailComposeViewController.h

Class Methods

canSendMail

Returns a Boolean indicating whether the current device is able to send email.

+ (BOOL)canSendMail

Return Value

YES if the device is configured for sending email or NO if it is not.

Discussion

You should call this method before attempting to display the mail composition interface. If it returns NO, you must not display the mail composition interface.

Availability

Available in iOS 3.0 and later.

Declared In

MFMailComposeViewController.h

Instance Methods

addAttachmentData:mimeType:fileName:

Adds the specified data as an attachment to the message.

- (void)addAttachmentData:(NSData*)attachment mimeType:(NSString*)mimeType fileName:(NSString*)filename

Parameters

attachment: The data to attach. Typically, this is the contents of a file that you want to include. This parameter must not be nil.
mimeType: The MIME type of the specified data. (For example, the MIME type for a JPEG image is image/jpeg.) For a list of valid MIME types, see http://www.iana.org/assignments/media-types/. This parameter must not be nil.
filename: The preferred filename to associate with the data. This is the default name applied to the file when it is transferred to its destination. Any path separator (/) characters in the filename are converted to underscore (_) characters prior to transmission. This parameter must not be nil.

Discussion

This method attaches the specified data after the message body but before the user’s signature. You may attach multiple files (using different file names) but must do so prior to displaying the mail composition interface. Do not call this method after presenting the interface to the user.

Availability

Available in iOS 3.0 and later.

Related Sample Code

Declared In

MFMailComposeViewController.h

setBccRecipients:

Sets the initial recipients to include in the email’s “Bcc” field.

- (void)setBccRecipients:(NSArray*)bccRecipients

Parameters

bccRecipients: An array of NSString objects, each of which contains the email address of a single recipient.

Discussion

This method replaces the previous blind carbon-copy recipients with the new ones listed in the bccRecipients parameter. This method does not filter out duplicate email addresses, so if duplicates are present, multiple copies of the email message may be sent to the same address.

You should call this method before you display the mail composition interface only. Do not call it after presenting the interface to the user.

Availability

Available in iOS 3.0 and later.

Related Sample Code

MessageComposer

Declared In

MFMailComposeViewController.h

setCcRecipients:

Sets the initial recipients to include in the email’s “Cc” field.

- (void)setCcRecipients:(NSArray*)ccRecipients

Parameters

ccRecipients: An array of NSString objects, each of which contains the email address of a single recipient.

Discussion

This method replaces the previous carbon-copy recipients with the new ones listed in the ccRecipients parameter. This method does not filter out duplicate email addresses, so if duplicates are present, multiple copies of the email message may be sent to the same address.

You should call this method before you display the mail composition interface only. Do not call it after presenting the interface to the user.

Availability

Available in iOS 3.0 and later.

Related Sample Code

MessageComposer

Declared In

MFMailComposeViewController.h

setMessageBody:isHTML:

Sets the initial body text to include in the email.

- (void)setMessageBody:(NSString*)body isHTML:(BOOL)isHTML

Parameters

body: The initial body text of the message. The text is interpreted as either plain text or HTML depending on the value of the isHTML parameter.
isHTML: Specify YES if the body parameter contains HTML content or specify NO if it contains plain text.

Discussion

This method replaces the previous body content with the new content. If the user has a signature file, the body content is inserted immediately before the signature. If you want to include images with your content, you must attach the images separately using the addAttachmentData:mimeType:fileName: method.

You should call this method before you display the mail composition interface only. Do not call it after presenting the interface to the user.

Availability

Available in iOS 3.0 and later.

Related Sample Code

MessageComposer

Declared In

MFMailComposeViewController.h

setSubject:

Sets the initial text for the subject line of the email.

- (void)setSubject:(NSString*)subject

Parameters

subject: The text to display in the subject line.

Discussion

This method replaces the previous subject text with the new text. You should call this method before you display the mail composition interface only. Do not call it after presenting the interface to the user.

Availability

Available in iOS 3.0 and later.

Related Sample Code

Declared In

MFMailComposeViewController.h

setToRecipients:

Sets the initial recipients to include in the email’s “To” field.

- (void)setToRecipients:(NSArray*)toRecipients

Parameters

toRecipients: An array of NSString objects, each of which contains the email address of a single recipient.

Discussion

This method replaces the previous recipients with the new ones listed in the toRecipients parameter. This method does not filter out duplicate email addresses, so if duplicates are present, multiple copies of the email message may be sent to the same address.

You should call this method before you display the mail composition interface only. Do not call it after presenting the interface to the user.

Availability

Available in iOS 3.0 and later.

Related Sample Code

MessageComposer

Declared In

MFMailComposeViewController.h

Constants

MFMailComposeResult

Result codes returned when the mail composition interface is dismissed.

enum MFMailComposeResult {
   MFMailComposeResultCancelled,
   MFMailComposeResultSaved,
   MFMailComposeResultSent,
   MFMailComposeResultFailed
};
typedef enum MFMailComposeResult MFMailComposeResult;

Constants

MFMailComposeResultCancelled

The user cancelled the operation. No email message was queued.

Available in iOS 3.0 and later.

Declared in MFMailComposeViewController.h.

MFMailComposeResultSaved

The email message was saved in the user’s Drafts folder.

Available in iOS 3.0 and later.

Declared in MFMailComposeViewController.h.

MFMailComposeResultSent

The email message was queued in the user’s outbox. It is ready to send the next time the user connects to email.

Available in iOS 3.0 and later.

Declared in MFMailComposeViewController.h.

MFMailComposeResultFailed

The email message was not saved or queued, possibly due to an error.

Available in iOS 3.0 and later.

Declared in MFMailComposeViewController.h.

Mail Message Error Domain

The domain used for NSError objects associated with the mail composition interface.

NSString *const MFMailComposeErrorDomain;

Constants

MFMailComposeErrorDomain

The error domain associated with NSError objects.

Available in iOS 3.0 and later.

Declared in MFMailComposeViewController.h.

MFMailComposeErrorCode

Error codes for NSError objects associated with the mail composition interface.

enum MFMailComposeErrorCode {
   MFMailComposeErrorCodeSaveFailed,
   MFMailComposeErrorCodeSendFailed
};
typedef enum MFMailComposeErrorCode MFMailComposeErrorCode;

Constants

MFMailComposeErrorCodeSaveFailed

An error occurred trying to save the email message to the Drafts folder.

Available in iOS 3.0 and later.

Declared in MFMailComposeViewController.h.

MFMailComposeErrorCodeSendFailed

An error occurred while trying to queue or send the email message.

Available in iOS 3.0 and later.

Declared in MFMailComposeViewController.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.