Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/EinfachHans/capacitor-email-composer
E-Mail Composer Plugin for Capacitor
https://github.com/EinfachHans/capacitor-email-composer
Last synced: 7 days ago
JSON representation
E-Mail Composer Plugin for Capacitor
- Host: GitHub
- URL: https://github.com/EinfachHans/capacitor-email-composer
- Owner: EinfachHans
- License: mit
- Created: 2021-06-10T09:47:58.000Z (over 3 years ago)
- Default Branch: dev
- Last Pushed: 2024-04-18T10:28:43.000Z (7 months ago)
- Last Synced: 2024-10-01T14:10:45.822Z (about 1 month ago)
- Language: Java
- Size: 555 KB
- Stars: 21
- Watchers: 2
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
- awesome-capacitor - Email composer - Open a native E-Mail Composer within your Capacitor App. (Other plugins)
README
# Capacitor E-Mail Composer
[](https://www.npmjs.com/package/capacitor-email-composer)
This Plugin is used to open a native E-Mail Composer within your Capacitor App.
**Table of Content**
- [Install](#install)
- [Attachments](#attachments)
- [Device Storage](#device-storage)
- [Native resources](#native-resources)
- [Assets](#assets)
- [Base64](#base64)
- [API](#api)
- [hasAccount()](#hasaccount)
- [open(...)](#open)
- [Interfaces](#interfaces)
- [Changelog](#changelog)
- [Troubleshooting](#troubleshooting)
- [TransactionTooLargeException](#transactiontoolargeexception)
## Install
```bash
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!
```ts
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.
```ts
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.
```ts
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**.
```ts
import { EmailComposer } from 'capacitor-email-composer'
EmailComposer.open({
attachments: [{
type: 'base64',
path: 'iVBORw0KGgoAAAANSUhEUgAAADwAAAA8CAYAAAA6...',
name: 'icon.png' // this is required
}]
})
```
## API
* [`hasAccount()`](#hasaccount)
* [`open(...)`](#open)
* [Interfaces](#interfaces)
### hasAccount()
```typescript
hasAccount() => Promise
```
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(...)
```typescript
open(options?: OpenOptions | undefined) => Promise
```
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](CHANGELOG.md)
## 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](https://github.com/EinfachHans/capacitor-email-composer/issues/19#issuecomment-1786087158) about how to work around this problem.