Class

MFMailComposeViewController

The MFMailComposeViewController class provides a standard interface for managing, editing, and sending an email message. Use this view controller to display a standard email interface inside your app. Before presenting the interface, populate the fields with initial values for the subject, email recipients, body text, and attachments of the email. After presenting the interface, the user can edit your initial values before sending the email.

Overview

The composition interface does not guarantee the delivery of your email message; it only lets you construct the initial message and present it for user approval. The user may opt to cancel the composition interface, in which case the message and its contents are discarded. If the user opts to send the message, the message is queued in the user’s Mail app outbox. The Mail app is ultimately responsible for sending the message.

Figure 1

The mail composition interface

An alternate way to compose emails is to create and open a URL that uses the mailto scheme. URLs of that type are directed to the built-in Mail app, which uses your URL to configure a message. For information about the structure of mailto URLs, see Apple URL Scheme Reference.

Checking the Availability of the Composition Interface

Before presenting the mail compose view controller, always call the the canSendMail() method to see if the current device is configured to send email. 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 false.

Listing 1

Checking the availability of mail services

if !MFMailComposeViewController.canSendMail() {
    print("Mail services are not available")
    return
}

Configuring and Displaying the Composition Interface

After verifying that mail services are available, you can create and configure the mail composition view controller and then present it like you would any other view controller. Use the methods of this class to specify the subject, recipients, and message body of the email, including any attachments you want to send with the message. Listing 2 shows how to configure the composition interface and present it modally. Always assign a delegate to the mailComposeDelegate property. The delegate is responsible for dismissing the composition interface later.

Listing 2

Configuring and presenting the composition interface

let composeVC = MFMailComposeViewController()
composeVC.mailComposeDelegate = self
 
// Configure the fields of the interface.
composeVC.setToRecipients(["address@example.com"])
composeVC.setSubject("Hello!")
composeVC.setMessageBody("Hello from California!", isHTML: false)
 
// Present the view controller modally.
self.presentViewController(composeVC, animated: true, completion: nil)

The mail compose view controller is not dismissed automatically. When the user taps the buttons to send the email or cancel the interface, the mail compose view controller calls the mailComposeController(_:didFinishWith:error:) method of its delegate. Your implementation of that method must dismiss the view controller explicitly, as shown in Listing 3. You can also use this method to check the result of the operation.

Listing 3

Dismissing the mail compose view controller

func mailComposeController(controller: MFMailComposeViewController,
                           didFinishWithResult result: MFMailComposeResult, error: NSError?) {
    // Check the result or perform other tasks.
    
    // Dismiss the mail compose view controller.
    controller.dismissViewControllerAnimated(true, completion: nil)
}

The user can delete a queued message before it is sent. Although the view controller reports the success or failure of the operation to its delegate, this class does not provide a way for you to verify whether the email was actually sent.

For more information on how to present and dismiss view controllers, see View Controller Programming Guide for iOS.

Topics

Determining Mail Availability

class func canSendMail()

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

Setting Mail Fields Programmatically

func setSubject(String)

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

func setToRecipients([String]?)

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

func setCcRecipients([String]?)

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

func setBccRecipients([String]?)

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

func setMessageBody(String, isHTML: Bool)

Sets the initial body text to include in the email.

func addAttachmentData(Data, mimeType: String, fileName: String)

Adds the specified data as an attachment to the message.

Accessing the Delegate

var mailComposeDelegate: MFMailComposeViewControllerDelegate?

The mail composition view controller’s delegate.

Constants

enum MFMailComposeResult

Result codes returned when the mail composition interface is dismissed.

Mail Message Error Domain

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

enum MFMailComposeError.Code

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

Relationships

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software