Sharing notebooks with individuals and with the world
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
SharedNotebooktype 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
LinkedNotebookdefines 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
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
GUIDof 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
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
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
SharedNotebookmust be used for each person. In other words,
SharedNotebookrepresents a relationship between a notebook and a single recipient. Each notebook contains a
sharedNotebookscollection containing these instances.
- To stop sharing a notebook with a specific individual, you must call
NoteStore.expungeSharedNotebooksand 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
allowPreviewboolean on the
Notebookobject to whichever value is appropriate. If the value is unset, the Evernote API will throw an exception indicating that
requireLoginis invalid. Leave
requireLoginunset (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
The salient portions here deal with the
publishing attributes on the notebook:
publishedis a boolean that controls whether the notebook is publicly shared. To share a given notebook, set this value to true.
publishingis an instance of the
Publishingtype. At minimum, the
uriattribute (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