cordova-plugin-email

    1.2.7 • Public • Published

    Cordova Email Plugin

    Greenkeeper badge

    Build Status Build status npm version Dependency Status devDependency Status

    The plugin provides access to the 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.

    NPM

    Feel free to donate

    Click here to lend your support and make a donation at www.pledgie.com ! Or donate Bitcoins: bitcoin:3NKtxw1SRYgess5ev4Ri54GekoAgkR213D

    Bitcoin

    Also via greenaddress

    Installation

    $ cordova plugin add cordova-plugin-email

    Or if you want to use the development version (nightly build), which maybe not stable!:

    cordova plugin add cordova-plugin-email@next
    

    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.

    Overview

    1. Supported Platforms
    2. Installation
    3. ChangeLog
    4. Using the plugin
    5. Examples
    6. Quirks

    Supported Platforms

    • iOS
    • Android
    • Amazon FireOS
    • Windows
    • Browser

    PhoneGap Build

    Add the following xml to your config.xml to always use the latest version of this plugin:

    <gap:plugin name="cordova-plugin-email-composer" version="0.8.3" source="npm" />

    Changelog

    • See CHANGELOG.md to get the full changelog for the plugin.

    Using the plugin

    The plugin creates the object cordova.plugins.email with following methods:

    1. email.isAvailable
    2. email.open

    Plugin initialization

    The plugin and its methods are not available before the deviceready event has been fired.

    document.addEventListener('deviceready', function () {
        // cordova.plugins.email is now available
    }, false);

    Determine if the device is capable to send emails

    The ability to send emails can be revised through the email.isAvailable interface. The method takes a callback function, passed to which is a boolean property. Optionally the callback scope can be assigned as a second parameter.

    The Email service is only available on devices capable which are able to send emails. E.g. which have configured an email account and have installed an email app. You can use this function to hide email functionality from users who will be unable to use it.

    cordova.plugins.email.isAvailable(
        function (isAvailable) {
            // alert('Service is not available') unless isAvailable;
        }
    );

    If you want to open a draft in a specific application, just pass its uri scheme on iOS, or its name on Android as first parameter, to check whether the application is installed or not. The callback function will return a second parameter of type boolean then.

    cordova.plugins.email.isAvailable(
        urischeme, function (isAvailable, withScheme) {
            // alert('Service is not available') unless isAvailable;
        }
    );
     

    Note: If the user didn't have any email account configured on iOS this will also return false

    Open a pre-filled email draft

    A pre-filled email draft can be opened through the email.open or email.openDraft interface. The method takes a hash as an argument to specify the email's properties. All properties are optional. Further more it accepts an callback function to be called after the email view has been dismissed.

    After opening the draft the user may have the possibilities to edit, delete or send the email.

    Further informations

    • An configured email account is required to send emails.
    • Attachments can be either base64 encoded datas, files from the the device storage or assets from within the www folder.
    • The default value for isHTML is true.
    • Its possible to specify the email app on Android and iOS.
    • See the examples for how to create and show an email draft.
    cordova.plugins.email.open({
        to:          Array, // email addresses for TO field
        cc:          Array, // email addresses for CC field
        bcc:         Array, // email addresses for BCC field
        attachments: Array, // file paths or base64 data streams
        subject:    String, // subject of the email
        body:       String, // email body (for HTML, set isHtml to true)
        isHtml:    Boolean, // indicats if the body is HTML or plain text
    }, callback, scope);

    Examples

    Open an email draft

    The following example shows how to create and show an email draft pre-filled with different kind of properties.

    cordova.plugins.email.open({
        to:      'max@mustermann.de',
        cc:      'erika@mustermann.de',
        bcc:     ['john@doe.com', 'jane@doe.com'],
        subject: 'Greetings',
        body:    'How are you? Nice greetings from Leipzig'
    });

    Of course its also possible to open a blank draft.

    cordova.plugins.email.open();

    Send HTML encoded body

    Its possible to send the email body either as text or HTML. In the case of HTML the isHTML properties needs to be set.

    cordova.plugins.email.open({
        to:      'max@mustermann.de',
        subject: 'Greetings',
        body:    '<h1>Nice greetings from Leipzig</h1>',
        isHtml:  true
    });

    When building for the browser, you cannot use HTML in the body content. Internally, this plugin generates a "mailto:"-style link to support browsers, and the mailto URI scheme only supports plain text body content. See RFC6068 for more details on mailto URIs.

    Get informed when the view has been dismissed

    The open method supports additional callback to get informed when the view has been dismissed.

    cordova.plugins.email.open(properties, function () {
        console.log('email view dismissed');
    }, this);

    Adding attachments

    Attachments can be either base64 encoded datas, files from the the device storage or assets from within the www folder.

    Attach Base64 encoded content

    The code below shows how to attach an base64 encoded image which will be added as a image with the name icon.png.

    cordova.plugins.email.open({
        subject:     'Cordova Icon',
        attachments: 'base64:icon.png//iVBORw0KGgoAAAANSUhEUgAAADwAAAA8CAYAAAA6/...'
    });

    Attach files from the device storage

    The path to the files must be defined absolute from the root of the file system.

    cordova.plugins.email.open({
        attachments: 'file:///storage/sdcard/icon.png', //=> Android
    });

    Attach native app resources

    Each app has a resource folder, e.g. the res folder for Android apps or the Resource folder for iOS apps. The following example shows how to attach the app icon from within the app's resource folder.

    cordova.plugins.email.open({
        attachments: 'res://icon.png' //=> res/drawable/icon (Android)
    });

    Attach assets from the www folder

    The path to the files must be defined relative from the root of the mobile web app folder, which is located under the www folder.

    cordova.plugins.email.open({
        attachments: [
            'file://img/logo.png', //=> assets/www/img/logo.png (Android)
            'file://css/index.css' //=> www/css/index.css (iOS)
        ]
    });

    Specify email app

    Its possible to specify the email app which shall open the draft for further editing. Just pass its scheme name through the drafts app-attribute. If the phone isn´t able to handle the specified scheme it will fallback to standard.

    // Specify app by scheme name
    cordova.plugins.email.open({
        app: 'mailto',
        subject: 'Sent with mailto'
    })

    On Android the app can be specified by either an alias or its package name. The alias gmail is available by default.

    // Add app alias
    cordova.plugins.email.addAlias('gmail', 'com.google.android.gm');
     
    // Specify app by name or alias
    cordova.plugins.email.open({
        app: 'gmail',
        subject: 'Sent from Gmail'
    })

    Quirks

    HTML and CSS on Android

    Even Android is capable to render HTML formatted mails, most native Mail clients like the standard app or Gmail only support rich formatted text while writing mails. That means that CSS cannot be used (no class and style support).

    The following table gives an overview which tags and attributes can be used:

    • <a href="...">
    • <b>
    • <big>
    • <blockquote>
    • <br>
    • <cite>
    • <dfn>
    • <div align="...">
    • <em>
    • <font size="..." color="..." face="...">
    • <h1>
    • <h2>
    • <h3>
    • <h4>
    • <h5>
    • <h6>
    • <i>
    • <img src="...">
    • <p>
    • <small>
    • <strike>
    • <strong>
    • <sub>
    • <sup>
    • <tt>
    • <u>

    HTML and CSS on Windows

    HTML+CSS formatted body are not supported through the native API for Windows.

    Contributing

    1. Fork it
    2. Create your feature branch (git checkout -b my-new-feature)
    3. Commit your changes (git commit -am 'Add some feature')
    4. Push to the branch (git push origin my-new-feature)
    5. Create new Pull Request

    Development

    Testing

    Android and iOS Tooling setup, see

    export PLATFORM=android # or ios ..
    npm run clean && npm run setupDemoApp && npm run build
    

    License

    This software is released under the Apache 2.0 License.

    © 2013-2016 appPlant UG, Inc. All rights reserved

    Install

    npm i cordova-plugin-email

    DownloadsWeekly Downloads

    215

    Version

    1.2.7

    License

    MIT

    Unpacked Size

    109 kB

    Total Files

    20

    Last publish

    Collaborators

    • hypery2k