Composing E-mail and SMS in Corona
Those who have been waiting for the ability to compose e-mails (with attachments) and SMS (text messages) from within your Corona app will be happy to hear that both features have been made available via Daily Builds (just before the holidays).
Today, I’m going to show you exactly how you can take advantage of the incredibly simple (but infinitely useful) API so you can incorporate these features into your apps right away.
native.showPopup()
This is the function that handles everything, and as you’ll see in a moment, it’s very easy to use. For a more complete explanation, please see the native.showPopup() API documentation.
Composing an E-mail
To send an e-mail, you pass “mail” as the first argument to the function, and pass an options table with the following (optional) fields:
- to – a string for one recipient, or an array of strings for multiple recipients.
- subject – a string representing the e-mail subject line.
- body – a string representing the e-mail body content.
- isBodyHTML – a boolean (true/false) used to toggle whether body contains HTML or not (default is false).
- attachment – a table with three keys: baseDir, filename, and type (e.g. “image”).
Below is a simple plain text e-mail with an image attachment:
{
to = "john.doe@somewhere.com",
subject = "My High Score",
body = "I scored over 9000!!! Can you do better?",
attachment = { baseDir=system.DocumentsDirectory,
filename="Screenshot.png", type="image" },
}
native.showPopup("mail", options)
Below is an HTML e-mail with multiple correspondents as well as an attachment (if you can’t see the code below, go here to view it):
NOTE: When composing an HTML e-mail, don’t forget to include the opening and closing HTML tags.
When you call the function (native.showPopup), it will open up a new e-mail composition in your device’s e-mail app. The fields you do not include in your options table will be blank, but users will have the option of populating this info on their own (as usual). They are solely responsible for actually sending the message.
Composing an SMS message
Composing an SMS is similar, but has fewer options than e-mail. For the first argument, you’ll pass “sms” instead of “mail” and a table with the following (once again, optional) parameters:
- to – a single string (representing a phone number), or an array of strings (for multiple recipients).
- message – a string with the message body. Remember, SMS messages should be kept to about the size of a tweet (140 characters, give or take).
Below is an example SMS with no recipients specified (users will specify recipients from the SMS app of their device):
{
body = "I scored over 9000!!! Can you do better?"
}
native.showPopup("sms", options)
And here’s another example, this time with multiple recipients specified:
{
to = { "1234567890", "9876543210" },
body = "I scored over 9000!!! Can you do better?"
}
native.showPopup("sms", options)
Remember, users will be transferred to their device’s e-mail/SMS app and will be solely responsible for the sending of the messages, and/or filling out any fields that you left out of the options table.
Usage Suggestions
So now you know how to compose e-mail and text messages from your Corona app, and I’m sure you’ve got tons of ideas as to how you’re going to use it in your app. But in case you’re having trouble, here’s some suggestions:
- Encourage users to share screenshots of their progress via e-mail.
- Create some kind of greeting card feature where users can customize a message and send it to a friend.
- Allow users to text or e-mail people they know about your app (and optionally include a tasteful promo graphic).
- Generate a special code that users can send to their friends via e-mail or SMS to gift items.
- BONUS: Take advantage of app URL schemes in conjunction with any of the above to launch your app in interesting new ways.
Of course, one could get away with pushing the sending of e-mails and texts to their friends, so moderation is key here. But providing your users with an easy, familiar way to spread the word about your app could be just what your app needs to go viral.
Remember, this feature is only available to subscribers through the Daily Builds at the moment. Subscribe now to take advantage of this new feature, along with tons of other great new features such as remote push notifications, url scheme handling, Facebook single sign-on (to name a few), and everything else we’re continuing to roll out on a daily basis.
RSS feed
I’m guessing this would not work on an iPod touch, right?
@Joe Cool: The email portion will work on an iPod touch, and the SMS *should* open the Messages app just fine if the iPod touch has iOS 5 installed.
Works like a breeze
tested it on Android and iOS
keep up the good work,
Jürgen
@jpnne: Thanks for the feedback! Glad to see it’s working for you.
yeah! Great work Jonathan as always. Please see my post in the forums about the troubles that popup when PUSH enabling certificates and trying to build in Corona.
Are there any special permissions needed for the app? Attempted on my Vibrant ( Running Android 4.03 and it did not work. nothing opened.
Great Job!!
One step closer to Calendars and Contacts!!!
Thanks,
Richard
Thanks Jonathan. Is it possible to bypass sending the user to the native SMS app and to send the text in the background?
@Jeff: You cannot bypass the native SMS app and send the text in the background because that would enable apps to have the ability to send SPAM on the user’s behalf. These features are mainly for pre-populating emails and SMS messages. The only thing you can do “extra” is attach images from your app to emails (Doodle Jump does this—or used to anyway).
i can not get this to work on my galaxy s vibrant – rooted or my wifes, stock vibrant..
nothing happens..
great thanks Jon.
@ansca: can we have multipart please? (textbody, altbody, textpart or whatever option)
(eg from PHPMailer)
$mail->IsHTML(true);
$mail->Body = “Test 1 of PHPMailer htmlThis is a test”;
$mail->AltBody=”This is text only alternative body.”;
SpamAssassin specifically included a rule that adds spam points for *only* sending an HTML part
“Message only has text/html MIME parts – Body Rule”
http://help.campaignmonitor.com/topic.aspx?t=104
thanks
J
never mind. Go ahead and say it… Larry did you read the flipping version number.. downloaded and installed latest build.. worked like a champ… – i feel like a chump.
thanks
I’m quite interested in this statement:
“Generate a special code that users can send to their friends via e-mail or SMS to gift items.”
How would you do this?
Thanks,
Matt.
How do you reference the attachments in the body? i.e. inline graphics.
Thanks
jmp909,
The e-mail popup will automatically create an alt body for you based on the body text you give it. If you give it an HTML body, then the alt body will be plain text. If you give the body plain text, then the alt body will be set to HTML. I’ve confirmed this to work on Android today (I have not confirmed this on iOS yet). If you send it to a gmail account, you can easily look at the internals of the e-mail by clicking the “Show Original” option from the Reply button’s dropdown menu.
So, this should help prevent e-mails from being blocked by spam filters as you were saying.
Regarding the alt-body, I don’t think this should be settable. This is because the settings you are providing here are merely initializing the mail client’s fields which the user can change before sending the e-mail. This means that the end-user can change the body text before sending the e-mail, making it inconsistent with the alt-body that you’ve set within the Lua code. Now, if we were sending the e-mail in the background without UI then that would be a different matter. Anyways, that’s my 2 cents.
@Matt Webster: Regarding the generating a code for users to send to their friends (who also own the app), the high-level concept would be if your app was web-connected, every “object” in your app could have a unique ID associated with it (in the online database). When the user “gifts” the object to another user (by sending the object’s unique ID via email or sms), the “owner” of that object would change as soon as the other user enters the ID of the object.
I’m sure there is a way to do it completely locally (though I’m not sure how secure it would be, as it would probably be easy to crack the code).
What a great addition!
In less than an hour today (which included downloading the daily build) I added the ability for users of one of my apps to send a screenshot to their friends via email.
Very cool way for users to help get the word out about the app. Thanks!
This is the best blog design and article. Very nice job. Thank you very much
@jonathan
Is there a way to change the labels/language on the buttons(send,cancel) in mail popup and when you cancel the mail change the delete/save draft + cancel buttons?
This is awesome!! Thank you @jonathan!
This there a way of linking this to something like google analytics to see how many times it is being used?
Would adding a email footer image that is loaded remotely do the trick?
It’s not working on my iPhone 3GS.
Also, in the simulator, I get the following error (iPhone 3 / 4 / Droid):
“ERROR: native.showPopup() does not support mail popups on this device.”
I am using Version 2011.714
Also, what’s worse, I have the facebook connect function in my App:
facebook.login( “my-number-here”, listener, {“publish_stream”} )
This used to pop up a facebook-connect-window on top of the App. With the newest build the browser will open and send me to a FB-connect-page…
A round of applause for your blog.Really looking forward to read more.
Is there a know issue with e-mail attachment with the kindle? Everything works great in iOS. Are there special permissions?
I am testing it in an Ipod touch and i cant get it works…all time says:
attempt to call field ‘showPopup’ (a nil value)
Some notes for those having trouble getting this feature to work properly:
Jonathan,
Just began testing the native.showPopup() on the iPhone and I have found that when a variable that contains multiple email addresses is used in the “to” or “cc” options the associated fields in the email popup fail to populate.
@Virgil Siegle: How are you passing multiple email addresses? Are you passing them all inside of a single string, or are you passing them as individual strings in an array? You should be passing them as individual strings in an array. For example:
This is wrong:
{ “johndoe@email.com, janedoe@email.com, me@mail.com” }
This is right:
{ “johndoe@email.com”, “janedoe@email.com”, “me@mail.com” }
Notice how in the correct example (the second one), each email address has their own set of quotes, and then a comma, and then another email address with its own quotes. The commas separating the quotes is an array of strings. The commas within the quotes are just part of a single string.
Jonathan,
Thanks for your quick reply.
I am parsing the the addresses to include quotes and they are formatted as a comma separated array exactly as you describe in the “right” method. This array is then placed in a local global and added as an option like so: cc = {myGlobal}.
Virgil
Are there any Android permissions necessary to do this?
We learned the hard way:
Make sure your device has an email account already configured. If you don’t have one configured then this just fails silently (unlike Objective-C based apps).
Hopefully that will be addressed in a future build.
I still have not found a way to add more than one email address unless they are hard coded like Jonathan suggest above. When hard coded like this { “johndoe@email.com”, “janedoe@email.com”, “me@mail.com” } it will populate the popup properly. When these address are inserted into a global the popup’s address field will fail to populate.
Really could use some help on this. I have two apps that I can’t finish until this is solved.
can someone look into this?
not able to assign global, example given by Virgil above. Hard coded works fine.
another example,
local str = {“johndoe@email.com”, “janedoe@email.com”, “me@mail.com”}
local options = {cc={str}} <– don't work
local options = {cc={“johndoe@email.com”, “janedoe@email.com”, “me@mail.com”}} <– works fine
how come?
thanks for your attention.
simon
@simon
You need to specify the str table directly, not inside a subtable.
local options = {cc=str}
sean
In you example what is the value of “str”?
I have found no joy when trying to add more than one address to the variable.
I have used something similar to the following to populate it.
local str = ‘”john.doe@somewhere.com”‘..’”john.smith@somewhere.com”‘
It will produce an empty “cc” field.
If I remove one address it will populate.
Is this broken at the moment? I can’t get any samples working, always results in:
Lua Runtime Error: lua_pcall failed with status: 2, error message is: ?:0: attempt to call field ‘showPopup’ (a nil value)
Elfod,
This API is not available in the release version, build 704. This API is only available in the newest daily builds, which are available to paid subscribers.