Only show these results:

Composer Component

Use the Nylas Composer to connect to any email data and provide a custom front end for your applications. Composer providers an out the box solution for writing and sending emails.

Without needing to write a single line of code, Composer comes with:

  • To, from, cc, and bcc fields
  • Subject field
  • Header
  • Attachment
  • Sending right out the box
  • Ability to format messages
  • Light and dark themes
  • Customization options
  • Schedule Message to be sent

If you want to change the behavior of Composer, it comes with custom callback functions and custom hooks.

Nylas Composer

Prerequisites

  • Create a new application or use an existing application with at least 1 account added.
  • An application to add the Component to.
  • A domain for the application to run at. For example localhost.

Quickstart

  1. Create a Composer component in your Nylas Dashboard.
  2. Add it to your application.
    <head>
<!-- Import the script from CDN -->
<script src="https://unpkg.com/@nylas/components-composer"></script>
</head>
<body>
<!-- Place the component on the page -->
<nylas-composer id="PASTE_YOUR_COMPONENT_ID"></nylas-composer>
</body>

That’s It! Composer is ready to use!

Quickstart Sandbox

Copy our sandbox if you prefer. The application uses demo data. Create a new Component so you can use your data.

Composer Intallation Options

You can install Composer 2 ways:

npm Package

Composer on npm

  1. Run npm i @nylas/components-composer or yarn add @nylas/components-composer
  2. Then import and render the component.
    // Import the web component
import '@nylas/components-composer`;

// In render method
<nylas-composer></nylas-composer>

Script Tag

Use the CDN script tag, https://unpkg.com/@nylas/components-composer.

    <head>
<!-- Import the script from CDN -->
<script src="https://unpkg.com/@nylas/components-composer"></script>
</head>
<body>
<!-- Place the component on the page -->
<nylas-composer></nylas-composer>
</body>

Install Composer

Use the following instructions to learn step-by-step how to enable and use the Composer component. The example uses the npm method of installation.

Create the Composer Component

  1. Log in to your Nylas dashboard.
  2. Click Components.
  3. Click the Composer.
  4. Name your Component and select the account.
  5. Use an existing access token or generate a new one. To quickly start testing your Component select Enable for a single account.
    1. To learn how to enable components for multiple accounts see Authorizing Components
  6. Enter the domain the component will run on. Without the domains, the component will not run.
  7. Save your new Component.
  8. On the Edit page, you can configure your component behavior and appearance.

Generate an Access Token

Generating a new access token will not replace your existing access token; it will create a second access token with the same scopes as the previous token. You can revoke access tokens at any time.

Nylas Composer

Add the Component To Your Application

  1. On the Edit page, there are instructions for installing the new Component.
  2. If you haven't installed the Composer Component already, open a terminal and run npm i @nylas/components-composer.
  3. Then add your Nylas component. Copy and paste your component code into your application.
    <nylas-composer id="your-component-id"></nylas-composer>

Nylas Composer Copy Code

  1. You should refresh your application if needed. Any configuration options set on the editing page will apply to your component.

Authorizing Components

With components, you can authorize them to work with a single account or multiple accounts.

Enable for a single account

A single account is a way to get started quickly. If you use this method in production, you'll have to authenticate each account from the dashboard one by one.

Enable components single account

Enable for all accounts

To enable all accounts, you'll need to pass in a user's access token as a property of the component. One way to achieve this is to create a login screen, capture the access token and pass it into the component.

Make sure to keep access_tokens hidden and never expose them online.

Enable Components for all accounts

Dashboard Preview

Dashboard previews do not work when enabling for all accounts.

Usage

There are 2 ways to use Composer:

  • You can create a Nylas Account and Composer comes ready to use without any coding needed.
  • You can bring your own data.

Use a Nylas Account

Install the Composer, then add it to your application. That's it! You're ready to start sending emails. You can alter the apperance and behavior for more functionality.

Bring Your Data

After installing Composer you will need to use custom callbacks to send emails. Check out our example using callbacks to send emails.

Send Emails

Once attached to an account, you can send emails from that account. Emails can be sent directly or scheduled to be sent at a later time. Composer uses the Outbox Endpoint to ensure a high rate of deliverability.

Attachments

File attachments are limited to 6 MB.

Customization

Nylas components are flexible and can be customized for your needs. You can customize the display in 2 ways:

From your Nylas dashboard

Use this option if you are using the Component created from the dashboard. Customize the display by going to your application, selecting Components. Then select the Component you want to edit. If you are customizing using the dashboard, you can not edit the CSS or use custom callbacks.

Directly in the application

No matter where you created your Component, you can use this method to edit the display options.

Pass them as component props:

    <nylas-composer 
theme="dark"
show_header="false"
/>

You can also use composer.options.

    <body>
<nylas-composer id="PASTE_YOUR_COMPONENT_ID"></nylas-composer>
<script>
const composer = document.getElementById('PASTE_YOUR_COMPONENT_ID')
composer.options = { theme: 'dark', show_header: false }
</script>
</body>

Custom Properties

Name Type Description Default value
theme string Light or dark theme. Possible values are light, dark or URL to custom css file. light
show_header boolean Show the Composer header. If removed, the minimize, close and new message text are removed. true
show_from boolean Display the from field. true
show_to boolean Display the to field. true
show_cc boolean Display the cc field. true
show_bcc boolean Display the bcc field. true
visible boolean Display composer on page load. If false you need to call composer.open() true
minimized boolean Show the minimize icon. false
show_subject boolean Show the subject line. true
show_close_button boolean Show the close icon. true
show_minimize_button boolean Display the minimize icon. true
show_cc_button boolean Display css field. true
show_bcc_button boolean Display bcc field. true
show_attachment_button boolean Display attachment icon. true
show_editor_toolbar boolean Display toolbar with options such as bold, lists and underline. true

Custom CSS

To customize the CSS, you can change to one of the provided themes or provide your own stylesheet using the theme attribute. Review the dark.css theme to get the CSS variable names.

    import React from "react";
import "./styles.css";
import "@nylas/components-composer";

export default function App() {
return (
<div className="App">
<h1>Nylas Composer</h1>
<nylas-composer
id="your-composer-id"
show_header="false"
css_url= "https://example.com/my-composer-theme.css"
></nylas-composer>
</div>
);
}

Here is the CSS for the dark theme for you to get started.

    .nylas-composer {
--background: rgb(40, 43, 43);
--background-muted: #454949;
--text: #fff;
--text-light: #B0B0C0;
--text-secondary: #FFFFFF;
--font: lato, sans-serif;
--font-size: 14px;
--font-size-small: 12px;

--border: #282828;
--primary-light: #012CB4;
--primary: #0037E5;
--icons: #8E8E98;
--header-background: var(--background);

--success: white;
--success-light: var(--primary);

--danger: #ffffff;
--danger-light: #FF5454;

--info: var(--primary-light);
--info-light: #AEBFF9;
}

Allowed Domains

For your Composer Component to work, you must add a list of allowed domains.
Use glob patterns to enable or disable domains.

Some examples of glob patterns:

How Properties are Handled

Nylas Components follow an order of operations to decide if the dashboard or code takes precedence.

  1. If the property is passed directly to the Component, use that first.
  2. If the property is not passed directly in the Component use the dashboard settings.
  3. If there are no properties set in the Component or the dashboard, use the Component defaults.

Custom Behavior

You can attach custom callbacks to Composer. These custom callbacks let you change the behavior or use the Component completely detached from Nylas.

Composer comes with callback and hooks. Use callback to change the component behavior and hooks to change behavior or get data when certain actions are taken.

In this example, we are using the composer.send callback and composer.afterSendSuccess to control the behavior of sending a message and closing the Composer after a message is sent.

...
// Customize appearance
el.options = {
show_header: true,
show_subject: true,
theme: "dark",
show_editor_toolbar: true
};

// Use custom callbacks, implement send function
el.send = async (data) => {
return new Promise((resolve, reject) => {
setTimeout(() => {
return resolve({ success: true });
}, 250);
});
};

// Use after send hook
el.afterSendSuccess = async (response) => {
el.close(); // Hide the composer after sending
};

Custom Callbacks

You can't pass callbacks as attributes

You must select the element, for example document.getElementById, and then attach the custom properties.

Name Type Description
composer.send(message) function Function that implements sending the email
composer.from function or array Array of contacts to pre-fill the from field or function that returns array of contacts or promise.
composer.to function or array Array of contacts to pre-fill the to field or function that returns array of contacts or promise.
composer.cc function or array Array of contacts to pre-fill the cc field or function that returns array of contacts or promise.
composer.bcc function or array Array of contacts to pre-fill the bcc field or function that returns array of contacts or promise.
composer.options Object Pass props as a composer property (check section custom properties.
composer.uploadFile Function Function that has single argument (file) and returns object in format as described in Nylas file documentation

Custom Hooks

Name Type Description
composer.change(message) function Called every time composer data is changed. First (and only) argument contains the latest version of the message.
composer.beforeSend function Called before sending the message.
composer.afterSendSuccess function Called before after the message is sent.
composer.afterSendError function Called if error happens during sending.
composer.beforeFileUpload function Called before sending the message.
composer.afterFileUploadSuccess function Called before after the message is sent.
composer.afterFileUploadError function Called if error happens during sending.
composer.beforeFileRemove function Called before attachment is removed.
composer.afterFileRemove function Called after attachment is removed.

You can use a custom method to open and close the Composer.

<body>
<nylas-composer id="PASTE_YOUR_COMPONENT_ID"></nylas-composer>
<script>
const composer = document.getElementById('PASTE_YOUR_COMPONENT_ID')

// to show the composer (if attribute "visible" is set to false)
composer.open();

// to close the composer
composer.close();
</script>
</body>

Callbacks and Hooks Sandbox

Grab our sandbox to get started using callbacks and hooks right away.
The application uses demo data. Create a new Component so you can use your data.

Demo Apps

You can fork any of these to get started right away with Composer.

What's Next?