diff --git a/Makefile b/Makefile
index 54aa67d..28165b5 100644
--- a/Makefile
+++ b/Makefile
@@ -14,4 +14,7 @@ tools_DEPEND_DIRS = src
 DIRS += test
 test_DEPEND_DIRS = src
 
+DIRS += example
+example_DEPEND_DIRS = src
+
 include $(TOP)/configure/RULES_TOP
diff --git a/documentation/example.rst b/documentation/example.rst
new file mode 100644
index 0000000..91e8d8a
--- /dev/null
+++ b/documentation/example.rst
@@ -0,0 +1,13 @@
+Examples
+========
+
+Mailbox Server
+--------------
+
+Serves a single PV name.
+Any updates written (PUT) to this PV will be stored verbatim
+and sent to any subscribers.
+
+.. literalinclude:: ../example/mailbox.cpp
+    :language: c++
+    :name: mailbox.cpp
diff --git a/documentation/index.rst b/documentation/index.rst
index e9a5b9f..d53eb7b 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -13,6 +13,7 @@ The canonical source can be found at https://github.com/mdavidsaver/pvxs
    client
    server
    util
+   example
 
 
 Indices and tables
diff --git a/example/Makefile b/example/Makefile
new file mode 100644
index 0000000..471eb17
--- /dev/null
+++ b/example/Makefile
@@ -0,0 +1,24 @@
+TOP=..
+
+include $(TOP)/configure/CONFIG
+#----------------------------------------
+#  ADD MACRO DEFINITIONS AFTER THIS LINE
+#=============================
+
+PROD_LIBS += pvxs Com
+
+TESTPROD += mailbox
+mailbox_SRCS += mailbox.cpp
+
+PROD_SYS_LIBS += event_core
+
+PROD_SYS_LIBS_DEFAULT += event_pthreads
+PROD_SYS_LIBS_WIN32 += netapi32 ws2_32
+PROD_SYS_LIBS_vxWorks =
+
+#===========================
+
+include $(TOP)/configure/RULES
+#----------------------------------------
+#  ADD RULES AFTER THIS LINE
+
diff --git a/example/mailbox.cpp b/example/mailbox.cpp
new file mode 100644
index 0000000..7b2315e
--- /dev/null
+++ b/example/mailbox.cpp
@@ -0,0 +1,57 @@
+/**
+ * Copyright - See the COPYRIGHT that is included with this distribution.
+ * pvxs is distributed subject to a Software License Agreement found
+ * in file LICENSE that is included with this distribution.
+ */
+
+#include <iostream>
+
+#include <pvxs/sharedpv.h>
+#include <pvxs/server.h>
+#include <pvxs/nt.h>
+#include <pvxs/log.h>
+
+using namespace pvxs;
+
+int main(int argc, char* argv[])
+{
+    if(argc<=1) {
+        std::cerr<<"Usage: "<<argv[0]<<" <pvname>\n";
+        return 1;
+    }
+
+    // Read $PVXS_LOG from process environment and update
+    // logging configuration.  eg. PVXS_LOG=*=DEBUG makes
+    // a lot of noise.
+    logger_config_env();
+
+    // Must provide a data type for the mailbox
+    Value initial = nt::NTScalar{TypeCode::Float64}.create();
+    // (optional) Provide an initial value
+    initial["value"] = 42.0;
+    initial["alarm.severity"] = 0;
+    initial["alarm.status"] = 0;
+    initial["alarm.message"] = "";
+
+    // Actually creating the mailbox PV.
+    // buildMailbox() includes a default PUT handler which simply
+    // stores whatever a client sends (subject to our data type).
+    server::SharedPV pv(server::SharedPV::buildMailbox());
+    // Associate a data type (and maybe initial value) with this PV
+    pv.open(initial);
+
+    // Build server which will server this PV
+    auto serv = server::Config::from_env()
+            .build()
+            .addPV(argv[1], pv);
+
+    // (optional) Print the configuration this server is using
+    // with any auto-address list expanded.
+    std::cout<<"Effective config\n"<<serv.config();
+
+    // Start server and run forever, or until Ctrl+c is pressed.
+    // Returns on SIGINT or SIGTERM
+    serv.run();
+
+    return 0;
+}
diff --git a/test/Makefile b/test/Makefile
index 3a474cf..1d9414b 100644
--- a/test/Makefile
+++ b/test/Makefile
@@ -70,10 +70,6 @@ TESTPROD += mcat
 mcat_SRCS += mcat.cpp
 # not a unittest
 
-TESTPROD += mailbox
-mailbox_SRCS += mailbox.cpp
-# not a unittest
-
 PROD_SYS_LIBS += event_core
 
 PROD_SYS_LIBS_DEFAULT += event_pthreads
diff --git a/test/mailbox.cpp b/test/mailbox.cpp
deleted file mode 100644
index d6215b5..0000000
--- a/test/mailbox.cpp
+++ /dev/null
@@ -1,56 +0,0 @@
-/**
- * Copyright - See the COPYRIGHT that is included with this distribution.
- * pvxs is distributed subject to a Software License Agreement found
- * in file LICENSE that is included with this distribution.
- */
-
-#include <iostream>
-
-#include <pvxs/sharedpv.h>
-#include <pvxs/server.h>
-#include <pvxs/nt.h>
-#include <pvxs/log.h>
-
-DEFINE_LOGGER(app, "mailbox");
-
-namespace {
-using namespace pvxs;
-using namespace pvxs::server;
-
-void usage(const char* cmd)
-{
-    std::cerr<<"Usage: "<<cmd<<" <pvname>\n";
-}
-
-} // namespace
-
-int main(int argc, char* argv[])
-{
-    if(argc<=1) {
-        usage(argv[0]);
-        return 1;
-    }
-
-    pvxs::logger_level_set(app.name, pvxs::Level::Info);
-    pvxs::logger_config_env();
-
-    auto initial = nt::NTScalar{TypeCode::Float64}.create();
-    initial["value"] = 42.0;
-    initial["alarm.severity"] = 0;
-    initial["alarm.status"] = 0;
-    initial["alarm.message"] = "";
-
-    auto pv(SharedPV::buildMailbox());
-    pv.open(initial);
-
-    auto serv = Config::from_env()
-            .build()
-            .addPV(argv[1], pv);
-
-    std::cout<<"Effective config\n"<<serv.config();
-
-    log_info_printf(app, "Running\n%s", "");
-    serv.run();
-
-    return 0;
-}