Notebook Sharing

Sharing notebooks with individuals and with the world

Overview

All aspects of Evernote’s notebook sharing capabilities are available to third-party developers via the Evernote API. This functionality can be a little difficult to understand at first, so this document will cover all related concepts in detail. First, some vocabulary:

A Shared Notebook is accessible to users other than the notebook owner: either specific individuals or the world. The SharedNotebook type controls how and with whom a notebook is shared.
A Linked Notebook is a reference in one user's account to a notebook that has been shared by another user. The LinkedNotebook defines this relationship between the shared notebook and the subscriber.

For example: if Bob creates a notebook in his account called “Fishing” and shares it with Susan, a SharedNotebook instance is created on Bob’s account which contains information about Susan (including her email address) and sent to the Evernote API. When Susan accepts the invitation, a LinkedNotebook instance is created in Susan's account which points to Bob’s SharedNotebook instance.

Here’s a simple graphic illustrating these principles:

Sharing a notebook with a single person

To share a notebook with a single person, you need three things (aside from an authenticated instance of NoteStore):

The GUID of the Notebook you’d like to share.
The email address of the person with whom you’d like to share the notebook.
The desired priviledge level (which are collected in the SharedNotebookPrivilegeLevel enumeration).

Here is a short example demonstrating how to create a new notebook and share it:

We begin by creating a new instance of Notebook and giving it a value for name. After notebook is then created on the Evernote service (using NoteStore.createNotebook), we’ll have the GUID of the notebook that we’ll use to share it.

Then, we create an instance of SharedNotebook. This type can be described as establishing the relationship between the notebook and the person with whom it is being shared. By populating the notebookGuid and email attributes of the SharedNotebook instance, we create this relationship. Finally, we assign the desired privilege level using the privilege attribute on the SharedNotebook, which will be a member of the SharedNotebookPrivilegeLevel enumeration (see the docs for a description of each option).

Finally, we send the SharedNotebook to Evernote by calling NoteStore.createSharedNotebook. If you run the sample code above, you’ll see something like this in the sharing preferences for the notebook we created:

A couple of other things about shared notebooks:

To share a notebook with multiple individuals, a separate instance of SharedNotebook must be used for each person. In other words, SharedNotebook represents a relationship between a notebook and a single recipient. Each notebook contains a sharedNotebooks collection containing these instances.
To stop sharing a notebook with a specific individual, you must call NoteStore.expungeSharedNotebooks and include the identifier for the correct SharedNotebook. Note that this function requires special permission from Evernote; if you need access to this functionality, get in touch with us.
Be sure to set the allowPreview boolean on the Notebook object to whichever value is appropriate. If the value is unset, the Evernote API will throw an exception indicating that requireLogin is invalid. Leave requireLogin unset (as it is deprecated).

Sharing a notebook with the world

Making a notebook publicly visible is a bit easier than sharing with specific people. To share a notebook with the world, you need only set a couple of attributes on the Notebook object and call NoteStore.updateNotebook:

The salient portions here deal with the published and publishing attributes on the notebook:

published is a boolean that controls whether the notebook is publicly shared. To share a given notebook, set this value to true.
publishing is an instance of the Publishing type. At minimum, the uri attribute (which controls the ending portion of the sharing URL) must be defined for the notebook to be publicly visible on the web. All other fields are optional and, in the case of ascending, assigned a default value by the Evernote service if not manually set.

To stop sharing a notebook publicly, simply set the published attribute to false and call NoteStore.updateNotebook.