An erlang library for consuming the Postmark mail service api
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc
examples
src
.gitignore
LICENSE
README.md
erlang_postmarkapp.iml
init.sh
rebar.config
rebar.lock
rebar3

README.md

erlang_postmarkapp

An erlang library for consuming the Postmark mail service api. It was inspired by the official Postmark PHP package https://github.com/wildbit/postmark-php.

Build

$ rebar3 compile

Quickstart

To use it from the console you can just do this:

$ ./init.sh

This will build it, and start the Erlang shell.

Supported Operations

At the moment, the library only supports: sending emails, handling bounces and managing servers.

Installation

You can add it to your rebar.config like so:

{deps, [
       ...
       {erlang_postmarkapp, "1.*", {git, "https://github.com/emmanix2002/erlang_postmarkapp.git", {branch, "master"}}}
]}.

Data Types

deliveryStat()

deliveryStat() = {inactive_mails, integer()} | {bounces, [#postmark_bounce_stats{}]}

deliveryStatsResponse()

deliveryStatsResponse() = [deliveryStat()] | {error, string()}

bounce()

bounce() = #postmark_bounce{}

bounces()

bounces() = [bounce()]

bouncesInfo()

bouncesInfo() = {total, integer()} | {bounces, bounces()}

bouncesResponse()

bouncesResponse() = [bouncesInfo()]

emailBody()

emailBody() = {text, string()} | {html, string()}

optionalValue()

optionalValue() = string() | undefined

optionalListValue()

optionalListValue() = list() | undefined

postmarkEmail()

postmarkEmail() = #postmark_email{}

postmarkEmails()

postmarkEmails() = [postmarkEmail()]

sendEmailResponse()

sendEmailResponse() = {ok, string()} | {error, string()}

serverColor()

serverColor() = purple | blue | turqoise | green | red | yellow | grey

tag()

tag() = string()

tags()

tags() = [tag()]

trackLinkStatus()

trackLinkStatus() = none | html_and_text | html_only | text_only

Record Types

#postmark_email{}

-record(postmark_email, { from :: string(), to :: string(), subject :: string(), html :: optionalValue(), text :: optionalValue(), tag :: optionalValue(), track_opens=true :: boolean(), reply_to :: optionalValue(), cc :: optionalValue(), bcc :: optionalValue(), track_links :: trackLinkStatus(), template_id :: optionalValue(), template_model :: optionalListValue(), inline_css=true :: boolean() })

#postmark_send_response{}

-record(postmark_send_response, { message_id :: string(), error_code :: integer(), message :: string() })

#postmark_bounce_request{}

-record(postmark_bounce_request, { count=500 :: integer(), offset=0 :: integer(), bounce_type :: string(), email :: string(), inactive :: boolean(), tag :: string(), message_id :: string(), from_date :: string(), to_date :: string() })

#postmark_bounce_stats{}

-record(postmark_bounce_stats, { type :: optionalValue(), name :: string(), count :: integer() })

#postmark_bounce{}

-record(postmark_bounce, { id :: integer(), type :: string(), type_code :: integer(), name :: string(), tag :: optionalValue(), message_id :: optionalValue(), server_id :: optionalValue(), description :: optionalValue(), details :: optionalValue(), email :: string(), from :: string(), bounced_at :: string(), dump_available :: boolean(), inactive :: boolean(), can_activate :: boolean(), subject :: string() })

#postmark_server{}

-record(postmark_server, { id :: integer(), name :: string(), api_tokens=[] :: list(), server_link :: string(), color :: serverColor(), smtp_api_activated :: boolean(), raw_email_enabled :: boolean(), delivery_hook_url :: string(), inbound_address :: string(), inbound_hook_url :: string(), bounce_hook_url :: string(), include_bounce_content_in_hook :: boolean(), open_hook_url :: boolean(), post_first_open_only :: boolean(), track_opens :: boolean(), track_links :: trackLinkStatus(), inbound_domain :: string(), inbound_hash :: string(), inbound_spam_threshold :: integer() })

Modules Index (Exports)

erlang_postmarkapp (Email)

setup/1, setup/2, send_email/1, send_email/4, send_email/11, send_email_with_template/1, send_email_with_template/10,
send_email_batch/1, get_server_token/0, get_account_token/0, track_links_to_string/1

erlang_postmarkapp_bounces (Bounces)

activate_bounce/1, get_delivery_stats/0, get_bounces/1, get_bounce/1, get_bounce_dump/1, get_bounce_tags/0,

erlang_postmarkapp_server (Server)

get_server/0, edit_server/1

Exported Function Details

activate_bounce/1

activate_bounce(BounceId::integer()) -> {ok, bounce()} | {error, string()}

get_bounces/1

get_bounces(BounceRequestRecord::#postmark_bounce_request{}) -> bouncesResponse() | {error, string()}

get_bounce/1

get_bounce(BounceId::integer()) -> {ok, bounce()} | {error, string()}

get_bounce_dump/1

get_bounce_dump(BounceId::integer()) -> {ok, string()} | {error, string()}

get_bounce_tags/0

get_bounce_tags() -> {ok, tags()} | {error, string()}

get_delivery_stats/0

get_delivery_stats() -> deliveryStatsResponse()

get_server/0

get_server() -> {ok, #postmark_server{}} | {error, string()}

edit_server/1

edit_server(ServerRecord::#postmark_server{}) -> {ok, #postmark_server{}} | {error, string()}

setup/1

setup(ServerToken::string()) -> ok

setup/2

setup(ServerToken::string(), AccountToken::string()) -> ok

get_server_token/0

get_server_token() -> string()

get_account_token/0

get_account_token() -> string()

send_email/1

send_email(PostmarkEmail::#postmark_email{}) -> sendEmailResponse()

send_email/4

send_email(From::string(), To::string(), Subject::string(), Body::emailBody()) -> sendEmailResponse()

send_email/11

send_email(From::string(), To::string(), Subject::string(), HtmlBody::optionalValue(), TextBody::optionalValue(), Tag::string(), TrackOpens::boolean(), ReplyTo::optionalValue(), Cc::optionalValue(), Bcc::optionalValue(), TrackLinks::trackLinkStatus()) -> sendEmailResponse()

send_email_batch/1

send_email_batch(PostmarkEmailList::postmarkEmails()) -> sendEmailResponse()

send_email_with_template/1

send_email_with_template(PostmarkEmail::#postmark_email{}) -> sendEmailResponse()

send_email_with_template/10

send_email_with_template(From::string(), To::string(), TemplateId::string(), TemplateModel::list(), Tag:: optionalValue(), TrackOpens::boolean(), ReplyTo::optionalValue(), Cc::optionalValue(), Bcc:: optionalValue(), TrackLinks::trackLinkStatus()) -> sendEmailResponse()

track_links_to_string/1

track_links_to_string(TrackLinkStatus::trackLinkStatus()) -> string()

Usage

To use the library, you need to set it up by providing the Server Token [and optionally an Account Token].
Before you start making calls, you need to call the setup/1 or setup/2 functions to initialise the library and start all required processes. Recommendation: It is best to put the call to setup() in your init function, if you have any.

See an example below:
This is a simple example of sending a plaintext email using the library.

send_text_mail() ->
    ServerToken = "your server token here",
    erlang_postmarkapp:setup(ServerToken),
    Body = {text, "Hello World!"},
    case erlang_postmarkapp:send_email("signature@domain.com", "recipient@example.com", "A good example", Body) of
        {ok, MessageId} -> io:format("Successfully sent email with MessageID ~p~n", [MessageId]);
        {error, Reason} -> io:format("Message sending failed because ~p~n", [Reason])
    end.
  • setup(ServerToken): sets the server token that will be used to authenticate with the Postmark API.
  • send_email*(): these functions allow you to send an email.

NOTE: based on the information on the Postman documentation, batch emails are limited to a maximum of 500 messages (the library enforces this); while for single emails, you can have at most 50 email addresses from a combination of all: To, Cc, and Bcc addresses.