Creating Notes
In this guide, we'll discuss how to create simple text notes as well as notes containing attachments using the Evernote Cloud API.
-
Creating a Simple Text Note
The most basic Evernote note will contain only text. They can get much more complex than that, of course, but we need to crawl before we can walk.
Prerequisites
To proceed with this example, we’ll assume that the following are already in place:
- You have a developer token (or a working OAuth implementation by which you can retrieve a valid authentication token)
- You have an instance of UserStore and NoteStore
Creating notes in Evernote is done using the
NoteStore.createNoteAPI function. This function takes two arguments: a valid auth token (as a string) and an instance ofTypes.Note. TheNoteinstance, in turn, will need to have the following attributes defined at minimum before we can send it to the API:Note.title— the title of the noteNote.content— the body of the note, formatted as ENML (Evernote Markup Language)
Optionally, we can also set the GUID of the notebook where we’d like this note to reside (as
Note.notebookGuid). If we don’t provide this value, the note will be created in the account’s default notebook.Each note’s body must begin with two things: the standard XML version declaration and the link to the ENML DOCTYPE definition for Evernote notes.
The XML version declaration will look like this:
<?xml version="1.0" encoding="UTF-8"?>
The ENML DOCTYPE definition (DTD) for notes will look like this:
<!DOCTYPE en-note SYSTEM "https://xml.evernote.com/pub/enml2.dtd">
If either of these nodes is omitted in the note body, the Evernote API will reject the note as malformed and invalid.
Assuming both of those pieces are in place, now we just need to add the body of the note, which must be wrapped in
<en-note>tags. Here is the body of a simple (yet complete) Evernote note:<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE en-note SYSTEM "https://xml.evernote.com/pub/enml2.dtd"><en-note>Hello, world!</en-note>
If we take the above XML and a title, we have the necessary parts to create a very simple text note.
Below you’ll find sample code that performs the entire note creation process.
main.py from evernote.edam.type import ttypes def makeNote(authToken, noteStore, noteTitle, noteBody, parentNotebook=None): nBody = '<?xml version="1.0" encoding="UTF-8"?>' nBody += '<!DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd">' nBody += '<en-note>%s</en-note>' % noteBody ## Create note object ourNote = ttypes.Note() ourNote.title = noteTitle ourNote.content = nBody ## parentNotebook is optional; if omitted, default notebook is used if parentNotebook and hasattr(parentNotebook, 'guid'): ourNote.notebookGuid = parentNotebook.guid ## Attempt to create note in Evernote account try: note = noteStore.createNote(authToken, ourNote) except Errors.EDAMUserException, edue: ## Something was wrong with the note data ## See EDAMErrorCode enumeration for error code explanation ## http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode print "EDAMUserException:", edue return None except Errors.EDAMNotFoundException, ednfe: ## Parent Notebook GUID doesn't correspond to an actual notebook print "EDAMNotFoundException: Invalid parent notebook GUID" return None ## Return created note object return notegistfile1.m - (void) makeNoteWithTitle:(NSString*)noteTile withBody:(NSString*) noteBody withParentNotebook:(EDAMNotebook*)parentNotebook { NSString *noteContent = [NSString stringWithFormat:@"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">" "<en-note>" "%@" "</en-note>",noteBody]; // Parent notebook is optional; if omitted, default notebook is used NSString* parentNotebookGUID; if(parentNotebook) { parentNotebookGUID = parentNotebook.guid; } // Create note object EDAMNote *ourNote = [[EDAMNote alloc] initWithGuid:nil title:noteTile content:noteContent contentHash:nil contentLength:noteContent.length created:0 updated:0 deleted:0 active:YES updateSequenceNum:0 notebookGuid:parentNotebookGUID tagGuids:nil resources:nil attributes:nil tagNames:nil]; // Attempt to create note in Evernote account [[EvernoteNoteStore noteStore] createNote:ourNote success:^(EDAMNote *note) { // Log the created note object NSLog(@"Note created : %@",note); } failure:^(NSError *error) { // Something was wrong with the note data // See EDAMErrorCode enumeration for error code explanation // http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode NSLog(@"Error : %@",error); }]; }example.rb def make_note(note_store, note_title, note_body, parent_notebook=nil) n_body = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" n_body += "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">" n_body += "<en-note>#{note_body}</en-note>" ## Create note object our_note = Evernote::EDAM::Type::Note.new our_note.title = note_title our_note.content = n_body ## parent_notebook is optional; if omitted, default notebook is used if parent_notebook && parent_notebook.guid our_note.notebookGuid = parent_notebook.guid end ## Attempt to create note in Evernote account begin note = note_store.createNote(our_note) rescue Evernote::EDAM::Error::EDAMUserException => edue ## Something was wrong with the note data ## See EDAMErrorCode enumeration for error code explanation ## http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode puts "EDAMUserException: #{edue}" rescue Evernote::EDAM::Error::EDAMNotFoundException => ednfe ## Parent Notebook GUID doesn't correspond to an actual notebook puts "EDAMNotFoundException: Invalid parent notebook GUID" end ## Return created note object note endexample.php <?php function makeNote($noteStore, $noteTitle, $noteBody, $parentNotebook = null) { $nBody = '<?xml version="1.0" encoding="UTF-8"?>'; $nBody .= '<!DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd">'; $nBody .= '<en-note>' . $noteBody . '</en-note>'; // Create note object $ourNote = new Note(); $ourNote->title = $noteTitle; $ourNote->content = $nBody; // parentNotebook is optional; if omitted, default notebook is used if (isset($parentNotebook) && isset($parentNotebook->guid)) { $ourNote->notebookGuid = $parentNotebook->guid; } // Attempt to create note in Evernote account try { $note = $noteStore->createNote($ourNote); } catch (EDAMUserException $edue) { // Something was wrong with the note data // See EDAMErrorCode enumeration for error code explanation // http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode print "EDAMUserException: " . $edue; } catch (EDAMNotFoundException $ednfe) { // Parent Notebook GUID doesn't correspond to an actual notebook print "EDAMNotFoundException: Invalid parent notebook GUID"; } // Return created note object return $note; } ?>example.java public Note makeNote(NoteStoreClient noteStore, String noteTitle, String noteBody, Notebook parentNotebook) { String nBody = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"; nBody += "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">"; nBody += "<en-note>" + noteBody + "</en-note>"; // Create note object Note ourNote = new Note(); ourNote.setTitle(noteTitle); ourNote.setContent(nBody); // parentNotebook is optional; if omitted, default notebook is used if (parentNotebook != null && parentNotebook.isSetGuid()) { ourNote.setNotebookGuid(parentNotebook.getGuid()); } // Attempt to create note in Evernote account Note note = null; try { note = noteStore.createNote(ourNote); } catch (EDAMUserException edue) { // Something was wrong with the note data // See EDAMErrorCode enumeration for error code explanation // http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode System.out.println("EDAMUserException: " + edue); } catch (EDAMNotFoundException ednfe) { // Parent Notebook GUID doesn't correspond to an actual notebook System.out.println("EDAMNotFoundException: Invalid parent notebook GUID"); } catch (Exception e) { // Other unexpected exceptions e.printStackTrace(); } // Return created note object return note; }example.js var Evernote = require('evernote'); function makeNote(noteStore, noteTitle, noteBody, parentNotebook) { var nBody = '<?xml version="1.0" encoding="UTF-8"?>'; nBody += '<!DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd">'; nBody += "<en-note>" + noteBody + "</en-note>"; // Create note object var ourNote = new Evernote.Types.Note(); ourNote.title = noteTitle; ourNote.content = nBody; // parentNotebook is optional; if omitted, default notebook is used if (parentNotebook && parentNotebook.guid) { ourNote.notebookGuid = parentNotebook.guid; } // Attempt to create note in Evernote account (returns a Promise) noteStore.createNote(ourNote) .then(function(note) { // Do something with `note` console.log(note); }).catch(function (err) { // Something was wrong with the note data // See EDAMErrorCode enumeration for error code explanation // http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode console.log(err); }); } -
Creating Notes with Attachments
In addition to text, notes can also contain attachments (called “Resources” in the Evernote API). These files can be of any file type, but certain files will be represented differently.
This section will describe how to add various attachments—audio, images, other files—to a note before it is created. First, let’s talk about the
Resourcedata type (defined here).Types.ResourceWhen we add a new
Resourceto a note, many of the members of this object will be set by the Evernote Cloud API when the resource is created: the Resource’s GUID, the GUID of the Note object containing the Resource, any recognition data as well as the Resource’s Update Sequence Number (USN).To take an ordinary file and make it into a
Resourceobject, we need to perform the following steps:- Determine the MIME type of the file to be attached.
- Read the contents of the file and use it to create an instance of
Types.Data(which will then be assigned to theResourceobject’sdatamember). - Generate an MD5 hash of the contents of the file.
This is the minimum amount of information necessary to attach a file to a Note, but we should add one last thing in the interest of completeness: the
ResourceAttributesmember. (Defined here),ResourceAttributeslets us define things like the filename, source URL and other data about the Resource.Here’s a simple function for turning a collection of files into
Resourceinstances suitable for adding to an Evernote note:main.py from evernote.edam.type import ttypes def makeNote(authToken, noteStore, noteTitle, noteBody, parentNotebook=None): nBody = '<?xml version="1.0" encoding="UTF-8"?>' nBody += '<!DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd">' nBody += '<en-note>%s</en-note>' % noteBody ## Create note object ourNote = ttypes.Note() ourNote.title = noteTitle ourNote.content = nBody ## parentNotebook is optional; if omitted, default notebook is used if parentNotebook and hasattr(parentNotebook, 'guid'): ourNote.notebookGuid = parentNotebook.guid ## Attempt to create note in Evernote account try: note = noteStore.createNote(authToken, ourNote) except Errors.EDAMUserException, edue: ## Something was wrong with the note data ## See EDAMErrorCode enumeration for error code explanation ## http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode print "EDAMUserException:", edue return None except Errors.EDAMNotFoundException, ednfe: ## Parent Notebook GUID doesn't correspond to an actual notebook print "EDAMNotFoundException: Invalid parent notebook GUID" return None ## Return created note object return notegistfile1.m - (void) makeNoteWithTitle:(NSString*)noteTile withBody:(NSString*) noteBody withParentNotebook:(EDAMNotebook*)parentNotebook { NSString *noteContent = [NSString stringWithFormat:@"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">" "<en-note>" "%@" "</en-note>",noteBody]; // Parent notebook is optional; if omitted, default notebook is used NSString* parentNotebookGUID; if(parentNotebook) { parentNotebookGUID = parentNotebook.guid; } // Create note object EDAMNote *ourNote = [[EDAMNote alloc] initWithGuid:nil title:noteTile content:noteContent contentHash:nil contentLength:noteContent.length created:0 updated:0 deleted:0 active:YES updateSequenceNum:0 notebookGuid:parentNotebookGUID tagGuids:nil resources:nil attributes:nil tagNames:nil]; // Attempt to create note in Evernote account [[EvernoteNoteStore noteStore] createNote:ourNote success:^(EDAMNote *note) { // Log the created note object NSLog(@"Note created : %@",note); } failure:^(NSError *error) { // Something was wrong with the note data // See EDAMErrorCode enumeration for error code explanation // http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode NSLog(@"Error : %@",error); }]; }Creating a
Resourcedoesn’t do us any good until we add it to a note, right? Embedding a Resource in a note requires the use of the<en-media>element, which is part of ENML. AResourceembedded in an ENML document might look something like this:<en-media type="image/jpg" hash="md5-of-file" />Image and PDF Resources
The following MIME types can be displayed inline within the body of a note:
- image/gif
- image/jpeg
- image/png
- application/pdf
When we include one of the above MIME types as a
Resourcein our note, we can (optionally) include width and height attributes in the<en-media>element:<en-media type="image/jpg" hash="md5-of-file" width="250" height="200" />Otherwise, the implementation is the same as described above.
Audio Resources
The MIME types supported for audio Resources are:
- audio/wav
- audio/mpeg
- audio/amr
When one of these file types is found in the
typeattribute of an<en-media>element, some Evernote clients will display an embedded audio player and allow playback of the file without leaving the app. The ENML syntax for audio Resources is the same as for all others; no special attributes or tags are required.All Other Resources
Resources that aren’t images or audio files whose formats appear in the previous two sections will be displayed using what’s called “attachment view” (as opposed to “inline view”). This means that the attachment will appear as a small file icon in the body of the note. When the user clicks/taps the file icon, the file will be opened using whichever application the operating system thinks is the correct option for that file. In other words, Evernote itself won’t try to open the file. -
Sample Code
Here’s the same
makeNotefunction we defined earlier, augmented to allow the attachment of Resources:main.py def makeNote(authToken, noteStore, noteTitle, noteBody, resources=[], parentNotebook=None): """ Create a Note instance with title and body Send Note object to user's account """ ourNote = Types.Note() ourNote.title = noteTitle ## Build body of note nBody = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" nBody += "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">" nBody += "<en-note>%s" % noteBody if resources: ### Add Resource objects to note body nBody += "<br />" * 2 ourNote.resources = resources for resource in resources: hexhash = binascii.hexlify(resource.data.bodyHash) nBody += "Attachment with hash %s: <br /><en-media type=\"%s\" hash=\"%s\" /><br />" % \ (hexhash, resource.mime, hexhash) nBody += "</en-note>" ourNote.content = nBody ## parentNotebook is optional; if omitted, default notebook is used if parentNotebook and hasattr(parentNotebook, 'guid'): ourNote.notebookGuid = parentNotebook.guid ## Attempt to create note in Evernote account try: note = noteStore.createNote(authToken, ourNote) except Errors.EDAMUserException, edue: ## Something was wrong with the note data ## See EDAMErrorCode enumeration for error code explanation ## http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode print "EDAMUserException:", edue return None except Errors.EDAMNotFoundException, ednfe: ## Parent Notebook GUID doesn't correspond to an actual notebook print "EDAMNotFoundException: Invalid parent notebook GUID" return None ## Return created note object return notegistfile1.m - (void)makeNoteWithTitle:(NSString*)noteTile withBody:(NSString*) noteBody withResources:(NSMutableArray*)resources withParentBotebook:(EDAMNotebook*)parentNotebook { NSString *noteContent = [NSString stringWithFormat:@"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">" "<en-note>" "%@",noteBody]; // Add resource objects to note body if(resources.count > 0) { noteContent = [noteContent stringByAppendingString: @"<br />"]; } // Include ENMLUtility.h . for (EDAMResource* resource in resources) { noteContent = [noteContent stringByAppendingFormat:@"Attachment : <br /> %@", [ENMLUtility mediaTagWithDataHash:resource.data.bodyHash mime:resource.mime]]; } noteContent = [noteContent stringByAppendingString:@"</en-note"]; // Parent notebook is optional; if omitted, default notebook is used NSString* parentNotebookGUID; if(parentNotebook) { parentNotebookGUID = parentNotebook.guid; } // Create note object EDAMNote *ourNote = [[EDAMNote alloc] initWithGuid:nil title:noteTile content:noteContent contentHash:nil contentLength:noteContent.length created:0 updated:0 deleted:0 active:YES updateSequenceNum:0 notebookGuid:parentNotebookGUID tagGuids:nil resources:resources attributes:nil tagNames:nil]; // Attempt to create note in Evernote account [[EvernoteNoteStore noteStore] createNote:ourNote success:^(EDAMNote *note) { // Log the created note object NSLog(@"Note created : %@",note); } failure:^(NSError *error) { // Something was wrong with the note data // See EDAMErrorCode enumeration for error code explanation // http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode NSLog(@"Error : %@",error); }]; }example.rb def make_note(note_store, note_title, note_body, resources=[], parent_notebook=nil) #Create a Note instance with title and body # Send Note object to user's account our_note = Evernote::EDAM::Type::Note.new our_note.title = note_title ## Build body of note n_body = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" n_body += "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">" n_body += "<en-note>#{note_body}" unless resources.empty? ### Add Resource objects to note body n_body += "<br /><br />" our_note.resources = resources resources.each do |resource| hash_func = Digest::MD5.new hexhash = hash_func.hexdigest(resource.data.body) n_body += "Attachment with hash #{hexhash}: <br /><en-media type=\"#{resource.mime}\" hash=\"#{hexhash}\" /><br />" end end n_body += "</en-note>" our_note.content = n_body ## Attempt to create note in Evernote account begin note = note_store.createNote(our_note) rescue Evernote::EDAM::Error::EDAMUserException => edue ## Something was wrong with the note data ## See EDAMErrorCode enumeration for error code explanation ## http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode puts "EDAMUserException: #{edue}" rescue Evernote::EDAM::Error::EDAMNotFoundException => ednfe ## Parent Notebook GUID doesn't correspond to an actual notebook puts "EDAMNotFoundException: Invalid parent notebook GUID" end ## Return created note object note endexample.php <?php function makeNote($noteStore, $noteTitle, $noteBody, $resources = array(), $parentNotebook = null) { // Create a Note instance with title and body // Send Note object to user's account $ourNote = new Note(); $ourNote->title = $noteTitle; ## Build body of note $nBody = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"; $nBody .= "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">"; $nBody .= "<en-note>" . $noteBody; if (isset($resources) && !empty($resources)) { // Add Resource objects to note body $nBody .= "<br /><br />"; $ourNote->resources = $resources; foreach ($resources as $resource) { $hexhash = md5($resource->data->body, 0); $nBody .= "Attachment with hash " . $hexhash . ": <br /><en-media type=\"" . $resource->mime . "\" hash=\"" . $hexhash . "\" /><br />"; } } $nBody .= "</en-note>"; $ourNote->content = $nBody; // parentNotebook is optional; if omitted, default notebook is used if (isset($parentNotebook) && isset($parentNotebook->guid)) { $ourNote->notebookGuid = $parentNotebook->guid; } // Attempt to create note in Evernote account $note = null; try { $note = $noteStore->createNote($ourNote); } catch (EDAMUserException $edue) { // Something was wrong with the note data // See EDAMErrorCode enumeration for error code explanation // http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode print "EDAMUserException: " . $edue; } catch (EDAMNotFoundException $ednfe) { // Parent Notebook GUID doesn't correspond to an actual notebook print "EDAMNotFoundException: Invalid parent notebook GUID"; } // Return created note object return $note; } ?>example.java public Note makeNote(NoteStoreClient noteStore, String noteTitle, String noteBody, List<Resource> resources, Notebook parentNotebook) { // Create a Note instance with title and body // Send Note object to user's account Note ourNote = new Note(); ourNote.setTitle(noteTitle); // Build body of note String nBody = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"; nBody += "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">"; nBody += "<en-note>#{note_body}"; if (resources != null && resources.size() > 0) { // Add Resource objects to note body nBody += "<br /><br />"; ourNote.setResources(resources); for (Resource resource : resources) { StringBuilder sb = new StringBuilder(); for (byte hashByte : resource.getData().getBodyHash()) { int intVal = 0xff & hashByte; if (intVal < 0x10) { sb.append('0'); } sb.append(Integer.toHexString(intVal)); } String hexhash = sb.toString(); nBody += "Attachment with hash " + hexhash + ": <br /><en-media type=\"" + resource.getMime() + "\" hash=\"" + hexhash + "\" /><br />"; } } nBody += "</en-note>"; ourNote.setContent(nBody); // parentNotebook is optional; if omitted, default notebook is used if (parentNotebook != null && parentNotebook.isSetGuid()) { ourNote.setNotebookGuid(parentNotebook.getGuid()); } // Attempt to create note in Evernote account Note note = null; try { note = noteStore.createNote(ourNote); } catch (EDAMUserException edue) { // Something was wrong with the note data // See EDAMErrorCode enumeration for error code explanation // http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode System.out.println("EDAMUserException: " + edue); } catch (EDAMNotFoundException ednfe) { // Parent Notebook GUID doesn't correspond to an actual notebook System.out.println("EDAMNotFoundException: Invalid parent notebook GUID"); } // Return created note object return note; }example.js function makeNote(noteStore, noteTitle, noteBody, resources, parentNotebook, callback) { // Create note object var ourNote = new Evernote.Note(); ourNote.title = noteTitle; // Build body of note var nBody = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"; nBody += "<!DOCTYPE en-note SYSTEM \"http://xml.evernote.com/pub/enml2.dtd\">"; nBody += "<en-note>" + noteBody; if (resources && resources.length > 0) { // Add Resource objects to note body nBody += "<br /><br />"; ourNote.resources = resources; for (i in resources) { var md5 = crypto.createHash('md5'); md5.update(resources[i].data.body); var hexhash = md5.digest('hex'); nBody += "Attachment with hash " + hexhash + ": <br /><en-media type=\"" + resources[i].mime + "\" hash=\"" + hexhash + "\" /><br />" } } nBody += "</en-note>"; ourNote.content = nBody; // parentNotebook is optional; if omitted, default notebook is used if (parentNotebook && parentNotebook.guid) { ourNote.notebookGuid = parentNotebook.guid; } // Attempt to create note in Evernote account noteStore.createNote(ourNote, function(note) { if (note.errorCode) { // Something was wrong with the note data // See EDAMErrorCode enumeration for error code explanation // http://dev.evernote.com/documentation/reference/Errors.html#Enum_EDAMErrorCode console.log(note); } else { callback(note); } }); }