| Copyright | Dennis Gosnell 2016 |
|---|---|
| License | BSD3 |
| Maintainer | Dennis Gosnell (cdep.illabout@gmail.com) |
| Stability | experimental |
| Portability | unknown |
| Safe Haskell | None |
| Language | Haskell2010 |
Mail.Hailgun.Simple
Description
This module provides a simple, easy-to-use wrapper around the hailgun package. hailgun is a package providing a way to send email using Mailgun.
Here is a short example of how to use this package:
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-}
module FooBar where
import Control.Monad.Reader (ReaderT)
import Data.Text (Text)
import Data.Text.Encoding (encodeUtf8)
import Text.Email.Validate (EmailAddress)
import Text.Shakespeare.Text (sbt)
import Mail.Hailgun.Simple
(MessageContent(TextOnly), Email(..), EmailError,
HailgunContext, ResponseFromMailgun, sendEmail)
-- This function will send a new user an email.
sendEmailToNewUser
:: Text -- ^ user's name
-> EmailAddress -- ^ user's email address
-> ReaderT HailgunContext IO (Either EmailError ResponseFromMailgun)
sendEmailToNewUser name emailaddress = do
let email = Email
{ emailSubject = "Thanks for signing up!"
, emailBody = TextOnly $ encodeUtf8 body
, emailReplyTo = myEmailAddress
, emailRecipientsTo = [emailaddress]
, emailRecipientsCC = []
, emailRecipientsBCC = []
, emailAttachments = []
}
sendEmail email
where
body :: Text
body = [sbt|Hi #{name}!
|
|Thanks for signing up to our service!
|
|From your friends at foobar.com :-)|]
myEmailAddress :: EmailAddress
myEmailAddress = undefined
- sendEmail :: forall r m. (HasHailgunContext r, MonadIO m, MonadReader r m) => Email -> m (Either EmailError ResponseFromMailgun)
- data Email = Email {}
- data MessageContent :: *
- = TextOnly { }
- | TextAndHTML { }
- data ResponseFromMailgun = ResponseFromMailgun {
- mailgunMessage :: Text
- mailgunId :: Text
- data HailgunContext :: * = HailgunContext {}
- class HasHailgunContext r where
- data EmailError
- emailToHailgunMessage :: Email -> Either EmailError HailgunMessage
- sendHailgunMessage :: forall r m. (HasHailgunContext r, MonadIO m, MonadReader r m) => HailgunMessage -> m (Either EmailError ResponseFromMailgun)
Sending an Email
sendEmail :: forall r m. (HasHailgunContext r, MonadIO m, MonadReader r m) => Email -> m (Either EmailError ResponseFromMailgun) #
Send an Email.
Returns an EmailErrorIncorrectEmailFormat error if the format of the email
was not correct (for instance, if the email senders or receivers were
incorrect, or the attachments are specified incorrectly). If you are
constructing an Email by hand (and not programatically), this error will
indicate a programmer error.
Returns an EmailErrorSendError if there was a problem with actually
sending the Email. This will usually be an error from the Mailgun
servers.
Email
Datatype representing an email to send.
Constructors
Fields | |
data MessageContent :: * #
Any email content that you wish to send should be encoded into these types before it is sent. Currently, according to the API, you should always send a Text Only part in the email and you can optionally add a nicely formatted HTML version of that email to the sent message.
It is best to send multi-part emails using both text and HTML or text only. Sending HTML only email is not well received by ESPs.
(Source)
This API mirrors that advice so that you can always get it right.
Constructors
| TextOnly | The Text only version of the message content. |
Fields
| |
| TextAndHTML | A message that contains both a Text version of the email content and a HTML version of the email content. |
Fields
| |
Instances
Response
data ResponseFromMailgun #
Response returned from Mailgun's servers.
Constructors
| ResponseFromMailgun | |
Fields
| |
Instances
HailgunContext
data HailgunContext :: * #
When comunnicating to the Mailgun service you need to have some common pieces of information to authenticate successfully. This context encapsulates that required information.
Constructors
| HailgunContext | |
Fields
| |
Instances
class HasHailgunContext r where #
This class provides one layer (or multiple layers) of indirection. It
makes it possible to pass sendEmail a generic configuration datatype
that contains a HailgunContext instead of a HailgunContext directly.
For instance, imagine you had a configuration datatype like this:
data Config = Config
{ configDatabasePool :: Pool
, configHailgunContext :: HailgunContext
}
You could create an instance of HasHailgunContext for Config like this:
instanceHasHailgunContextConfig where getHailgunContext :: Config ->HailgunContextgetHailgunContext = configHailgunContext
Now, you can pass Config to sendEmail instead of a HailgunContext
directly.
Minimal complete definition
Methods
getHailgunContext :: r -> HailgunContext #
Instances
Errors
data EmailError #
Datatype to represent possible errors with sending an email.
Constructors
| EmailErrorIncorrectEmailFormat Text | Email was in incorrect format. Since we are creating emails by hand, this error should never occur. |
| EmailErrorSendError Text | Error from Mailgun when trying to send an email. |
Instances
| Show EmailError # | |
| Generic EmailError # | |
| type Rep EmailError # | |
Lower-level calls
emailToHailgunMessage :: Email -> Either EmailError HailgunMessage #
Wrapper around Mail.Hailgun's hailgunMessage.
sendHailgunMessage :: forall r m. (HasHailgunContext r, MonadIO m, MonadReader r m) => HailgunMessage -> m (Either EmailError ResponseFromMailgun) #
Wrapper around Mail.Hailgun's sendEmail. Used by sendEmail.