capacitor-email-composer

Capacitor E-Mail Composer

This Plugin is used to open a native E-Mail Composer within your Capacitor App.

Table of Content

• Install
• Attachments
  • Device Storage
  • Native resources
  • Assets
  • Base64
• API
  • hasAccount()
  • open(...)
  • Interfaces
• Changelog
• Troubleshooting
  • TransactionTooLargeException

Install

npm install capacitor-email-composer
npx cap sync

Attachments

You can add attachments to the draft mail by using the attachments option in the open(...) method. Every attachment needs a type and a path. If you are adding a base64 type attachment, you also need to set the name:

Device Storage

The path to the files must be defined absolute from the root of the file system. On Android the user has to allow the app first to read from external storage!

import { EmailComposer } from 'capacitor-email-composer'

EmailComposer.open({
  attachments: [{
    type: 'absolute',
    path: 'storage/sdcard/icon.png' // Android
  }]
})

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

import { EmailComposer } from 'capacitor-email-composer'

EmailComposer.open({
  attachments: [{
    type: 'resource',
    path: 'icon.png'
  }]
})

Assets

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

import { EmailComposer } from 'capacitor-email-composer'

EmailComposer.open({
  attachments: [{
    type: 'asset',
    path: '/icon/favicon.png' // starting slash is important
  }]
})

Base64

The code below shows how to attach a base64 encoded image which will be added as an image. You must set a name.

import { EmailComposer } from 'capacitor-email-composer'

EmailComposer.open({
  attachments: [{
    type: 'base64',
    path: 'iVBORw0KGgoAAAANSUhEUgAAADwAAAA8CAYAAAA6...',
    name: 'icon.png' // this is required
  }]
})

API

• hasAccount()
• open(...)
• Interfaces

hasAccount()

hasAccount() => Promise<HasAccountResult>

Checks if the User can send a Mail iOS: Check if the current Device is configured to send mail Android: Currently does nothing

Returns: Promise<HasAccountResult>

Since: 1.0.0

---

open(...)

open(options?: OpenOptions | undefined) => Promise<void>

Open the E-Mail Composer

Param	Type	Description
options	OpenOptions	optional Options to prefill the E-Mail

Since: 1.0.0

---

Interfaces

HasAccountResult

Prop	Type	Since
hasAccount	boolean	1.0.0

OpenOptions

Prop	Type	Description	Since
to	string[]	email addresses for TO field	1.0.0
cc	string[]	email addresses for CC field	1.0.0
bcc	string[]	email addresses for BCC field	1.0.0
subject	string	subject of the email	1.0.0
body	string	email body	1.0.0
isHtml	boolean	indicates if the body is HTML or plain text (primarily iOS)	1.0.1
attachments	Attachment[]	attachments that are added to the mail file paths or base64 data streams	1.2.0

Attachment

Prop	Type	Description	Since
path	string	The path of the attachment. See the docs for explained informations.	1.2.0
type	'absolute' | 'resource' | 'asset' | 'base64'	The type of the attachment. See the docs for explained informations.	1.2.0
name	string	The name of the attachment. See the docs for explained informations. Required for base64 attachements.	1.2.0

Changelog

The full Changelog is available here

Troubleshooting

TransactionTooLargeException

When sharing data between two applications, the Android OS might throw this exception for several reasons, for example if the file is too large. Read more here about how to work around this problem.

Changelog

6.0.0 (2024-04-18)

⚠ BREAKING CHANGES

• Starting with version 6.X, Capacitor 6 is required

Features

• add capacitor 6 support (#34) (42555b5)