<doc>
	<legacy_id>1617</legacy_id>
	<name>revMail</name>
	<type>command</type>

	<syntax>
		<example>revMail <i>address, </i>[<i>ccAddress, </i>[<i>mailSubject, </i>[<i>messageBody</i>]]]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Opens a new email message in the user's email program.</summary>

	<examples>
<example>revMail &quot;guido@example.net&quot;</example>
<example>revMail &quot;help@example.com&quot;,,&quot;Help!&quot;,field &quot;Message&quot;</example>
<example><p>revMail &quot;support@runrev.com&quot;,&quot;me@example.org&quot;,&quot;Installation Help&quot;</p></example>
<example>revMail the bugAddress of this stack,,&quot;Auto Bug Report&quot;,myBugsList</example>
	</examples>

	<history>
		<introduced version="2.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="4.5.2">4.5.2</changed>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
		<category>Networks &amp; Communication</category>
		<category>Standalone Applications</category>
	</classification>

	<references>
		<command tag="revGoURL">revGoURL Command</command>
		<command tag="revMailUnicode">revMailUnicode Command</command>
		<command tag="mobileComposeMail">mobileComposeMail Command</command>
		<command tag="mobileComposeUnicodeMail">mobileComposeUnicodeMail Command</command>
		<command tag="mobileComposeHtmlMail">mobileComposeHtmlMail Command</command>
	</references>

	<description>
	<overview>Use the <b>revMail</b> <glossary tag="command">command</glossary> to create an email message from within a <object tag="stack">stack</object>.</overview>

		<parameters>
<parameter>
	<name>address</name>
	<description>A string consisting of one or more email addresses, separated by commas. These addresses appear in the 'To:' header of the email message.</description>
</parameter>
<parameter>
	<name>ccAddress</name>
	<description>A string consisting of one or more email addresses, separated by commas. These addresses appear in the 'Cc:' header of the email message.</description>
</parameter>
<parameter>
	<name>mailSubject</name>
	<description>A string consisting of a single line. This text appears in the 'Subject:' header of the email message.</description>
</parameter>
<parameter>
	<name>messageBody</name>
	<description>A string. This text appears in the 'body' of the email message.</description>
</parameter>		</parameters>

	<value></value>
	<comments>When LiveCode executes the <b>revMail</b> <glossary tag="command">command</glossary>, the user's email program is opened (if necessary) and a new email message with the specified <glossary tag="parameter">parameters</glossary> is created. The user can change any of the settings before sending the message, and the message is not sent automatically: the user must explicitly send it (for example, by clicking a 'Mail' button in the email program).<p></p><p>On Mac OS systems, the mail message is opened in the application the user has set for the 'mailto:' protocol in the Internet control panel (or, for older system versions, Internet Config).</p><p></p><p>On iOS, <b>revMail</b> hooks into the iOS MessageUI framework.</p><p></p><p>On return on iOS, the result is set to one of:</p><p>* <i>not configured</i> - if the user has turned off or has not setup mail access on their device</p><p>* <i>cancel</i> - if the user chooses to cancel the send</p><p>* <i>saved</i> - if the user chose to save the message in drafts</p><p>* <i>sent</i> - if the user elected to send the email</p><p>* <i>failed</i> - if sending the email was attempted, but it failed</p><p></p><p>On return on Android, the result is set to:</p><p>* <i>unknown</i> - On Android the email activity does not return its status back to the calling activity so the result is set to 'unknown' in all cases</p><p><code tag=""><important></code> <code tag="">On</code> <glossary tag="Mac OS">Mac OS systems</glossary>, the <b>revMail</b> <glossary tag="command">command</glossary> requires that AppleScript be installed and that the GURL <glossary tag="Apple Event">Apple Event</glossary> be supported. GURL support is included in <glossary tag="Mac OS">Mac OS</glossary> 8.5 or later, and is available for <glossary tag="Mac OS">Mac OS</glossary> 8.0 and 8.1 if the Internet Scripting file is installed in the Scripting Additions folder inside the Extensions folder. (This <keyword tag="file">file</keyword> is installed by the Internet Access installer on the 8.0 installation CD.) The <b>revMail</b> <glossary tag="command">command</glossary> is not supported for <glossary tag="Mac OS">Mac OS</glossary> versions before 8.0.</important><p></p><p>For some older email programs, it may not be possible to specify a <i>ccAddress</i>, <i>mailSubject</i>, or <i>messageBody</i>. Generally, the <command tag="revMail">revMail</command> <glossary tag="command">command</glossary> still works with such programs, but only the 'To:' header is set.</p><p></p><p><code tag=""><note></code><code tag=""> When included in a</code> <glossary tag="standalone application">standalone application</glossary>, the <glossary tag="Common library">Common library</glossary> is implemented as a hidden <command tag="group">group</command> and made available when the <command tag="group">group</command> receives its first <message tag="openBackground">openBackground</message> message. During the first part of the <glossary tag="application">application's</glossary> startup process, before this <keyword tag="message box">message</keyword> is sent, the <b>revMail</b> <glossary tag="command">command</glossary> is not yet available. This may affect attempts to use this <glossary tag="command">command</glossary> in <message tag="startup">startup</message>, <message tag="preOpenStack">preOpenStack</message>, <message tag="openStack">openStack</message>, or <message tag="preOpenCard">preOpenCard</message> <glossary tag="handler">handlers</glossary> in the <glossary tag="main stack">main stack</glossary>. Once the <glossary tag="application">application</glossary> has finished starting up, the <command tag="start using">library</command> is available and the <b>revMail</b> <glossary tag="command">command</glossary> can be used in any <glossary tag="handler">handler</glossary>.</note><p></p><p></p><note>Once the <b>revMail</b> command is called, you have no more control over what the user does with the message. They are free to modify the message and the addresses as they see fit.</note></comments>
	</description>
</doc>