--- mailhandler.api.php
+++ mailhandler.api.php
@@ -0,0 +1,115 @@
+<?php
+// $Id$
+
+/**
+ * @file
+ * Hooks provided by the Mailhandler module.
+ *
+ * Describe the hooks and functions available to integrate other modules with
+ * Mailhandler. Listhandler module is an example of a real integration.
+ * 
+ * @see http://drupal.org/project/listhandler
+ */
+
+/**
+ * Allow override node/comment elements before submitting the entry.
+ *
+ * Modules may implement this hook if they want to alter or process the node or
+ * comment being saved. This hook is executed while logged in as the author user
+ * so avoid to handle administrative tasks as the user may not have enough
+ * permissions to do.
+ *
+ * A module can completely process the node. To avoid other modules to act on
+ * the new created entry, it must return the node object.
+ * 
+ * @param $node
+ *   A node/comment object completely processed by the parser.
+ * @param $result
+ *   Unknown: Imap stream?
+ * @param $number
+ * function listhandler_mailhandler($node, $result, $msg_number, $header, $mailbox) {
+ *   Unknown
+ * @param $header
+ *   Current email message header
+ * @param $mailbox
+ *   Array containing the mailbox information.
+ *
+ * @return
+ *   return the $node object if the module process the node, preventing other
+ *   module's hook from being called or nothing.
+ */
+function hook_mailhandler($node, $result, $number, $header, $mailbox) {
+
+}
+
+/**
+ * Inform other modules about node/comment being created using Mailhandler.
+ *
+ * Modules may implement this hook if they want to process site information by
+ * the new known node/comment id just created. This hook is executed while
+ * logged in as the author user so avoid to handle administrative tasks as the
+ * user may not have enough permissions to do.
+ *
+ * @param $node
+ *   A complete node/comment object.
+ * @param $type
+ *   String to identify the type of created object
+ *   - 'node'
+ *   - 'comment'
+ * 
+ */
+function hook_mailhandler_post_save(array &$keys) {
+
+}
+
+/**
+ * Define additional authentication methods for Mailhandler.
+ *
+ *
+ * This hook is invoked from sshkey_save() before the SSH key is saved to the
+ * database. 
+ *
+ * @return
+ *   An array of authentication methods. Each method has a key corresponding to
+ *   its method shortname being registered. The method is an associative array
+ *   that may contain the following key-value pairs:
+ *   - 'title': Required. The untranslated title of the method.
+ *   - 'description': The untranslated description of the method.
+ *   - 'callback': The function to call to perform the authentication.
+ *   When the callback is located in a external file that requires to be loaded
+ *   the authentication method can use the following keys that are used to load
+ *   the file using module_load_include().
+ *   - 'module': The module name handling the callback.
+ *   - 'extension': The file extension.
+ *   - 'basename': The file name.
+ *
+ * @see mailhandler_authenticate_default
+ */
+function hook_mailhandler_authenticate_info() {
+
+}
+
+/**
+ * Example of custom authentication method.
+ *
+ * The purpose of the authentication method is to fill authorship attributes in
+ * the node object. This function must be declared as authentication method with
+ * hook_mailhandler_authenticate_info(), as the 'callback' parameter for the
+ * method.
+ *
+ * @param $node
+ *   Object a node object
+ * @param $header
+ *   Object of message header information
+ * @param $origbody
+ *   String message body text
+ * @param $mailbox
+ *   Array of mailbox configuration
+ *
+ * @return
+ *   The node object with authorship attributes filled, usually $node->uid and
+ *   $node->name attributes.
+ */
+function example_authentication_method($node, $header, $origbody, $mailbox) {
+
+}