@@ -1,3 +1,10 @@
1+{-| This package is an attempt to expose the Mandrill JSON API in pure Haskell.
2+ To do that, the library API comes in two flavours:
3+
4+ * An IO-based, low-level 1:1 mapping of the JSON API,
5+ as described on <https://mandrillapp.com/api/docs/ the website>.
6+ * A handy monad transformer which can be plugged in your stack of choice.
7+-}
18
29module Network.API.Mandrill (
310 module M
@@ -6,6 +13,9 @@ module Network.API.Mandrill (
613 , newTextMessage
714 , newHtmlMessage
815 , liftIO
16+
17+ -- * Appendix: Example Usage
18+ -- $exampleusage
919 ) where
1020
1121import Control.Monad.Reader
@@ -21,16 +31,39 @@ import Text.Email.Validate
2131import qualified Data.Text as T
2232import qualified Data.Aeson as JSON
2333
34+{- $exampleusage
35+
36+The API was designed to allow to get you started as quickly as possible:
37+
38+> {-# LANGUAGE OverloadedStrings #-}
39+> import Text.Email.Validate
40+> import Network.API.Mandrill
41+>
42+> main :: IO ()
43+> main = do
44+> case validate "foo@example.com" of
45+> Left err -> print $ "Invalid email!" ++ show err
46+> Right addr -> runMandrill "MYTOKENHERE" $ do
47+> let msg = "<p>My Html</p>"
48+> res <- sendEmail (newTextMessage addr [addr] "Hello" msg)
49+> case res of
50+> MandrillSuccess k -> liftIO (print k)
51+> MandrillFailure f -> liftIO (print f)
52+
53+-}
2454
2555--------------------------------------------------------------------------------
26−emptyMessage :: EmailAddress -> EmailAddress -> MandrillMessage
56+-- | Builds an empty message, given only the email of the sender and
57+-- the emails of the receiver. Please note that the "Subject" will be empty,
58+-- so you need to use either @newTextMessage@ or @newHtmlMessage@ to populate it.
59+emptyMessage :: EmailAddress -> [EmailAddress] -> MandrillMessage
2760emptyMessage f t = MandrillMessage {
2861 _mmsg_html = mempty
2962 , _mmsg_text = Nothing
3063 , _mmsg_subject = T.empty
3164 , _mmsg_from_email = f
3265 , _mmsg_from_name = Nothing
33− , _mmsg_to = [newRecipient t]
66+ , _mmsg_to = map newRecipient t
3467 , _mmsg_headers = JSON.Null
3568 , _mmsg_important = Nothing
3669 , _mmsg_track_opens = Nothing
@@ -59,22 +92,33 @@ emptyMessage f t = MandrillMessage {
5992 }
6093
6194
62−
6395--------------------------------------------------------------------------------
96+-- | Create a new HTML message.
6497newHtmlMessage :: EmailAddress
65− -> EmailAddress
98+ -- ^ Sender email
99+ -> [EmailAddress]
100+ -- ^ Receivers email
66101 -> T.Text
102+ -- ^ Subject
67103 -> Html
104+ -- ^ The HTML body
68105 -> MandrillMessage
69106newHtmlMessage f t subj html = let body = mkMandrillHtml html in
70107 ((mmsg_html .~ body) . (mmsg_subject .~ subj)) $ (emptyMessage f t)
71108
72109
73110--------------------------------------------------------------------------------
111+-- | Create a new textual message. By default Mandrill doesn't require you
112+-- to specify the @mmsg_text@ when sending out the JSON Payload, and this
113+-- function ensure it will be present.
74114newTextMessage :: EmailAddress
75− -> EmailAddress
115+ -- ^ Sender email
116+ -> [EmailAddress]
117+ -- ^ Receivers email
76118 -> T.Text
119+ -- ^ Subject
77120 -> T.Text
121+ -- ^ The body, as normal text.
78122 -> MandrillMessage
79123newTextMessage f t subj txt = let body = unsafeMkMandrillHtml txt in
80124 ((mmsg_html .~ body) .
@@ -83,6 +127,11 @@ newTextMessage f t subj txt = let body = unsafeMkMandrillHtml txt in
83127
84128
85129--------------------------------------------------------------------------------
130+-- | The simplest way to use the API. All you need to provide is a valid
131+-- 'MandrillMessage' and this function will send an email inside a
132+-- 'MandrillT' transformer. You are not forced to use the 'MandrillT' context
133+-- though. Have a look at "Network.API.Mandrill.Messages" for an IO-based,
134+-- low lever function for sending email.
86135sendEmail :: MonadIO m
87136 => MandrillMessage
88137 -> MandrillT m (MandrillResponse [MessagesResponse])