System Messaging

Programming Topics for

iOS
Contents

About System Messaging 4

Organization of This Document 4

Sending a Mail Message 5

Sending an SMS Message 8

Document Revision History 9

2010-11-15 | Copyright © 2010 Apple Inc. All Rights Reserved.

2
Listings

Sending a Mail Message 5

Listing 1 Posting the mail composition interface 6

2010-11-15 | Copyright © 2010 Apple Inc. All Rights Reserved.

3
About System Messaging

iOS lets you present a standard email or SMS composition interface from within your app. In both cases, you
can programmatically preconfigure the message with recipients and content, which the user can then edit
before sending. Outgoing mail and SMS messages are automatically handled by the system’s Mail and Messages
queues.

Organization of This Document

This document includes the following articles:
● “Sending a Mail Message” (page 5) explains how to use the standard mail composition interface as well
as how to write a delegate method for dismissing it when the user is finished.
● “Sending an SMS Message” (page 8) explains how to configure and present a standard SMS message
composition interface, as well as how to dismiss it with a delegate object.

2010-11-15 | Copyright © 2010 Apple Inc. All Rights Reserved.

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

Note: In all versions of iOS, you can also provide an email composition interface by creating and
opening a URL that uses the mailto scheme. URLs of this type are automatically handled by the
built-in Mail app. For more information on how to open a URL of this type, see “Communicating with
Other Applications” in iOS App Programming Guide .

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.

2010-11-15 | Copyright © 2010 Apple Inc. All Rights Reserved.

5
Sending a Mail Message

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:@"[email protected]",

nil];

NSArray *ccRecipients = [NSArray arrayWithObjects:@"[email protected]",

@"[email protected]", nil];

NSArray *bccRecipients = [NSArray arrayWithObjects:@"[email protected]",

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.

2010-11-15 | Copyright © 2010 Apple Inc. All Rights Reserved.

6
Sending a Mail Message

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

2010-11-15 | Copyright © 2010 Apple Inc. All Rights Reserved.

7
Sending an SMS Message

In iOS 4.0 and later, you can send text messages from within your application. This feature is strictly for sending
messages. Incoming SMS messages go to the built-in Messages app.

To use the SMS 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 provide the standard user interface for composing an SMS (Short Message Service) message, use the
MFMessageComposeViewController class. Create an instance of this class and assign it a delegate object.
The delegate must conform to the MFMessageComposeViewControllerDelegate protocol.

Before presenting the composition interface to the user, you can configure initial recipients and message
content. With setup complete, call the UIViewControllerpresentModalViewController:animated:
method to present the SMS message composition view controller modally.

While the interface is visible, the user can edit the recipients list and message content. The user then sends
the message, or cancels it, by tapping the appropriate control in the interface.

If the user requests that the message be sent, the system queues it for delivery and invokes the delegate
object’s messageComposeViewController:didFinishWithResult: method. The result is one of “sent,”
“cancelled,” or “failed.”

Finally, the delegate is responsible for dismissing the message composition view controller, which it should
do by calling the UIViewController dismissModalViewControllerAnimated: method.

For a complete description of the MFMessageComposeViewController class, see

MFMessageComposeViewController Class Reference .

2010-11-15 | Copyright © 2010 Apple Inc. All Rights Reserved.

8
Document Revision History

This table describes the changes to System Messaging Programming Topics for iOS .

Date Notes

2010-11-15 New document that explains how to send mail and SMS messages from
your app.

Some of this document’s content was previously available in Device

Features Programming Guide .

2010-11-15 | Copyright © 2010 Apple Inc. All Rights Reserved.

9
Apple Inc.
Copyright © 2010 Apple Inc.
All rights reserved.

No part of this publication may be reproduced,

stored in a retrieval system, or transmitted, in any
form or by any means, mechanical, electronic,
photocopying, recording, or otherwise, without
prior written permission of Apple Inc., with the
following exceptions: Any person is hereby
authorized to store documentation on a single
computer for personal use only and to print
copies of documentation for personal use
provided that the documentation contains
Apple’s copyright notice.
No licenses, express or implied, are granted with
respect to any of the technology described in this
document. Apple retains all intellectual property
rights associated with the technology described
in this document. This document is intended to
assist application developers to develop
applications only for Apple-labeled computers.
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010

Apple, the Apple logo, and Xcode are trademarks

of Apple Inc., registered in the U.S. and other
countries.
iOS is a trademark or registered trademark of
Cisco in the U.S. and other countries and is used
under license.
Even though Apple has reviewed this document,
APPLE MAKES NO WARRANTY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS
DOCUMENT, ITS QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED
“AS IS,” AND YOU, THE READER, ARE ASSUMING THE
ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS DOCUMENT, even if advised of
the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE
ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL
OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,
agent, or employee is authorized to make any
modification, extension, or addition to this warranty.
Some states do not allow the exclusion or limitation
of implied warranties or liability for incidental or
consequential damages, so the above limitation or
exclusion may not apply to you. This warranty gives
you specific legal rights, and you may also have other
rights which vary from state to state.