-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Mailgun REST api interface for Haskell.
--   
--   Mailgun is an online service that sends emails. It is a great point of
--   integration for many SaaS services and this Haskell library cleanly
--   interfaces with Mailgun so that you can send emails from your Haskell
--   applications.
@package hailgun
@version 0.4.1.8

module Mail.Hailgun.Attachment

-- | Creates an attachment from a filepath and strict ByteString.
createAttachment :: FilePath -> ByteString -> Attachment

-- | Creates an attachment from a filepath and lazy ByteString.
createAttachmentLazy :: FilePath -> ByteString -> Attachment

-- | Allows you to add an attachment to an already created HailgunMessage.
--   But please note that it will only add your attachment as a standard
--   attachment. Inline attachments must be added at the time that the
--   HailgunMessage was created.
addAttachment :: Attachment -> Endo HailgunMessage


-- | Hailgun is a Haskell wrapper around the <a>Mailgun api's</a> that use
--   type safety to ensure that you are sending a valid request to the
--   Mailgun API's. Mailgun is a service that lets you send emails. It also
--   contains a number of other email handling API's that will be
--   implimented in the future.
module Mail.Hailgun

-- | Send an email using the Mailgun API's. This method is capable of
--   sending a message over the Mailgun service. All it needs is the
--   appropriate context.
sendEmail :: HailgunContext -> HailgunMessage -> IO (Either HailgunErrorResponse HailgunSendResponse)

-- | A method to construct a HailgunMessage. You require a subject,
--   content, From address and people to send the email to and it will give
--   you back a valid Hailgun email message. Or it will error out while
--   trying.
hailgunMessage :: MessageSubject -> MessageContent -> UnverifiedEmailAddress -> MessageRecipients -> [Attachment] -> Either HailgunErrorMessage HailgunMessage

-- | Allows you to add an attachment to an already created HailgunMessage.
--   But please note that it will only add your attachment as a standard
--   attachment. Inline attachments must be added at the time that the
--   HailgunMessage was created.
addAttachment :: Attachment -> Endo HailgunMessage

-- | When comunnicating to the Mailgun service you need to have some common
--   pieces of information to authenticate successfully. This context
--   encapsulates that required information.
data HailgunContext
HailgunContext :: String -> String -> Maybe Proxy -> HailgunContext

-- | The domain of the mailgun account that you wish to send the emails
--   through.
[hailgunDomain] :: HailgunContext -> String

-- | The API key for the mailgun account so that you can successfully make
--   requests. Please note that it should include the <tt>key</tt> prefix.
[hailgunApiKey] :: HailgunContext -> String
[hailgunProxy] :: HailgunContext -> Maybe Proxy

-- | A Hailgun Email message that may be sent. It contains important
--   information such as the address that the email is from, the addresses
--   that it should be going to, the subject of the message and the content
--   of the message. Any email that you wish to send via this api must be
--   converted into this structure first. To create a message then please
--   use the hailgunMessage interface.
data HailgunMessage
type MessageSubject = Text  Represents a message subject.

-- | 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.
--   
--   <pre>
--   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.
--   </pre>
--   
--   (<a>Source</a>)
--   
--   This API mirrors that advice so that you can always get it right.
data MessageContent

-- | The Text only version of the message content.
TextOnly :: ByteString -> MessageContent

-- | The text content that you wish to send (please note that many clients
--   will take the HTML version first if it is present but that the text
--   version is a great fallback).
[textContent] :: MessageContent -> ByteString

-- | A message that contains both a Text version of the email content and a
--   HTML version of the email content.
TextAndHTML :: ByteString -> ByteString -> MessageContent

-- | The text content that you wish to send (please note that many clients
--   will take the HTML version first if it is present but that the text
--   version is a great fallback).
[textContent] :: MessageContent -> ByteString

-- | The HTML content that you wish to send.
[htmlContent] :: MessageContent -> ByteString

-- | A collection of unverified email recipients separated into the To, CC
--   and BCC groupings that email supports.
data MessageRecipients
MessageRecipients :: [UnverifiedEmailAddress] -> [UnverifiedEmailAddress] -> [UnverifiedEmailAddress] -> MessageRecipients

-- | The people to email directly.
[recipientsTo] :: MessageRecipients -> [UnverifiedEmailAddress]

-- | The people to "Carbon Copy" into the email. Honestly, why is that term
--   not deprecated yet?
[recipientsCC] :: MessageRecipients -> [UnverifiedEmailAddress]

-- | The people to "Blind Carbon Copy" into the email. There really needs
--   to be a better name for this too.
[recipientsBCC] :: MessageRecipients -> [UnverifiedEmailAddress]

-- | No recipients for your email. Useful singleton instance to avoid
--   boilerplate in your code. For example:
--   
--   <pre>
--   toBob = emptyMessageRecipients { recipientsTo = ["bob@bob.test"] }
--   </pre>
emptyMessageRecipients :: MessageRecipients
type UnverifiedEmailAddress = ByteString  Represents an email address that is not yet verified.

-- | The response to an email being accepted by the Mailgun API.
data HailgunSendResponse
HailgunSendResponse :: String -> String -> HailgunSendResponse

-- | The freeform message from the mailgun API.
[hsrMessage] :: HailgunSendResponse -> String

-- | The ID of the message that has been accepted by the Mailgun api.
[hsrId] :: HailgunSendResponse -> String

-- | A generic error message that is returned by the Hailgun library.
type HailgunErrorMessage = String

-- | An error that comes from Mailgun or the Hailgun API.
data HailgunErrorResponse
HailgunErrorResponse :: String -> HailgunErrorResponse

-- | A generic message describing the error.
[herMessage] :: HailgunErrorResponse -> String

-- | Make a request to Mailgun for the domains against your account. This
--   is a paginated request so you must specify the pages of results that
--   you wish to get back.
getDomains :: HailgunContext -> Page -> IO (Either HailgunErrorResponse HailgunDomainResponse)

-- | Represents a single page of results. You specify a page of results
--   when you wish to to make a request to a paginated resource.
data Page
Page :: Integer -> Integer -> Page
[pageStart] :: Page -> Integer
[pageLength] :: Page -> Integer
data HailgunDomain
HailgunDomain :: Text -> String -> String -> HailgunTime -> Bool -> String -> HailgunDomain
[domainName] :: HailgunDomain -> Text
[domainSmtpLogin] :: HailgunDomain -> String
[domainSmtpPassword] :: HailgunDomain -> String
[domainCreatedAt] :: HailgunDomain -> HailgunTime
[domainWildcard] :: HailgunDomain -> Bool
[domainSpamAction] :: HailgunDomain -> String
data HailgunDomainResponse
HailgunDomainResponse :: Integer -> [HailgunDomain] -> HailgunDomainResponse
[hdrTotalCount] :: HailgunDomainResponse -> Integer
[hdrItems] :: HailgunDomainResponse -> [HailgunDomain]

-- | A wrapper for UTCTime so that we can always pass correctly formatted
--   times to Mailgun.
newtype HailgunTime
HailgunTime :: UTCTime -> HailgunTime

-- | A convinience method to create a proxy for the HailgunContext.
toProxy :: String -> Int -> Proxy

-- | An Attachment that may be sent. It contains the file path of the
--   attachment and the data that you wish to send in the attachment body.
--   It is important to note that this data type makes no distinction
--   between standard attachments and HTML inline attachments. See
--   sendEmail for more details on how to make your attachments behave like
--   inline attachments.
data Attachment
Attachment :: FilePath -> AttachmentBody -> Attachment
[attachmentFilePath] :: Attachment -> FilePath
[attachmentBody] :: Attachment -> AttachmentBody

-- | An Attachment body is the raw data that you want to send with your
--   attachment.
data AttachmentBody

-- | A strict ByteString representation of your data.
AttachmentBS :: ByteString -> AttachmentBody

-- | A lazy ByteString representation of your data.
AttachmentLBS :: ByteString -> AttachmentBody
