diff --git a/addons/mail/doc/mail_state.rst b/addons/mail/doc/mail_state.rst
new file mode 100644
index 00000000000..bd8052656d2
--- /dev/null
+++ b/addons/mail/doc/mail_state.rst
@@ -0,0 +1,28 @@
+.. _mail_state:
+
+message_state
+=============
+
+``message_state`` is a boolean field that states whether the document
+has unread messages. In previous versions, some documents were going
+back to ``pending`` state when receiving an email through the mail
+gateway. Now the state related to messages differs from the state or
+stage of the document itself.
+
+message_state and need action mechanism
++++++++++++++++++++++++++++++++++++++++
+
+The ``mail`` module introduces a default behavior for the need_action
+mechanism [REF].
+
+::
+
+  def get_needaction_user_ids(self, cr, uid, ids, context=None):
+    """ Returns the user_ids that have to perform an action
+        :return: dict { record_id: [user_ids], }
+    """
+    result = super(ir_needaction_mixin, self).get_needaction_user_ids(cr, uid, ids, context=context)
+    for obj in self.browse(cr, uid, ids, context=context):
+      if obj.message_state == False and obj.user_id:
+        result[obj.id].add(obj.user_id.id)
+    return result