Copyright	(c) 2012 Mark Hibberd
License	BSD3
Maintainer	Mark Hibberd <mark@hibberd.id.au>
Portability	portable
Safe Haskell	None
Language	Haskell98

Network.Api.Postmark

Contents

Settings
- Using the test token
Sending email
Error types
Lower-level API
- Request
- Response

Description

Library for postmarkapp.com HTTP Api.

To get start see some examples in the Network.Api.Postmark.Tutorial module.

Source and more information can be found at https://github.com/apiengine/postmark.

To experiment with a live demo try:

$ git clone https://github.com/apiengine/postmark
$ cd postmark
$ cabal install --only-dependencies &&  cabal configure -f demo  && cabal build
$ ./dist/build/postmark-demo/postmark-demo

Issues can be reported at https://github.com/apiengine/postmark/issues.

Synopsis

data PostmarkSettings = PostmarkSettings {
- apiUrl :: Text
- apiToken :: PostmarkApiToken
}
type PostmarkApiToken = Text
postmarkHttp :: PostmarkApiToken -> PostmarkSettings
postmarkHttps :: PostmarkApiToken -> PostmarkSettings
postmarkTestToken :: PostmarkApiToken
postmarkHttpTest :: PostmarkSettings
postmarkHttpsTest :: PostmarkSettings
email :: Email -> PostmarkRequest' Sent
emails :: [Email] -> PostmarkRequest' [Sent]
data Email = Email {
- emailFrom :: Text
- emailTo :: [Text]
- emailCc :: [Text]
- emailBcc :: [Text]
- emailSubject :: Text
- emailTag :: Maybe Text
- emailHtml :: Maybe Text
- emailText :: Maybe Text
- emailReplyTo :: Text
- emailHeaders :: Map Text Text
- emailTrackOpens :: Maybe Bool
- emailTrackLinks :: Maybe TrackLinks
- emailAttachments :: [Attachment]
}
defaultEmail :: Email
emailWithTemplate :: EmailWithTemplate -> PostmarkRequest' Sent
data EmailWithTemplate = EmailWithTemplate {
- templateId :: Int
- templateModel :: Map Text Text
- inlineCss :: Bool
- emailFrom' :: Text
- emailTo' :: [Text]
- emailCc' :: [Text]
- emailBcc' :: [Text]
- emailTag' :: Maybe Text
- emailReplyTo' :: Text
- emailHeaders' :: Map Text Text
- emailTrackOpens' :: Maybe Bool
- emailTrackLinks' :: Maybe TrackLinks
- emailAttachments' :: [Attachment]
}
defaultEmailWithTemplate :: EmailWithTemplate
data TrackLinks
- = None
- | HtmlAndText
- | HtmlOnly
- | TextOnly
data Attachment = Attachment {
- attachmentName :: Text
- attachmentContent :: Text
- attachmentContentType :: Text
}
data Sent = Sent {
- postmarkMessageId :: Text
- postmarkSubmittedAt :: Text
- postmarkTo :: Text
}
data PostmarkError = PostmarkError {
- errorType :: PostmarkErrorType
- errorMessage :: Text
}
data PostmarkErrorType
- = PostmarkBadApiToken
- | PostmarkInvalidEmail
- | PostmarkSenderNotFound
- | PostmarkSenderNotConfirmed
- | PostmarkInvalidJson
- | PostmarkIncompatibleJson
- | PostmarkNotAllowed
- | PostmarkInactive
- | PostmarkBounceNotFound
- | PostmarkBounceQueryException
- | PostmarkJsonRequired
- | PostmarkTooManyMessages
- | PostmarkTemplateQueryException
- | PostmarkTemplateNotFound
- | PostmarkTemplateLimitWouldBeExceeded
- | PostmarkTemplateNoDataReceived
- | PostmarkTemplateRequiredFieldMissing
- | PostmarkTemplateFieldTooLarge
- | PostmarkTemplateFieldInvalid
- | PostmarkUnkownError Int
request :: PostmarkSettings -> PostmarkRequest e a -> IO (PostmarkResponse e a)
data PostmarkRequest e a where
- PostmarkRequest :: (FromJSON e, FromJSON a) => StdMethod -> Text -> RequestTransformer -> PostmarkRequest e a
type PostmarkRequest' a = PostmarkRequest PostmarkError a
data PostmarkResponse e a
- = PostmarkSuccess a
- | PostmarkUnauthorized
- | PostmarkFailure e
- | PostmarkUnexpected PostmarkUnexpectedType Int (Maybe Text) (Maybe Text)
data PostmarkUnexpectedType
- = ServerError
- | UnexpectedResponseCode
- | JsonSyntaxError
- | JsonFormatError
type PostmarkResponse' a = PostmarkResponse PostmarkError a
syntaxErr :: Int -> ByteString -> Text -> PostmarkResponse e a
formatErr :: Int -> ByteString -> Text -> PostmarkResponse e a

Settings

data PostmarkSettings Source #

To construct PostmarkSettings, use postmarkHttps or postmarkHttp.

Or to use the test API instead, use postmarkHttpsTest or postmarkHttpTest.

Constructors

PostmarkSettings
Fields apiUrl :: Text apiToken :: PostmarkApiToken

Instances

Eq PostmarkSettings Source #
Instance details Defined in Network.Api.Postmark.Settings Methods (==) :: PostmarkSettings -> PostmarkSettings -> Bool # (/=) :: PostmarkSettings -> PostmarkSettings -> Bool #
Show PostmarkSettings Source #
Instance details Defined in Network.Api.Postmark.Settings Methods showsPrec :: Int -> PostmarkSettings -> ShowS # show :: PostmarkSettings -> String # showList :: [PostmarkSettings] -> ShowS #

type PostmarkApiToken = Text Source #

The Postmark “server token” which is sent via the X-Postmark-Server-Token HTTP header. You can find your server token under the “Credentials” tab on the Postmark website.

If you do not yet have a Postmark account, or if you want to send test emails that don't actually get delivered, you may use postmarkTestToken.

https://postmarkapp.com/developer/api/overview#authentication

postmarkHttp :: PostmarkApiToken -> PostmarkSettings Source #

Constructs Postmark settings using the HTTP protocol and your API token.

HTTPS is recommended instead (postmarkHttps).

postmarkHttps :: PostmarkApiToken -> PostmarkSettings Source #

Constructs Postmark settings using the HTTPS protocol and your API token.

Using the test token

postmarkTestToken :: PostmarkApiToken Source #

An API token that you can use when you want to send test emails that don't actually get delivered to the recipient.

https://postmarkapp.com/developer/api/overview#authentication

postmarkHttpTest :: PostmarkSettings Source #

Postmark settings using the HTTP protocol and the test API token (postmarkTestToken).

HTTPS is recommended instead (postmarkHttpsTest).

postmarkHttpsTest :: PostmarkSettings Source #

Postmark settings using the HTTPS protocol and the test API token (postmarkTestToken).

Sending email

email :: Email -> PostmarkRequest' Sent Source #

Send a single email: http://developer.postmarkapp.com/developer-build.html

emails :: [Email] -> PostmarkRequest' [Sent] Source #

Bulk send emails: http://developer.postmarkapp.com/developer-build.html#batching-messages

data Email Source #

Email data type. It is recommended that you use the defaultEmail function and selector syntax to build an email, e.g.:

defaultEmail {
    emailFrom = "you@yourdomain.com"
  , emailTo = "person@example.com"
  , emailSubject = "This is an example email!"
  }

Constructors

Email
Fields emailFrom :: Text emailTo :: [Text] emailCc :: [Text] emailBcc :: [Text] emailSubject :: Text emailTag :: Maybe Text emailHtml :: Maybe Text emailText :: Maybe Text emailReplyTo :: Text emailHeaders :: Map Text Text emailTrackOpens :: Maybe Bool emailTrackLinks :: Maybe TrackLinks emailAttachments :: [Attachment]

Instances

ToJSON Email Source #
Instance details Defined in Network.Api.Postmark.Data Methods toJSON :: Email -> Value # toEncoding :: Email -> Encoding # toJSONList :: [Email] -> Value # toEncodingList :: [Email] -> Encoding #

defaultEmail :: Email Source #

Using a template

emailWithTemplate :: EmailWithTemplate -> PostmarkRequest' Sent Source #

Send a single email using a template: https://postmarkapp.com/developer/api/templates-api#email-with-template

data EmailWithTemplate Source #

Constructors

EmailWithTemplate
Fields templateId :: Int templateModel :: Map Text Text inlineCss :: Bool emailFrom' :: Text emailTo' :: [Text] emailCc' :: [Text] emailBcc' :: [Text] emailTag' :: Maybe Text emailReplyTo' :: Text emailHeaders' :: Map Text Text emailTrackOpens' :: Maybe Bool emailTrackLinks' :: Maybe TrackLinks emailAttachments' :: [Attachment]

Instances

ToJSON EmailWithTemplate Source #
Instance details Defined in Network.Api.Postmark.Data Methods toJSON :: EmailWithTemplate -> Value # toEncoding :: EmailWithTemplate -> Encoding # toJSONList :: [EmailWithTemplate] -> Value # toEncodingList :: [EmailWithTemplate] -> Encoding #

defaultEmailWithTemplate :: EmailWithTemplate Source #

When “link tracking” is enabled, Postmark will record statistics when a user clicks on a link in an email. You can use this feature to determine if a particular recipient has clicked a link that was emailed to them.

https://postmarkapp.com/developer/user-guide/tracking-links#enabling-link-tracking

Constructors

None	No links will be replaced or tracked.
HtmlAndText	Links will be replaced in both HTML and text bodies.
HtmlOnly	Links will be replaced in only the HTML body. You may want this option if you do not want encoded tracking links to appear in the plain text of an email.
TextOnly	Links will be replaced in only the text body.

Instances

Show TrackLinks Source #
Instance details Defined in Network.Api.Postmark.Data Methods showsPrec :: Int -> TrackLinks -> ShowS # show :: TrackLinks -> String # showList :: [TrackLinks] -> ShowS #
ToJSON TrackLinks Source #
Instance details Defined in Network.Api.Postmark.Data Methods toJSON :: TrackLinks -> Value # toEncoding :: TrackLinks -> Encoding # toJSONList :: [TrackLinks] -> Value # toEncodingList :: [TrackLinks] -> Encoding #

Attachments

data Attachment Source #

Constructors

Attachment
Fields attachmentName :: Text attachmentContent :: Text attachmentContentType :: Text

Instances

ToJSON Attachment Source #
Instance details Defined in Network.Api.Postmark.Data Methods toJSON :: Attachment -> Value # toEncoding :: Attachment -> Encoding # toJSONList :: [Attachment] -> Value # toEncodingList :: [Attachment] -> Encoding #

Response type

data Sent Source #

Constructors

Sent
Fields postmarkMessageId :: Text postmarkSubmittedAt :: Text postmarkTo :: Text

Instances

Eq Sent Source #
Instance details Defined in Network.Api.Postmark.Data Methods (==) :: Sent -> Sent -> Bool # (/=) :: Sent -> Sent -> Bool #
Show Sent Source #
Instance details Defined in Network.Api.Postmark.Data Methods showsPrec :: Int -> Sent -> ShowS # show :: Sent -> String # showList :: [Sent] -> ShowS #
FromJSON Sent Source #
Instance details Defined in Network.Api.Postmark.Data Methods parseJSON :: Value -> Parser Sent # parseJSONList :: Value -> Parser [Sent] #

Error types

data PostmarkError Source #

Constructors

PostmarkError
Fields errorType :: PostmarkErrorType errorMessage :: Text

Instances

Eq PostmarkError Source #
Instance details Defined in Network.Api.Postmark.Error Methods (==) :: PostmarkError -> PostmarkError -> Bool # (/=) :: PostmarkError -> PostmarkError -> Bool #
Show PostmarkError Source #
Instance details Defined in Network.Api.Postmark.Error Methods showsPrec :: Int -> PostmarkError -> ShowS # show :: PostmarkError -> String # showList :: [PostmarkError] -> ShowS #
FromJSON PostmarkError Source #
Instance details Defined in Network.Api.Postmark.Error Methods parseJSON :: Value -> Parser PostmarkError # parseJSONList :: Value -> Parser [PostmarkError] #

data PostmarkErrorType Source #

Instances

Eq PostmarkErrorType Source #
Instance details Defined in Network.Api.Postmark.Error Methods (==) :: PostmarkErrorType -> PostmarkErrorType -> Bool # (/=) :: PostmarkErrorType -> PostmarkErrorType -> Bool #
Show PostmarkErrorType Source #
Instance details Defined in Network.Api.Postmark.Error Methods showsPrec :: Int -> PostmarkErrorType -> ShowS # show :: PostmarkErrorType -> String # showList :: [PostmarkErrorType] -> ShowS #

Lower-level API

Request

request :: PostmarkSettings -> PostmarkRequest e a -> IO (PostmarkResponse e a) Source #

Run the specified request with the specified settings.

data PostmarkRequest e a where Source #

Constructors

PostmarkRequest :: (FromJSON e, FromJSON a) => StdMethod -> Text -> RequestTransformer -> PostmarkRequest e a

type PostmarkRequest' a = PostmarkRequest PostmarkError a Source #

Response

data PostmarkResponse e a Source #

Constructors

PostmarkSuccess a
PostmarkUnauthorized
PostmarkFailure e
PostmarkUnexpected PostmarkUnexpectedType Int (Maybe Text) (Maybe Text)

Instances

(Eq a, Eq e) => Eq (PostmarkResponse e a) Source #
Instance details Defined in Network.Api.Postmark.Response Methods (==) :: PostmarkResponse e a -> PostmarkResponse e a -> Bool # (/=) :: PostmarkResponse e a -> PostmarkResponse e a -> Bool #
(Show a, Show e) => Show (PostmarkResponse e a) Source #
Instance details Defined in Network.Api.Postmark.Response Methods showsPrec :: Int -> PostmarkResponse e a -> ShowS # show :: PostmarkResponse e a -> String # showList :: [PostmarkResponse e a] -> ShowS #

data PostmarkUnexpectedType Source #

Constructors

ServerError
UnexpectedResponseCode
JsonSyntaxError
JsonFormatError

Instances

Eq PostmarkUnexpectedType Source #
Instance details Defined in Network.Api.Postmark.Response Methods (==) :: PostmarkUnexpectedType -> PostmarkUnexpectedType -> Bool # (/=) :: PostmarkUnexpectedType -> PostmarkUnexpectedType -> Bool #
Show PostmarkUnexpectedType Source #
Instance details Defined in Network.Api.Postmark.Response Methods showsPrec :: Int -> PostmarkUnexpectedType -> ShowS # show :: PostmarkUnexpectedType -> String # showList :: [PostmarkUnexpectedType] -> ShowS #

type PostmarkResponse' a = PostmarkResponse PostmarkError a Source #

syntaxErr :: Int -> ByteString -> Text -> PostmarkResponse e a Source #

formatErr :: Int -> ByteString -> Text -> PostmarkResponse e a Source #

PostmarkBadApiToken
PostmarkInvalidEmail
PostmarkSenderNotFound
PostmarkSenderNotConfirmed
PostmarkInvalidJson
PostmarkIncompatibleJson
PostmarkNotAllowed
PostmarkInactive
PostmarkBounceNotFound
PostmarkBounceQueryException
PostmarkJsonRequired
PostmarkTooManyMessages
PostmarkTemplateQueryException
PostmarkTemplateNotFound
PostmarkTemplateLimitWouldBeExceeded
PostmarkTemplateNoDataReceived
PostmarkTemplateRequiredFieldMissing
PostmarkTemplateFieldTooLarge
PostmarkTemplateFieldInvalid
PostmarkUnkownError Int

Settings

Using the test token

Sending email

Using a template

Tracking links

Attachments

Response type

Error types

Lower-level API

Request

Response