sc-cordova-plugin-email-composer v1.0.0

Cordova Email Plugin

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.

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.

Supported Platforms

• Android / Amazon FireOS
• Browser
• iOS
• OSX
• Windows

Installation

The plugin can be installed via Cordova-CLI and is publicly available on NPM.

Execute from the projects root folder:

$ cordova plugin add cordova-plugin-email-composer

Or install a specific version:

$ cordova plugin add cordova-plugin-email-composer@VERSION

Or install the latest head version:

$ cordova plugin add https://github.com/katzer/cordova-plugin-email-composer.git

Or install from local source:

$ cordova plugin add cordova-plugin-email-composer --searchpath <path>

Usage

The plugin creates the object cordova.plugins.email and is accessible after the deviceready event has been fired.

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

Determine email capability

The Email service is only available on devices which have configured an email account:

cordova.plugins.email.isAvailable(function (hasAccount) {});

To check for a specific mail client, just pass its uri scheme on iOS, or its name on Android as first parameter:

cordova.plugins.email.isAvailable('gmail', function (hasAccount, hasGmail) {});

Open an email draft

All properties are optional. After opening the draft the user may have the possibilities to edit the 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);

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();

Its possible to specify the email client. If the phone isn´t able to handle the specified scheme it will fallback to the system default:

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' });

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)
    ]
});

Permissions

The plugin might ask for granting permissions like reading email account informations. That's done automatically.

Its possible to request them manually:

cordova.plugins.email.requestPermission(function (granted) {...});

Or check if they have been granted already:

cordova.plugins.email.hasPermission(function (granted) {...});

In case of missing permissions the result of isAvailable might be wrong.

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:

HTML and CSS on Windows

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

Other limitations

• \<img> tags do not work properly on Android.
• Callbacks for windows and osx platform are called immediately.
• isAvailable does always return true for windows platform.

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

License

This software is released under the Apache 2.0 License.

Made with :yum: from Leipzig

© 2013 appPlant GmbH