Exploring Evernote's x-callback-url

It came to my attention last month that Evernote enabled many actions via Launch Center Pro, including x-callback-url support. What’s impressive about this implementation is how the Evernote team were meticulous to empower its users with great control over parameters.

Over the years, Evernote became more than a web clipper or a rich-text note editor, it expanded to support reminders, presentations and the list keeps growing. The new Evernote URL scheme is perfect for quick input as it offers different types of note for the user to select on the go, although existing note manipulation is non-existent.

There are two available actions: new-note and new-clipped-note, the former covers most note formats and the latter is dedicated to web clipping. The new-note action uses the type parameter to set the kind of note. Besides the type attribute, the new-note action also supports title, text, reminderdate, latitude and longitude.

Every note format supports the aforementioned parameters but text, which is interpreted according to the kind of note. Here's the list of note formats and how they handle the text parameter:

  • text: A regular note, parses the homonymous parameter as plain text;
  • camera: Opens Evernote on the camera and attach the picture taken to the note. Parses text as plain text;
  • photos: Prompts for photos in the Camera Roll. Selected images are attached to the note. Parses text as plain text;
  • list: Starts a to-do list. Parses text as the first task. No, you can't create multiple tasks from the URL scheme;
  • reminder: Creates a reminder. Ignores the text parameter;
  • audio: Records an audio note and is awesome. Parses text as plain text;
  • clipboard: Creates a regular note from the contents of the clipboard. Ignores the text parameter since it fills its field with the clipboard. Accepts text and images;
  • lastphoto: Attaches the last photo taken to a regular note. Ignores the text parameter since it uses the picture as content;
  • html: Creates a note with web content. The text parameter expects a valid HTML string without external resources.

How every note type works offers as many possibilities as it does limitations. For example, there's no way you can select a photo outside Evernote, as in Launch Center Pro, and include it to a note with text using the clipboard. I'm also suspicious on the reasons behind the lack of support for the text parameter in the lastphoto note type. The list note is a disappointment as it joins multiple lines into a single task, ruining your formatting. I couldn't find a way to generate multiple tasks from an unique action.

On the bright side, the audio type doesn't waste any second and starts recording as Evernote opens. Terrific for taking audio notes on the go. The html type is a fresh alternative to skip Drafts in my bookmarklet to capture web content. A working version of my webclipper bookmarklet going straight to Evernote is as follows:

javascript:(function(){var request=new XMLHttpRequest();request.open("GET","http://heckyesmarkdown.com/go/?read=1&md=0&preview=0&showframe=0&output=url&u="+encodeURIComponent(location.href),true);request.send();request.onreadystatechange=function(){location.href="evernote://x-callback-url/new-note?type=html&title="+encodeURIComponent(window.document.title)+"&text="+request.responseText};})();

However, if I were you I wouldn't dump Drafts out of the loop yet, as we'll see next, they are a perfect match.

I mentioned three parameters supported by all kinds of notes within a new-note action; latitude and longitude set the geolocation for your note and Drafts 4 brought the [[latitude]] and [[longitude]] template tags1.

The reminderdate parameter is tricky, to say the least, it allows you to include a reminder to your note, yet the format it accepts is in seconds since January 1st, 1970. The date may sound random, but it is common in the programming world: it is known as Unix time or just Epoch and is used on every programming language you may want to learn, such as Javascript, PHP or Python, and even those you may prefer to stay away, like Perl. If you use Due, you may be familiar with the Epoch as it is the reason why we set dates using its natural language parser instead of the URL scheme parameters. That's how difficult it is to grab the Epoch for a specific date on your iPhone, but there are workarounds.

The new version of Drafts also introduces Javascript, which has its own ways to manipulate dates, as you may have noticed in the natural language parser I posted previously, which you can adapt to output Epoch time2.

There's a nice function in Javascript called Date.parse(), which receives date strings or Date objects and converts them into milliseconds since Epoch. It is not very flexible, but I created a keyboard extension for Drafts which converts a Date string into a Date object before converting it into Epoch time. Creating a Date object is often more flexible and I strongly recommend if you're struggling to work with dates in Javascript. There are a few resources you can read to learn the available formats.

You can always install my Drafts keyboard extension to convert time strings to Epoch, but if the script doesn't work, there's not much I can do, read the articles I listed above and understand how the date conversion works.

if you're still not convinced on how Drafts is the ideal companion to Evernote, the newest version also introduced a syntax to convert Markdown to HTML on the go, just wrap your text on double percent signs. According to Drafts's documentation, you should also enable the XHTML output to the Markdown conversion by adding the xhtml parameter to the tag.

A working example could be %%xhtml|[[draft]]%% to convert the entire draft to HTML using the html note type3. Here's how the webclipper bookmarklet looks like if you stick with Drafts:

javascript:(function(){var request=new XMLHttpRequest();request.open("GET","http://heckyesmarkdown.com/go/?read=1&preview=0&showframe=0&output=url&u="+encodeURIComponent(location.href),true);request.send();request.onreadystatechange=function(){location.href="drafts4://x-callback-url/runAction?text="+encodeURIComponent(window.document.title + "\n")+request.responseText+"&action=Markdown To Evernote"};})();

It triggers an action named Markdown to Evernote, which you can download here. It uses a short Javascript step to convert Markdown to HTML due to the current bug on the double percent sign tag. The coolest thing about stickying with Drafts is that you can attach your location to the clip.

What x-callback-url parameters?

The current version of Evernote supports x-success, x-error and x-cancel.

Clipping entire pages

Earlier I mentioned another kind of action in Evernote, the new-clipped-note, which supports a single parameter: url. Beware! Don't encode the url you're passing as value or Evernote will throw an error.

This action clips the entire page from the address you submit, works great for clean pages, although I wish it supported more parameters.

I hope this article sets a nice introduction to Evernote's x-callback-url and how you can take the app beyond what their brand-new extension has to offer. Don't think URL schemes are dead. At least not yet.

  1. Drafts also supports variations for the geolocation tags for the latitude and longitude when the note was created or modified. Look at them at the documentation

  2. If you open that script, you'll find out that the calculations based on weekdays are all made using Epoch time. 

  3. The current version of Drafts ( throws an error when you try to convert Markdown to HTML as part of a URL action.