📮 react-native-email

Send a email using the Linking API

Table of Contents

• 📮 react-native-email
  • Table of Contents
  • Install
  • Usage
    • Line breaks in the body
    • Running on iOS simulator
    • Running on Android SDK 30+
  • API
  • Contributing
    • Development checks
  • License

Install

Install the package locally within you project folder with your package manager:

With npm:

npm install --save-exact react-native-email@2.1.0

With yarn:

yarn add --exact react-native-email@2.1.0

Versions 2.1.1 and 2.1.2 are affected by MAL-2025-190996. The commands above pin 2.1.0 to avoid those releases.

Usage

import React from 'react'
import { StyleSheet, Button, View } from 'react-native'
import email from 'react-native-email'

export default class App extends React.Component {
    render() {
        return (
            <View style={styles.container}>
                <Button title="Send Mail" onPress={this.handleEmail} />
            </View>
        )
    }

    handleEmail = () => {
        const to = ['first@example.com', 'second@example.com'] // string or array of email addresses
        email(to, {
            // Optional additional arguments
            cc: ['copy@example.com', 'another-copy@example.com'], // string or array of email addresses
            bcc: 'hidden@example.com', // string or array of email addresses
            subject: 'Show how to use',
            body: 'Some body right here',
            checkCanOpen: true // Check for a mail app before opening (default: true)
        }).catch(console.error)
    }
}

const styles = StyleSheet.create({
    container: {
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center'
    }
})

This results to:

Line breaks in the body

Pass a plain-text body with \r\n (CRLF) between lines. Use \r\n\r\n for a blank line:

email('recipient@example.com', {
    subject: 'Multiple lines',
    body: 'First line\r\nSecond line\r\n\r\nLast paragraph'
}).catch(console.error)

These JavaScript escape sequences create actual line breaks in the string. The library preserves the supplied line endings and URL-encodes the body; it does not convert \n to \r\n. CRLF produces %0D%0A, the line-break encoding required by RFC 6068.

Pass the original text, not a pre-encoded value such as %0D%0A or encodeURIComponent(body), because the library would encode it again. Literal backslash characters (for example, 'First\\nSecond') and HTML <br> tags are plain text, not line-break instructions.

The installed mail app renders the body. Test with the mail apps and OS versions your app supports; this library cannot correct a mail app's formatting behavior.

Running on iOS simulator

Opening a mailto: URL requires an installed mail app that can handle it. An iOS simulator may not have one, so validate mail composition on a device with a mail app available.

Running on Android SDK 30+

When your app targets Android 11 (API level 30) or higher, package visibility filtering can prevent Linking.canOpenURL from finding an installed mail app. With checkCanOpen enabled (the default), this can cause a Provided URL can not be handled error.

Add the following <queries> element as a direct child of <manifest> in android/app/src/main/AndroidManifest.xml, outside <application>. If your manifest already has <queries>, add the <intent> to it:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <queries>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="mailto" />
        </intent>
    </queries>
    <!-- Keep your existing application and other manifest entries here. -->
</manifest>

React Native's Linking.canOpenURL and Linking.openURL use ACTION_VIEW on Android, so the query must match that action and the mailto scheme. A DIAL query is for phone calls and does not describe this library's email intent. See the React Native Linking documentation, React Native Android implementation, and Android package visibility guidance.

A mail app that handles mailto: must still be installed. Rebuild the Android app after changing its manifest. If the check still fails, confirm that a mail app is available on your emulator or device.

Setting checkCanOpen: false skips the visibility check and attempts Linking.openURL directly. Android does not require package visibility to start another app's activity, but opening can still reject if there is no handler. Handle the returned promise's rejection, as in the usage example.

API

For all configuration options, please see the API docs.

Contributing

Got an idea for a new feature? Found a bug? Contributions are welcome! Please open up an issue or make a pull request.

Development checks

Use Node.js 18 or newer and pnpm 7.33.7 to run the regression suite:

pnpm install --frozen-lockfile --ignore-scripts
pnpm lint
pnpm test

The tests exercise the checked-in source with a mocked React Native Linking API, parse and run the README usage example, and check the Android manifest query. They do not validate Android package visibility or mail composition on a device. For that, build an app targeting API 30 or higher with the manifest query above, then use the default checkCanOpen: true on an emulator or device with a mail app installed. Confirm that the composer opens with the expected recipients, subject, and body; also check rejection handling when no mail app is available.

License

MIT © Tiaan du Plessis