diff --git a/akka-docs/java/code/docs/actor/UntypedActorDocTestBase.java b/akka-docs/java/code/docs/actor/UntypedActorDocTestBase.java
index c82ce30661..c2fb455cfb 100644
--- a/akka-docs/java/code/docs/actor/UntypedActorDocTestBase.java
+++ b/akka-docs/java/code/docs/actor/UntypedActorDocTestBase.java
@@ -50,6 +50,10 @@ import java.util.concurrent.TimeUnit;
 import java.util.ArrayList;
 //#import-askPipe
 
+//#import-stash
+import akka.actor.UntypedActorWithStash;
+//#import-stash
+
 import akka.actor.Props;
 import akka.actor.UntypedActor;
 import akka.actor.UntypedActorFactory;
@@ -346,6 +350,31 @@ public class UntypedActorDocTestBase {
 
   //#hot-swap-actor
 
+  //#stash
+  public static class ActorWithProtocol extends UntypedActorWithStash {
+    private Boolean isOpen = false;
+    public void onReceive(Object msg) {
+      if (isOpen) {
+        if (msg.equals("write")) {
+          // do writing...
+        } else if (msg.equals("close")) {
+          unstashAll();
+          isOpen = false;
+        } else {
+          stash();
+        }
+      } else {
+        if (msg.equals("open")) {
+          unstashAll();
+          isOpen = true;
+        } else {
+          stash();
+        }
+      }
+    }
+  }
+  //#stash
+
   //#watch
   public static class WatchActor extends UntypedActor {
     final ActorRef child = this.getContext().actorOf(Props.empty(), "child");
diff --git a/akka-docs/java/untyped-actors.rst b/akka-docs/java/untyped-actors.rst
index 57dbaa5604..a699cb7145 100644
--- a/akka-docs/java/untyped-actors.rst
+++ b/akka-docs/java/untyped-actors.rst
@@ -558,6 +558,48 @@ well. Use the ``getContext().unbecome`` method from within the Actor.
     if (message.equals("revert")) getContext().unbecome();
   }
 
+
+Stash
+=====
+
+The ``UntypedActorWithStash`` class enables an actor to temporarily stash away messages
+that can not or should not be handled using the actor's current
+behavior. Upon changing the actor's message handler, i.e., right
+before invoking ``getContext().become()`` or ``getContext().unbecome()``, all
+stashed messages can be "unstashed", thereby prepending them to the actor's
+mailbox. This way, the stashed messages can be processed in the same
+order as they have been received originally.
+
+.. warning::
+
+  Please note that the stash can only be used together with actors
+  that have a deque-based mailbox. For this, configure the
+  ``mailbox-type`` of the dispatcher to be a deque-based mailbox, such as
+  ``akka.dispatch.UnboundedDequeBasedMailbox`` (see :ref:`dispatchers-java`).
+
+Here is an example of the ``UntypedActorWithStash`` class in action:
+
+.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#stash
+
+Invoking ``stash()`` adds the current message (the message that the
+actor received last) to the actor's stash. It is typically invoked
+when handling the default case in the actor's message handler to stash
+messages that aren't handled by the other cases. It is illegal to
+stash the same message twice; to do so results in an
+``IllegalStateException`` being thrown. The stash may also be bounded
+in which case invoking ``stash()`` may lead to a capacity violation,
+which results in a ``StashOverflowException``. The capacity of the
+stash can be configured using the ``stash-capacity`` setting (an ``Int``) of the
+dispatcher's configuration.
+
+Invoking ``unstashAll()`` enqueues messages from the stash to the
+actor's mailbox until the capacity of the mailbox (if any) has been
+reached (note that messages from the stash are prepended to the
+mailbox). In case a bounded mailbox overflows, a
+``MessageQueueAppendFailedException`` is thrown.
+The stash is guaranteed to be empty after calling ``unstashAll()``.
+
+
 Killing an Actor
 ================
 
diff --git a/akka-docs/scala/actors.rst b/akka-docs/scala/actors.rst
index 47a2318e53..d3a53408e2 100644
--- a/akka-docs/scala/actors.rst
+++ b/akka-docs/scala/actors.rst
@@ -620,6 +620,54 @@ Here's how you use the ``unbecome`` method:
   }
 
 
+Stash
+=====
+
+The `Stash` trait enables an actor to temporarily stash away messages
+that can not or should not be handled using the actor's current
+behavior. Upon changing the actor's message handler, i.e., right
+before invoking ``context.become`` or ``context.unbecome``, all
+stashed messages can be "unstashed", thereby prepending them to the actor's
+mailbox. This way, the stashed messages can be processed in the same
+order as they have been received originally.
+
+.. warning::
+
+  Please note that the ``Stash`` can only be used together with actors
+  that have a deque-based mailbox. For this, configure the
+  ``mailbox-type`` of the dispatcher to be a deque-based mailbox, such as
+  ``akka.dispatch.UnboundedDequeBasedMailbox`` (see :ref:`dispatchers-scala`).
+
+Here is an example of the ``Stash`` in action:
+
+.. includecode:: code/docs/actor/ActorDocSpec.scala#stash
+
+Invoking ``stash()`` adds the current message (the message that the
+actor received last) to the actor's stash. It is typically invoked
+when handling the default case in the actor's message handler to stash
+messages that aren't handled by the other cases. It is illegal to
+stash the same message twice; to do so results in an
+``IllegalStateException`` being thrown. The stash may also be bounded
+in which case invoking ``stash()`` may lead to a capacity violation,
+which results in a ``StashOverflowException``. The capacity of the
+stash can be configured using the ``stash-capacity`` setting (an ``Int``) of the
+dispatcher's configuration.
+
+Invoking ``unstashAll()`` enqueues messages from the stash to the
+actor's mailbox until the capacity of the mailbox (if any) has been
+reached (note that messages from the stash are prepended to the
+mailbox). In case a bounded mailbox overflows, a
+``MessageQueueAppendFailedException`` is thrown.
+The stash is guaranteed to be empty after calling ``unstashAll()``.
+
+.. warning::
+
+  Note that the ``Stash`` trait must be mixed into (a subclass of) the
+  ``Actor`` trait before any trait/class that overrides the ``preRestart``
+  callback. This means it's not possible to write
+  ``Actor with MyActor with Stash`` if ``MyActor`` overrides ``preRestart``.
+
+
 Killing an Actor
 ================
 
diff --git a/akka-docs/scala/code/docs/actor/ActorDocSpec.scala b/akka-docs/scala/code/docs/actor/ActorDocSpec.scala
index ee05e95d42..108aba33b2 100644
--- a/akka-docs/scala/code/docs/actor/ActorDocSpec.scala
+++ b/akka-docs/scala/code/docs/actor/ActorDocSpec.scala
@@ -300,6 +300,26 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     val actor = system.actorOf(Props(new HotSwapActor), name = "hot")
   }
 
+  "using Stash" in {
+    //#stash
+    import akka.actor.Stash
+    class ActorWithProtocol extends Actor with Stash {
+      def receive = {
+        case "open" ⇒
+          unstashAll()
+          context.become {
+            case "write" ⇒ // do writing...
+            case "close" ⇒
+              unstashAll()
+              context.unbecome()
+            case msg ⇒ stash()
+          }
+        case msg ⇒ stash()
+      }
+    }
+    //#stash
+  }
+
   "using watch" in {
     //#watch
     import akka.actor.{ Actor, Props, Terminated }