postmark

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 21, 2023 License: MIT Imports: 9 Imported by: 15

README

postmark-go

GoDoc Build Status license

postmark-go is a Go client library for accessing the Postmark API (http://developer.postmarkapp.com/).

This is an unofficial library that is not affiliated with Postmark. Official libraries are available here.

v1.0 Breaking Changes

The signature of NewClient has changed. It now accepts options, one of which can be a custom HTTP client. Please pin to an older version if required.

Installation

go get -u github.com/mattevans/postmark-go

Setup

You'll need to pass an SERVER_API_TOKEN when initializing the client. This token can be found under the 'Credentials' tab of your Postmark server. More info here.

Client + Authentication

client := postmark.NewClient(
    postmark.WithClient(&http.Client{
        Transport: &postmark.AuthTransport{Token: "SERVER_API_TOKEN"},
    }),
)

Example usage (with Template)

emailReq := &postmark.Email{
  From:       "mail@company.com",
  To:         "jack@sparrow.com",
  TemplateID: 123456,
  TemplateModel: map[string]interface{}{
    "name": "Jack",
    "action_url": "http://click.company.com/welcome",
  },
  Tag:        "onboarding",
  TrackOpens: true,
  Metadata: map[string]string{
    "client-id": "123456",
    "client-ip": "127.0.0.1",
  },
}

email, response, err := client.Email.Send(emailReq)
if err != nil {
  return err
}

Example usage (with HtmlBody)

emailReq := &postmark.Email{
  From:       "mail@company.com",
  To:         "jack@sparrow.com",
  Subject:    "My Test Email",
  HtmlBody:   "<html><body><strong>Hello</strong> dear Postmark user.</body></html>",
  TextBody:   "Hello dear Postmark user",
  Tag:        "onboarding",
  TrackOpens: true,
  Metadata: map[string]string{
    "client-id": "123456",
    "client-ip": "127.0.0.1",
  },
}

email, response, err := client.Email.Send(emailReq)
if err != nil {
  return err
}

What's Implemented?

At the moment only a handful of the more common endpoints have been implemented. Open an issue (or PR) if you required something that's missing.

Thanks & Acknowledgements 👌

The packages's architecture is adapted from go-github, created by Will Norris. 🍻

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckResponse 

func CheckResponse(r *http.Response) error

CheckResponse checks the API response for errors. A response is considered an error if it has a status code outside the 200 range. API error responses map to ErrorResponse.

Types

type AuthTransport 

type AuthTransport struct {
	Transport http.RoundTripper
	Token     string
}

AuthTransport holds a authentication information for Postmark API.

func (*AuthTransport) RoundTrip 

func (t *AuthTransport) RoundTrip(req *http.Request) (resp *http.Response, err error)

RoundTrip implements the RoundTripper interface.

type Bounce added in v0.1.3 

type Bounce struct {
	ID            int64
	Type          string
	TypeCode      int64
	Name          string
	Tag           string
	MessageID     string
	Description   string
	Details       string
	Email         string
	BouncedAt     time.Time
	DumpAvailable bool
	Inactive      bool
	CanActivate   bool
	Subject       string
}

Bounce represents a BounceType in further detail.

type BounceActivated added in v0.1.4 

type BounceActivated struct {
	Message string
	Bounce  Bounce
}

BounceActivated represents a bounce that has been reactivated.

type BounceDeliveryStats added in v0.1.2 

type BounceDeliveryStats struct {
	InactiveMails int64
	Bounces       []BounceType
}

BounceDeliveryStats represents a collection of bounce stats.

type BounceDump added in v0.1.4 

type BounceDump struct {
	Body string
}

BounceDump represents a the raw source of bounce.

type BounceService added in v0.1.2 

type BounceService service

BounceService handles communication with the bounce related methods of the Postmark API (http://developer.postmarkapp.com/developer-api-bounce.html)

func (*BounceService) ActivateBounce added in v0.1.4 

func (s *BounceService) ActivateBounce(bounceID int64) (*BounceActivated, *Response, error)

ActivateBounce will attempt to reactivate this email via bounce ID.

func (*BounceService) GetBounceDump added in v0.1.4 

func (s *BounceService) GetBounceDump(bounceID int64) (*BounceDump, *Response, error)

GetBounceDump will return a single bounce dump by ID.

func (*BounceService) GetBounceTags added in v0.1.4 

func (s *BounceService) GetBounceTags() ([]string, *Response, error)

GetBounceTags will return a slice of tag values that have generated bounces.

func (*BounceService) GetBounces added in v0.1.3 

func (s *BounceService) GetBounces(bounceCount, bounceOffset int, parameters map[string]interface{}) (*Bounces, *Response, error)

GetBounces will return all bounces.

func (*BounceService) GetDeliveryStats added in v0.1.2 

func (s *BounceService) GetDeliveryStats() (*BounceDeliveryStats, *Response, error)

GetDeliveryStats will return all delivery stats aggregated by bounce type.

func (*BounceService) GetSingleBounce added in v0.1.4 

func (s *BounceService) GetSingleBounce(bounceID int64) (*Bounce, *Response, error)

GetSingleBounce will return a single bounce by ID.

type BounceType added in v0.1.2 

type BounceType struct {
	Type  string
	Name  string
	Count int64
}

BounceType represents the type of bounce with a count.

type Bounces added in v0.1.3 

type Bounces struct {
	TotalCount int64
	Bounces    []Bounce
}

Bounces represents a slice of bounces and a given count.

type Client 

type Client struct {
	Token      string
	UserAgent  string
	BackendURL *url.URL

	// Services used for communicating with the API.
	Email    *EmailService
	Bounce   *BounceService
	Template *TemplateService
	// contains filtered or unexported fields
}

Client holds a connection to the Postmark API.

func NewClient 

func NewClient(opts ...Option) *Client

NewClient creates a new Client with the appropriate connection details and services used for communicating with the API.

func (*Client) Do 

func (c *Client) Do(req *http.Request, v interface{}) (*Response, error)

Do sends an API request and returns the API response. The API response is JSON decoded and stored in 'v', or returned as an error if an API (if found).

func (*Client) NewRequest 

func (c *Client) NewRequest(method, urlPath string, body interface{}) (*http.Request, error)

NewRequest creates an API request. A relative URL can be provided in urlPath, which will be resolved to the BackendURL of the Client.

type Email 

type Email struct {
	From          string                 `json:",omitempty"`
	To            string                 `json:",omitempty"`
	Cc            string                 `json:",omitempty"`
	Bcc           string                 `json:",omitempty"`
	Subject       string                 `json:",omitempty"`
	Tag           string                 `json:",omitempty"`
	TemplateID    int                    `json:",omitempty"`
	TemplateModel map[string]interface{} `json:",omitempty"`
	HTMLBody      string                 `json:",omitempty"`
	TextBody      string                 `json:",omitempty"`
	ReplyTo       string                 `json:",omitempty"`
	Headers       []EmailHeader          `json:",omitempty"`
	Attachments   []EmailAttachment      `json:",omitempty"`
	TrackOpens    bool                   `json:",omitempty"`
	MessageStream string                 `json:",omitempty"`
	Metadata      map[string]string      `json:",omitempty"`
}

Email is the set of parameters that can be used when sending an email.

type EmailAttachment added in v0.1.1 

type EmailAttachment struct {
	Name        string
	Content     []byte
	ContentType *string
}

EmailAttachment represents the values for an email attachment.

type EmailHeader 

type EmailHeader struct {
	Name  string
	Value string
}

EmailHeader represents the values for an email header.

type EmailResponse 

type EmailResponse struct {
	To          string
	SubmittedAt time.Time
	MessageID   string
}

EmailResponse is the set of parameters that is used in response to a send request

type EmailService 

type EmailService service

EmailService handles communication with the email related methods of the Postmark API (http://developer.postmarkapp.com/developer-api-email.html)

func (*EmailService) Send 

func (s *EmailService) Send(emailRequest *Email) (*EmailResponse, *Response, error)

Send will build and execute request to send an email via the API.

func (*EmailService) SendBatch 

func (s *EmailService) SendBatch(emailRequests []*Email) ([]*EmailResponse, *Response, error)

SendBatch will build and execute request to send batch emails via the API.

type ErrorResponse 

type ErrorResponse struct {
	*http.Response
	ErrorCode int64
	Message   string
}

An ErrorResponse reports the error caused by an API request

func (*ErrorResponse) Error 

func (r *ErrorResponse) Error() string

type Option added in v1.0.0 

type Option func(o *Options)

Option to set an optional client value.

func WithBackendURL added in v1.0.0 

func WithBackendURL(v string) Option

WithBackendURL allows you to set a custom backend URL.

func WithClient added in v1.0.0 

func WithClient(v *http.Client) Option

WithClient allows you to set a custom http client.

func WithUserAgent added in v1.0.0 

func WithUserAgent(v string) Option

WithUserAgent allows you to set a custom user agent.

type Options added in v1.0.0 

type Options struct {
	Client     *http.Client
	BackendURL string
	UserAgent  string
}

Options for our client.

func NewOptions added in v1.0.0 

func NewOptions(opts ...Option) *Options

NewOptions returns a new Options with defaults and supplied overrides.

type Response 

type Response struct {
	*http.Response
	ErrorCode int64
	Message   string
}

Response is a Postmark response. This wraps the standard http.Response returned from the Postmark API.

type Template added in v0.1.4 

type Template struct {
	TemplateId         int64
	Name               string
	Subject            string
	HtmlBody           string
	TextBody           string
	AssociatedServerId int64
	Active             bool
}

Template represents a templates in further detail.

type TemplateOverview added in v0.1.4 

type TemplateOverview struct {
	TemplateId int64
	Name       string
	Active     bool
}

TemplateOverview represents overview/identifying information about a template.

type TemplateService added in v0.1.4 

type TemplateService service

TemplateService handles communication with the template related methods of the Postmark API (https://postmarkapp.com/developer/api/templates-api)

func (*TemplateService) GetSingleTemplate added in v0.1.4 

func (s *TemplateService) GetSingleTemplate(templateID int64) (*Template, *Response, error)

GetSingleTemplate will return a single template by ID.

func (*TemplateService) GetTemplates added in v0.1.4 

func (s *TemplateService) GetTemplates(count, offset int) (*Templates, *Response, error)

GetTemplates will return all templates.

type Templates added in v0.1.4 

type Templates struct {
	TotalCount int64
	Templates  []TemplateOverview
}

Templates represents a slice of templates and a given count.

Source Files

View all Source files

Directories

Path Synopsis
examples
batch-emails
bounce
send-email
send-email-attachment

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.