Security News
PyPI Introduces Digital Attestations to Strengthen Python Package Security
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Install the Nylas SDK:
npm install nylas
or yarn add nylas
Every resource (i.e., messages, events, contacts) is accessed via an instance of Nylas
. Before making any requests, be sure to call config
and initialize the Nylas
instance with your appId
and appSecret
. Then, call with
and pass it your accessToken
. The accessToken
allows Nylas
to make requests for a given account's resources.
const Nylas = require('nylas');
Nylas.config({
appId: APP_ID,
appSecret: APP_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);
Every resource method accepts an optional callback as the last argument:
nylas.threads.list({}, (err, threads) => {
console.log(threads.length);
});
Additionally, every resource method returns a promise, so you don't have to use callbacks if your code is promise-friendly. Here's an example using promises:
nylas.threads.list({}).then(threads => {
console.log(threads.length);
});
And here's an example using async/await:
const getThreadCount = async nylas => {
const threads = await nylas.threads.list({});
return threads.length;
};
The Nylas REST API uses server-side (three-legged) OAuth, and the Node.js bindings provide convenience methods that simplify the OAuth process. For more information about authenticating users with Nylas, visit the API docs.
urlForAuthentication()
takes in an options
object, which must have a redirectURI
property defined. Other supported, but optional, properties are:
loginHint
- The user's email address, if known.state
- An arbitrary string that will be returned back as a query param in your redirectURI
.scopes
- An array of which scopes you'd like to auth with. Possible items are 'email'
, 'calendar'
, and 'contacts'
. If omitted, defaults to all scopes.const Nylas = require('nylas');
Nylas.config({
appId: APP_ID,
appSecret: APP_SECRET,
});
router.get('/connect', (req, res, next) => {
options = {
redirectURI: 'http://localhost:3000/oauth/callback',
};
res.redirect(Nylas.urlForAuthentication(options));
});
router.get('/oauth/callback', (req, res, next) => {
if (req.query.code) {
Nylas.exchangeCodeForToken(req.query.code).then(token => {
// save the token to the current session, save it to the user model, etc.
});
} else if (req.query.error) {
res.render('error', {
message: req.query.reason,
error: {
status:
'Please try authenticating again or use a different email account.',
stack: '',
},
});
}
});
The Node.js SDK exposes API resources (threads, messages, folders, labels, files, events, contacts, etc.) as attributes of the nylas
object. You can query these resources in several ways. Available filters can be found in the API docs.
const nylas = Nylas.with(ACCESS_TOKEN);
// Find the first thread matching the filter criteria
nylas.threads.first({ from: EMAIL_ADDRESS }).then(thread => {
console.log(thread.subject);
console.log(thread.snippet);
});
// Count threads in inbox
nylas.threads.count({ in: 'inbox' }).then(count => {
console.log(`There are ${count} threads in your inbox.`);
});
// Fetch a single thread
nylas.threads
.find(THREAD_ID)
.then(thread => {
console.log(thread.subject);
})
.catch(err => {
console.log(`Thread not found! Error: ${err.toString()}`);
});
// Fetch a single thread (using optional callback instead of promise)
nylas.threads.find(THREAD_ID, (err, thread) => {
if (err) {
console.log(`Thread not found! Error: ${err.toString()}`);
return;
}
console.log(thread.subject);
});
// Iterate over every matching thread. Automatically paginates the underlying API
// as necessary and calls the provided block as threads are received. Calls the final
// block upon an error, or when processing is finished.
nylas.threads.forEach(
{ unread: false, from: 'chaiskye@gmail.com' },
thread => console.log(thread.subject),
err => console.log('Finished iterating through threads.')
);
// Returns an array of all matching threads, paginating the underlying API as necessary.
// May take a long time and return many, many objects if used with a broad filter.
nylas.threads.list({ in: 'inbox' }).then(threads => {
console.log(threads);
});
The folders and labels API allows you to apply Gmail labels to whole threads or individual messages and, for providers other than Gmail, to move threads and messages between folders.
Note that folders and labels are identical from the standpoint of the SDK. The only difference is that a message can have many labels but only a single folder.
const nylas = Nylas.with(ACCESS_TOKEN);
// List the labels for this account (Gmail)
nylas.labels.list({}).then(labels => {
for (const label of labels) {
console.log(label.displayName);
console.log(label.id);
}
});
// List the labels this account (Exchange or IMAP)
nylas.folders.list({}).then(folders => {
for (const folder of folders) {
console.log(folder.displayName);
console.log(folder.id);
}
});
// Create a folder (Exchange or IMAP)
const fld = nylas.folders.build({ displayName: 'Reminders' });
fld.save();
// Add the 'Spam' label to a thread (Gmail)
let spamLabel = undefined;
nylas.labels.list({}).then(labels => {
for (const label of labels) {
if (label.displayName == 'Spam') {
spamLabel = label;
break;
}
}
nylas.threads.list({}, (err, threads) => {
const thread = threads[0];
thread.labels.push(spamLabel);
thread.save();
console.log(thread);
});
});
const nylas = Nylas.with(ACCESS_TOKEN);
// Get the metadata of a particular file
const f = nylas.files.build({
id: fileId,
});
f.metadata((err, data) => {
console.log(data);
});
On success, the file metadata should look like:
{
"content_type": "application/msword",
"filename": "Reinstatement of Corporation.doc",
"id": "9tm2n206vdj29wrhcxfvmvo4o",
"message_ids": [
"93mtrpk4uo3wsvwcpb5yh57kp"
],
"account_id": "6aakaxzi4j5gn6f7kbb9e0fxs",
"object": "file",
"size": 100864
}
Because of a bug in the library we use to issue HTTP requests, we can't pass a stream to the file upload function, which is why we read the file directly.
const fs = require('fs');
const nylas = Nylas.with(ACCESS_TOKEN);
fs.readFile(filePath, 'utf8', (err, data) => {
f = nylas.files.build({
filename: filePath,
data: data,
contentType: 'text/plain',
});
f.upload((err, file) => {
// Create a draft and attach the file to it.
const draft = nylas.drafts.build({
subject: 'Ice Cream',
to: [{ email: 'helena@nylas.com' }],
body: 'Hey, find the file attached.',
});
draft.files = [file];
draft.send().then(message => {
console.log(`${message.id} was sent`);
});
});
});
const fs = require('fs');
const nylas = Nylas.with(ACCESS_TOKEN);
const f = nylas.files.build({
id: fileId,
});
f.download((err, file) => {
// File contains headers like 'Content-Disposition',
// and then the data is stored in 'body'
fs.writeFile('/tmp/' + file.filename, file.body);
});
You can create, save, and send drafts. To send, first create a draft object with the correct fields (To/CC/BCC, subject, body, etc.), and then call send
. When the draft is sent, the Nylas API will return a Message
object.
If you want to send a reply, set replyMessageId
to the ID of the message to which you're replying. When that field is set, the Nylas API will set email headers to mark your message as a reply.
const nylas = Nylas.with(ACCESS_TOKEN);
const draft = nylas.drafts.build({
subject: 'My New Draft',
to: [{ email: 'ben@nylas.com' }],
replyToMessageId: MESSAGE_ID,
});
// Sending the draft
draft.send().then(message => {
console.log(`${message.id} was sent`);
});
// Saving a draft
draft.save().then(draft => {
console.log(`${draft.id} was saved`);
});
// Retrieving and sending a saved draft
const savedId = '1234';
nylas.drafts
.find(savedId)
.then(draft => draft.send())
.then(message => {
console.log(`Sent ${message.subject}!`);
});
You can run a full-text search on threads and messages using search
and passing a string to query. By default, the Nylas API returns 40 results, but you can pass a limit
and offset
to perform pagination.
const nylas = Nylas.with(ACCESS_TOKEN);
nylas.messages.search('Hey!').then(messages => console.log(messages));
const DELTA_EXCLUDE_TYPES = ['contact', 'calendar', 'event', 'file', 'tag'];
const nylas = Nylas.with(ACCESS_TOKEN);
nylas.deltas.latestCursor((error, cursor) => {
// Save inital cursor.
persistCursor(cursor);
// Start the stream and add event handlers.
const stream = nylas.deltas.startStream(cursor, DELTA_EXCLUDE_TYPES);
stream
.on('delta', delta => {
// Handle the new delta.
console.log('Received delta:', delta);
// Save new cursor so this delta doesn't need to be re-fetched for future streams.
persistCursor(delta.cursor);
})
.on('error', err => {
// Handle errors here, such as by restarting the stream at the last cursor.
console.error('Delta streaming error:', err);
});
// Closing the stream explicitly, if needed
stopButton.addEventListener('click', () => {
stream.close();
});
});
You can send calendar invites to events using the Nylas API. To send invites and updates to the event's participants, set notify_participants
to true
.
const nylas = Nylas.with(ACCESS_TOKEN);
const event = nylas.events.build({
title: 'Out of time',
calendarId: CALENDAR_ID,
when: { start_time: 1437500000, end_time: 1437501600 },
participants: [{ email: 'helena@nylas.com', name: 'Helena Handbasket' }],
});
event.save({ notify_participants: true }).then(event => {
console.log(event);
console.log('Sent an invite to the participants');
});
// RSVP to an invite. Note that you can only RSVP to invites found in the
// "Emailed events" calendar.
nylas.events
.find(EVENT_ID)
.then(event => event.rsvp('maybe', 'I may attend this event'))
.then(event => console.log('RSVP sent!'));
To send raw MIME, you can build a draft and, instead of providing the normal fields, pass the MIME in an object as rawMime
.
To retrieve the raw MIME for an account's message, call getRaw
on the message object, and the MIME will be returned in a promise.
const nylas = Nylas.with(ACCESS_TOKEN);
// Send a message with raw MIME
const draft = nylas.drafts.build({ rawMime }); // rawMIME should be a MIME-format string with headers and multipart message
draft.send().then(message => console.log(message));
// Retrieve raw MIME for a message
nylas.messages
.first()
.then(message => message.getRaw())
.then(rawMessage => console.log(rawMessage));
It's possible to get details about the account you're accessing by using the account
method:
const nylas = Nylas.with(ACCESS_TOKEN);
nylas.account.get().then(account => console.log(account));
You can access the billing status and cancel/reactivate an account for the accounts in your app by using the accounts
method:
// Show all billing statuses for accounts
Nylas.accounts.list().then(accounts => {
console.log(accounts.length);
for (const account of accounts) {
console.log(
account.id,
account.billingState,
account.syncState
);
}
});
// Cancel the first account
Nylas.accounts
.first()
.then(account => account.downgrade())
.then(response => console.log(response));
// Reactivate an account
Nylas.accounts
.first()
.then(account => account.upgrade())
.then(response => console.log(response));
The Nylas Sync Engine is open-source, and you can also use the Node.js SDK with the open-source API. Since the open-source API provides no authentication or security, connecting to it is simple.
It requires us to "auth" to it by passing the account id as an auth token. Here's an example of fetching the messages of the first account after getting the account ID:
const Nylas = require('nylas');
Nylas.config({
appId: 'appId', // Doesn't matter when running locally
appSecret: 'appSecret', // Doesn't matter when running locally
apiServer: 'http://localhost:5555',
});
/* The open source version of the engine requires us to "auth" to it by
passing the account id as an auth token. Get the account id of the
first account.
*/
Nylas.accounts.first().then(account => {
const nylas = Nylas.with(account.id).messages.list(
{ limit: 20 },
(err, messages) => {
for (const message of messages) {
console.log(message.subject);
}
}
);
});
We have a few example Express apps in the example
directory that show examples for authentication and webhooks. You can run them to see how they're implemented:
npm install
or yarn
npm start
or yarn start
Note that you'll need to replace the Nylas app ID and app secret in app.js
or create a config.js
file with your application's credentials.
We'd love your help making the Nylas Node.js SDK better. Come chat in the Nylas community Slack channel or email support@nylas.com.
Please sign the Contributor License Agreement before submitting pull requests. (It's similar to other projects, like NodeJS or Meteor.)
Tests can be run with:
npm test
Our linter can be run with:
npm run lint
To use the package during local development, symlink the directory:
npm link
in the nylas-nodejs
directory
npm link nylas
in the directory with your code that uses the package
4.3.0 / 2019-03-18
FAQs
A NodeJS wrapper for the Nylas REST API for email, contacts, and calendar.
The npm package nylas receives a total of 29,177 weekly downloads. As such, nylas popularity was classified as popular.
We found that nylas demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.