MFMailComposeViewController Class Reference

Inherits from
Conforms to
Availability
Available in iOS 3.0 and later.
Declared in
MFMailComposeViewController.h
Related sample code

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