Agile Tortoise

Drafts for Developers

← Back to Developers

Drafts for Developers

If you implement, or plan on implementing, Drafts integration in your app, please drop us a line and let us know, we’d be happy to help.

If you develop and app that support URL schemes and works with text and would like to have it considered for a new action in Drafts, please drop us a line and let us know.

Drafts supports for integration with other apps via the x-callback-url protocol. Drafts registers the following URL schema:

  • Drafts (iPhone): drafts://, x-drafts://
  • Drafts for iPad: drafts://, x-drafts-for-ipad://

To target either version of Drafts, use “drafts://”. The x- version are provided if you need to specifically target or test for the installation of the iPad vs. iPhone version.

x-callback-url Actions

/create

  • Action: create
  • Parameters:
    • text [string, required] : URL encoded text to be used for new draft.
    • action [string, optional] : URL encoded name of an action in the Drafts’ action list. If included, the action will be triggered on the new draft after it is created (* see notes below about action security).
    • afterSuccess [string, optional] : Can be a value of “Nothing”, “Archive” or “Delete”. If provided, along with an action parameter, it will override any “after success” settings for the action.
    • allowEmpty [string, optional] : Can by “YES” or “NO”. Default is “YES”. This parameter should only be needed in actions which recursively call Drafts’ own URL schemes. When “NO” and an action parameter is included, Drafts will fail gracefully when trying to perform the action on an empty draft.
    • x-success [url, optional] : When used in conjunction with the ‘action’ parameter, this URL will be opened after the action is successfully completed.
    • x-error [url, optional] : When used in conjunction with the ‘action’ parameter, this URL will be opened if the action generates an error and cannot be completed successfully.
  • Description: Calling this action with the required “text” parameter will launch Drafts, create a new draft with the text passed, and present the draft to the user for editing.
  • Examples
    • create a draft with the text “Hello World”:
      • drafts://x-callback-url/create?text=Hello%20World
    • create a draft with the text “Hello World”, then fire the “Copy to Clipboard” action:
      • drafts://x-callback-url/create?text=Hello%20World&action=Copy%20to%20Clipboard

Firing Actions via URL

Triggering of actions via incoming URL is disabled by default, as it could be a security risk. To enable triggering of actions via URL, open Drafts’ Settings, scroll to the bottom and configure the following:

  • Allow URLs to trigger actions?: Turn on to allow triggering. If off, URLs specifying actions will generate an error.
  • Require “key” parameter / URL key: If you wish to allow action URLs, but maintain control over them, you can enable the “key” parameter. If on, incoming action URLs will check for an additional “key” parameter in the URL, and check if it matches the value in the URL key field – think of it as a password. Drafts generates a default value for URL key, but you may edit this value – the primary purpose of this is to allow you configure multiple copies of Drafts on different devices with the same key so that they can all work with the same workflow URLs.