Improve and document JSON serialization for Mandrill API

* Add some context to exceptions on unserializable
  values (addresses #89).
* Document need to format merge data
  (into something JSON-serializable).
* Add RemovedInDjrill2 DeprecationWarning.
* Deprecate blanket date/datetime serialization.

docs/usage/sending_mail.rst

@@ -198,6 +198,9 @@ Most of the options from the Mandrill
 
         message.global_merge_vars = {'company': "ACME", 'offer': "10% off"}
 
+    Merge data must be strings or other JSON-serializable types.
+    (See :ref:`formatting-merge-data` for details.)
+
 .. attribute:: merge_vars
 
     ``dict``: per-recipient merge variables (most useful with :ref:`mandrill-templates`). The keys
@@ -209,6 +212,9 @@ Most of the options from the Mandrill
             'rr@example.com':    {'offer': "instant tunnel paint"}
         }
 
+    Merge data must be strings or other JSON-serializable types.
+    (See :ref:`formatting-merge-data` for details.)
+
 .. attribute:: tags
 
     ``list`` of ``str``: tags to apply to the message, for filtering reports in the Mandrill
@@ -245,12 +251,18 @@ Most of the options from the Mandrill
 
         message.metadata = {'customer': customer.id, 'order': order.reference_number}
 
+    Mandrill restricts metadata keys to alphanumeric characters and underscore, and
+    metadata values to numbers, strings, boolean values, and None (null).
+
 .. attribute:: recipient_metadata
 
     ``dict``: per-recipient metadata values. Keys are the recipient email addresses,
     and values are dicts of metadata for each recipient (similar to
     :attr:`merge_vars`)
 
+    Mandrill restricts metadata keys to alphanumeric characters and underscore, and
+    metadata values to numbers, strings, boolean values, and None (null).
+
 .. attribute:: async
 
     ``Boolean``: whether Mandrill should use an async mode optimized for bulk sending.

docs/usage/templates.rst

@@ -37,6 +37,45 @@ and will ignore any `body` text set on the `EmailMessage`.
 All of Djrill's other :ref:`Mandrill-specific options <mandrill-send-support>`
 can be used with templates.
 
+
+.. _formatting-merge-data:
+
+Formatting Merge Data
+~~~~~~~~~~~~~~~~~~~~~
+
+If you're using dates, datetimes, Decimals, or anything other than strings and integers,
+you'll need to format them into strings for use as merge data::
+
+    product = Product.objects.get(123)  # A Django model
+    total_cost = Decimal('19.99')
+    ship_date = date(2015, 11, 18)
+
+    # Won't work -- you'll get "not JSON serializable" exceptions:
+    msg.global_merge_vars = {
+        'PRODUCT': product,
+        'TOTAL_COST': total_cost,
+        'SHIP_DATE': ship_date
+    }
+
+    # Do something this instead:
+    msg.global_merge_vars = {
+        'PRODUCT': product.name,  # assuming name is a CharField
+        'TOTAL_COST': "%.2f" % total_cost,
+        'SHIP_DATE': ship_date.strftime('%B %d, %Y')  # US-style "March 15, 2015"
+    }
+
+These are just examples. You'll need to determine the best way to format
+your merge data as strings.
+
+Although floats are allowed in merge vars, you'll generally want to format them
+into strings yourself to avoid surprises with floating-point precision.
+
+Technically, Djrill will accept anything serializable by the Python json package --
+which means advanced template users can include dicts and lists as merge vars
+(for templates designed to handle objects and arrays).
+See the Python :class:`json.JSONEncoder` docs for a list of allowable types.
+
+
 How To Use Default Mandrill Subject and From fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~