iOS Developer Library

Developer

MFMailComposeViewController Class Reference

Options
Deployment Target:

On This Page
Language:

MFMailComposeViewController

Inheritance


Import Statement


Swift

import MessageUI

Objective-C

@import MessageUI;

Availability


Available in iOS 3.0 and later.

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

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 1The mail composition interface image: ../Art/mail_interface.jpg
  • Returns a Boolean indicating whether the current device is able to send email.

    Declaration

    Swift

    class func canSendMail() -> Bool

    Objective-C

    + (BOOL)canSendMail

    Return Value

    YEStrue if the device is configured for sending email or NOfalse if it is not.

    Discussion

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

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func setSubject(_ subject: String!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func setToRecipients(_ toRecipients: [AnyObject]!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func setCcRecipients(_ ccRecipients: [AnyObject]!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func setBccRecipients(_ bccRecipients: [AnyObject]!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 3.0 and later.

  • Sets the initial body text to include in the email.

    Declaration

    Swift

    func setMessageBody(_ body: String!, isHTML isHTML: Bool)

    Objective-C

    - (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 YEStrue if the body parameter contains HTML content or specify NOfalse 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.

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 3.0 and later.

  • Adds the specified data as an attachment to the message.

    Declaration

    Swift

    func addAttachmentData(_ attachment: NSData!, mimeType mimeType: String!, fileName filename: String!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 3.0 and later.

  • Result codes returned when the mail composition interface is dismissed.

    Declaration

    Swift

    struct MFMailComposeResult { init(_ value: UInt32) var value: UInt32 }

    Objective-C

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

    Constants

    • MFMailComposeResultCancelled

      MFMailComposeResultCancelled

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

      Available in iOS 3.0 and later.

    • MFMailComposeResultSaved

      MFMailComposeResultSaved

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

      Available in iOS 3.0 and later.

    • MFMailComposeResultSent

      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.

    • MFMailComposeResultFailed

      MFMailComposeResultFailed

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

      Available in iOS 3.0 and later.

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    let MFMailComposeErrorDomain: String

    Objective-C

    NSString *const MFMailComposeErrorDomain;

    Constants

    • MFMailComposeErrorDomain

      MFMailComposeErrorDomain

      The error domain associated with NSError objects.

      Available in iOS 3.0 and later.

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

    Declaration

    Swift

    struct MFMailComposeErrorCode { init(_ value: UInt32) var value: UInt32 }

    Objective-C

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

    Constants

    • MFMailComposeErrorCodeSaveFailed

      MFMailComposeErrorCodeSaveFailed

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

      Available in iOS 3.0 and later.

    • MFMailComposeErrorCodeSendFailed

      MFMailComposeErrorCodeSendFailed

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

      Available in iOS 3.0 and later.

    Import Statement

    Objective-C

    @import MessageUI;

    Swift

    import MessageUI

    Availability

    Available in iOS 3.0 and later.