Skip to content

Latest commit

 

History

History
330 lines (229 loc) · 8.68 KB

README.md

File metadata and controls

330 lines (229 loc) · 8.68 KB
Raw

React Native Email Link

GitHub release NPM GitHub license

An easy way to open an email app of the user's choice, based on the mail apps they have installed on their device. Very helpful for magic link logins.

Currently supported apps:

  • Apple Mail
  • Gmail
  • Inbox
  • Spark
  • Airmail
  • Outlook
  • Yahoo Mail
  • Superhuman
  • Yandex
  • ProtonMail
  • Fastmail

Installation

1. Install the package

yarn add react-native-email-link

This package works with autolinking on RN>=0.60. If you're using an earlier version of React Native, please install version 1.4.0 of the library, or check out the legacy rnpm branch.

2. Post-install steps

Based on the platforms your app supports, you also need to:

iOS – Update Info.plist

To allow your app to detect if any of the mailbox apps are installed, an extra step is required on iOS. Your app needs to provide the LSApplicationQueriesSchemes key inside ios/{my-project}/Info.plist to specify the URL schemes with which the app can interact.

Just add this in your Info.plist depending on which apps you'd like to support. Omitting these might mean that the library can't detect some of the mail apps installed by the user.

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>mailto</string>
    <string>message</string>
    <string>readdle-spark</string>
    <string>airmail</string>
    <string>ms-outlook</string>
    <string>googlegmail</string>
    <string>inbox-gmail</string>
    <string>ymail</string>
    <string>superhuman</string>
    <string>yandexmail</string>
    <string>fastmail</string>
    <string>protonmail</string>
    <string>szn-email</string>
</array>
Expo – Enable Config Plugin

To allow the library to work with Expo you need to enable the config plugin. This plugin will automatically configure your Expo application with the correct settings for this library to function.

To enable the config plugin, add it to the plugins array inside your app.config.js/app.config.json. For example:

{
  "name": "my app",
  "plugins": ["react-native-email-link"]
}

Want this library to work on Android too? Because the library uses native code on Android you need to follow Expo's guide for custom native code.

Usage

openInbox

import { openInbox } from "react-native-email-link";

openInbox();

Arguments

title

Text for the top of the ActionSheet or Intent.

Type Required Default
string No 'Open mail app'

message

Subtext under the title on the ActionSheet

Type Required Default Platform
string No 'Which app would you like to open?' iOS

cancelLabel

Text for last button of the ActionSheet.

Type Required Default Platform
string No 'Cancel' iOS

removeText

If true, not text will be show above the ActionSheet or Intent. Default value is false.

Type Required Default
boolean No false

defaultEmailLabel

Text for first button of the ActionSheet.

Type Required Default Platform
string No 'Default email reader' iOS

newTask

If true, the email Intent will be started in a new Android task. Else, the Intent will be launched in the current task.

Read more about Android tasks here.

Type Required Default Platform
boolean No true Android

Example

import { openInbox } from "react-native-email-link";

openInbox({
  message: "Whatcha wanna do?",
  cancelLabel: "Go back!",
});

openComposer

import { openComposer } from "react-native-email-link";

openComposer();

Arguments

app

App to open the composer with

Type Required Example
string No An app's id that can be retrieved with getEmailClients
On Android - id holds the package name, e.g. com.mail.app
On iOS - id holds the app slug/name, e.g. gmail

title

Text for the top of the ActionSheet or Intent.

Type Required Default
string No 'Open mail app'

message

Subtext under the title on the ActionSheet.

Type Required Default Platform
string No 'Which app would you like to open?' iOS

cancelLabel

Text for last button of the ActionSheet.

Type Required Default Platform
string No 'Cancel' iOS

removeText

If true, not text will be show above the ActionSheet or Intent. Default value is false.

Type Required Default
boolean No false

defaultEmailLabel

Text for first button of the ActionSheet.

Type Required Default Platform
string No 'Default email reader' iOS

to

Recipient's email address.

Type Required Default
string No null

cc

Email's cc.

Type Required Default
string No null

bcc

Email's bcc.

Type Required Default
string No null

subject

Email's subject.

Type Required Default
string No null

body

Email's body.

Type Required Default
string No null

encodeBody

Apply encodeURIComponent to the email's body.

Type Required Default
boolean No false

Example

import { openComposer } from "react-native-email-link";

openComposer({
  to: "[email protected]",
  subject: "I have a question",
  body: "Hi, can you help me with...",
});

getEmailClients

import { getEmailClients } from "react-native-email-link";

const clients = await getEmailClients();

console.log(clients)[
  {
    iOSAppName: "gmail", // iOS only
    prefix: "gmail://",
    title: "GMail",
    androidPackagename: "com.google.android.gm", // Android only
    id: "gmail", // depending on the platform, holds either the package name or the app slug value
  }
];

To utilize this feature to display an email client picker within a custom UI and subsequently use the openComposer to launch a specific app, you just need to pass the id (from response) value into the options (options.app) within the openComposer.

Get professional support for this package →
Custom consulting sessions available for implementation support or feature development.