Mail to Tana Documentation

Introduction

One of my biggest sources of information, tasks, and frustration has always been email. As Tana aims to be the everything OS, getting email into Tana is an important steppingstone to getting there. Until this arrives natively, I have created a small service that allows you to do just that, but with a little magic sprinkled on top.

Mail to Tana allows you to create MailHooks. A MailHook creates a unique email address for a single node in Tana, allowing you to email/forward email that node. By default, this node is your Capture Inbox, but it can be any node you want.

You can configure what happens to the email before it lands in your node. By using AI you can extract Todo items, create summaries, you name it! These docs will walk you through getting started. Let’s start with setup, and then move to funcionality.

Setup

Setup takes a bit of effort. Start by importing the Mail to Tana template into your workspace. When you activate your first MailHook, Tana will ask for four things.

⚠️ To change these keys at a later point, go to the account icon (bottom left in Tana), click “Settings” in the menu, and enter “API Keys”. If you already created and saved mailhooks, you need to save each of your Mailhooks again, when you change your keys.

An OpenAI key (Mailhook OpenAI Key)

Create an OpenAI account and create an API on https://platform.openai.com/account/api-keys

A Tana Workspace API Token (Mailhook Tana Token)

MailHook License Key (Mailhook License Key)

MailHook requires a license key and subscription to use. To make this work it requires a server-side service and incoming mail service, both come with recurring costs.

Subscribe here to get your Mail to Tana Licence key. Note that this is a manual process, I will check when new people register, add them, and email tem. If it’s very popular, I will automate it. Please ping me on the Tana Slack (@dreetje), if you want to ensure you get it faster.

MailHook Secret (Mailhook API Key)

This is the API key used to ensure only you can access and update your hooks. You will get this key when you subscribe. (See licence key)

Adding a new MailHook

Click “+ Add new hook” to add a MailHook

Adding new MailHooks is very easy, simply click the “+ Add new hook” button, or add a new Tana node with the #mailhook supertag in the ‘Hooks’ field.

Finally, you can also click “MailHook examples” and select a hook from one of the examples and duplicate it into your ‘Hooks’ field. Click the example, type CMD+K, select “Duplicate node”, and drag the duplicated node to your hooks.

Activating your MailHook

New MailHook are inactive by default. You need to save them to activate their functionality. Click the “Save” button next to your MailHook to update it on the server and activate its email and API address.

Once a hook has been saved, more of its fields will be filled. The server will send back values for the Email and API fields.

In the example above, any email sent to the email address will be summarised into Tana with the topic as its top node.

Testing your HailHook

After activing your hook, copy the generated email address and forward any of your emails there. If all goes well, the result will land in your destination node in a while (default is the Capture Inbox).

When there is an issue, an error message will land in your destination, so you can see what happened

Note that processing usually can take up to a minute. This is impacted by several things: The delay your email client has for sending emails, the forwarder service we use adds some time (Postmark), and the major impact is the GPT model you choose.

Updating your Mailhook

Ensure to save changes after you update any of the fields, else your hook is no updated

Defining where output lands

By default, output lands in your Tana Capture Inbox. You can customize this to any node in your workspace by putting a reference in the ‘Destination’ field.

Note that the Tana API key you supplied needs to be able to access the destination node.

Using AI

Each MailHook comes with a Prompt field. This prompt will be sent to OpenAI replacing {{INPUT}} with your incoming email. This is where you specify what you want the AI to do with your email. The possibilities are endless.

Ideas to get you started

Extract tasks/todos incoming mail
Summarize your incoming mail
Auto-translate incoming mail
Automatically sort/tag incoming mail

View some of the examples (under MailHook examples) for more inspiration.

Leaving the prompt blank will skip the AI pre-processing step and send the raw data to Tana.

💡 You can also host your prompt on an external http location, editing the prompt in Tana isn’t the best experience. I suggest creating a Github GIST, and then copying the raw url in the Prompt URL field.

Advanced AI

By default, the AI is only able to output plain Tana nodes. But, you can make it smarter by supplying your own supertags, fields, and references.

Provide the AI with your Tana structure.

When you provide this information, the AI will atempt to use these to format the output it sends to Tana. The example above, combined with a prompt asking it to extract todo items, will result in Tana nodes tagged with the #todo supertag.

It might event attempt to fill the relevant fields, and reference the nodes you supplied, this usually requires you to shape the prompt in the right way.

The underlying system uses AI to generate JSON for the Tana Input API. Though this works surprisingly well, it is not perfect. The more structure you supply, the higher the chance it might fail. In this case, a failure node will be sent in its stead.

Attachments

Mail to Tana supports attachments. Start by allowing specific attachment file extensions in the “Allowed Attachments” field of your hook.

In your prompt you must instruct your AI to write the word [[ATTACHMENTS]] in a separate node, i.e as the value of a field. Mailt to Tana will place your attachments here.

Find/Replace References

Find/Replace “Google” and “Apple” with their references in the output.

Using the Find/Replace field, you can configure which words or phrases get referenced in the output sent over to your Tana node. This allows for auto-linking and saves a lot of time and effort.

Note that this does not use AI, it matches the full name of the nodes you provide. Using this in combination with AI features, also allows you to do more creative matching.

Using defaults in a new MailHook

Edit the example MailHook called “New Mailhook (Default)” under examples. This node in cloned when you add a new Mailhook.

TIP: Change your default model to gpt-4 here.

Configuration

Finally, you can customize some of the settings the AI uses. Most notable, you might want to switch the model to gpt-4, when you have access to the more advanced AI models.

Customize the model, temperature, and more.

Known Issues / Troubleshooting

If you are not getting output / errors.

Try switching to GPT-4, or better. GPT-3.5-turbo isn’t great at some tasks.

Check your saved MailHook, does every field have a description with helping text? If not it might be using a local field you already had saved in tana. This is especially a problem if the local field is not a plain text node, for now the only option is to rename the local field, change the local field to a plain field, or import the template in a clean workspace.

Check your API keys (especially the Tana workspace API key). After changing it you need to “Save” each of your mailhooks to update them.