mailform

README

go-mailform

A small library to send physical mail from your Go applications using https://mailform.io

Usage

First you will need an API Token from mailform.io

go get github.com/circa10a/go-mailform

package main

import (
	"fmt"
	"os"

	"github.com/circa10a/go-mailform"
)

func main() {
	client, err := mailform.New(&mailform.Config{
		Token: "MAILFORM_API_TOKEN",
	})
	if err != nil {
		fmt.Println(err)
	}

	// Create order
	// You can send a PDF file via local filesystem path or a URL.
	// FilePath will take precedence over URL.
	order, err := client.CreateOrder(mailform.OrderInput{
		// Send local pdf
		FilePath: "./sample.pdf",
		// Or you can send the file via URL
		URL: "http://s3.amazonaws.com/some-bucket/sample.pdf",
		// Shipping service options:
		// FEDEX_OVERNIGHT USPS_PRIORITY_EXPRESS USPS_PRIORITY USPS_CERTIFIED_PHYSICAL_RECEIPT USPS_CERTIFIED_RECEIPT USPS_CERTIFIED USPS_FIRST_CLASS USPS_STANDARD USPS_POSTCARD
		Service:      "USPS_PRIORITY",
		ToName:       "A Name",
		ToAddress1:   "Address 1",
		ToCity:       "Seattle",
		ToState:      "WA",
		ToPostcode:   "00000",
		ToCountry:    "US",
		FromName:     "My Name",
		FromAddress1: "My Address 1",
		FromCity:     "Dallas",
		FromState:    "TX",
		FromPostcode: "00000",
		FromCountry:  "US",
	})

	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	fmt.Println("Order ID", order.Data.ID)

	// Get Order
	orderDetails, err := client.GetOrder(order.Data.ID)
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	fmt.Println(orderDetails.Data)
}

Documentation

Index

• Constants
• Variables
• type Client
  • func New(c *Config) (*Client, error)
  • func (c *Client) CreateOrder(o OrderInput) (*Order, error)
  • func (c *Client) GetOrder(o string) (*Order, error)
• type Config
• type ErrMailform
  • func (e *ErrMailform) Error() string
• type ErrOrderInvalid
  • func (e *ErrOrderInvalid) Error() string
• type Order
• type OrderInput
  • func (o *OrderInput) FormData() map[string]string
  • func (o *OrderInput) Validate() error

Constants

const (
	// DefaultBaseURL is the default mailform API base url, but is can be overwritten via Config
	DefaultBaseURL = "https://www.mailform.io/app/api/v1"
	DefaultTimeout = time.Second * 15
	// Order Statuses
	StatusCancelled           = "cancelled"
	StatusQueued              = "queued"
	StatusAwaitingFulfillment = "awaiting_fulfillment"
	StatusFulfilled           = "fulfilled"
)

Variables

var (
	// ErrNilConfig is returned when a nil config is being passed to New().
	ErrNilConfig = errors.New("config cannot be nil")
)

var (
	// Service codes are the supported delivery services
	ServiceCodes = []string{
		"FEDEX_OVERNIGHT",
		"USPS_PRIORITY_EXPRESS",
		"USPS_PRIORITY",
		"USPS_CERTIFIED_PHYSICAL_RECEIPT",
		"USPS_CERTIFIED_RECEIPT",
		"USPS_CERTIFIED",
		"USPS_FIRST_CLASS",
		"USPS_STANDARD",
		"USPS_POSTCARD",
	}
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the mailform REST API client.

func New

func New(c *Config) (*Client, error)

New returns a new mailform REST API client.

func (*Client) CreateOrder

func (c *Client) CreateOrder(o OrderInput) (*Order, error)

CreateOrder creates a mailform order.

func (*Client) GetOrder

func (c *Client) GetOrder(o string) (*Order, error)

GetOrder gets a mailform order.

type Config

type Config struct {
	Token   string
	BaseURL string
	Timeout time.Duration
}

Config is the configuration used to communicate with the mailform API.

type ErrMailform

type ErrMailform struct {
	Err struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
	Detail string `json:"detail"`
}

ErrMailform is the error returned when mailform responds with an error.

func (*ErrMailform) Error

func (e *ErrMailform) Error() string

type ErrOrderInvalid

type ErrOrderInvalid struct {
	// contains filtered or unexported fields
}

ErrOrderInvalid is returned when order input is invalid

func (*ErrOrderInvalid) Error

func (e *ErrOrderInvalid) Error() string

type Order

type Order struct {
	Success bool `json:"success"`
	Data    struct {
		Object    string    `json:"object"`
		ID        string    `json:"id"`
		Created   time.Time `json:"created"`
		Total     int       `json:"total"`
		Modified  time.Time `json:"modified"`
		Webhook   string    `json:"webhook"`
		Lineitems []struct {
			ID        string `json:"id"`
			Pagecount int    `json:"pagecount"`
			To        struct {
				Name         string `json:"name"`
				Address1     string `json:"address1"`
				Address2     string `json:"address2"`
				City         string `json:"city"`
				State        string `json:"state"`
				Postcode     string `json:"postcode"`
				Country      string `json:"country"`
				Formatted    string `json:"formatted"`
				Organization string `json:"organization"`
			} `json:"to"`
			From struct {
				Name         string `json:"name"`
				Address1     string `json:"address1"`
				Address2     string `json:"address2"`
				City         string `json:"city"`
				State        string `json:"state"`
				Postcode     string `json:"postcode"`
				Country      string `json:"country"`
				Formatted    string `json:"formatted"`
				Organization string `json:"organization"`
			} `json:"from"`
			Simplex bool   `json:"simplex"`
			Color   bool   `json:"color"`
			Service string `json:"service"`
			Pricing []struct {
				Type  string `json:"type"`
				Value int    `json:"value"`
			} `json:"pricing"`
		} `json:"lineitems"`
		Account            string    `json:"account"`
		CustomerReference  string    `json:"customer_reference"`
		Channel            string    `json:"channel"`
		TestMode           bool      `json:"test_mode"`
		State              string    `json:"state"`
		Cancelled          time.Time `json:"cancelled"`
		CancellationReason string    `json:"cancellation_reason"`
	} `json:"data"`
}

Order is the details of an order from mailform.

type OrderInput

type OrderInput struct {
	// FilePath is the path of the file to print and mail
	// The PDF document to be mailed.
	// If this is not specified, the url parameter must be provided.
	// If both the file parameter and the url parameter are provided, the url parameter will be ignored
	FilePath string
	// The URL of the PDF document to be mailed: it will be downloaded completely before the API call completes.
	// The download must complete within 30 seconds.
	// If this is not specified, the file parameter must be provided.
	// If both the file parameter and the url parameter are provided, the url parameter will be ignored
	URL string
	// An optional customer reference to be attached to the order
	CustomerReference string
	// The delivery service to be used.
	// Must be one of FEDEX_OVERNIGHT, USPS_PRIORITY_EXPRESS, USPS_PRIORITY, USPS_CERTIFIED_PHYSICAL_RECEIPT, USPS_CERTIFIED_RECEIPT, USPS_CERTIFIED, USPS_FIRST_CLASS, USPS_STANDARD or USPS_POSTCARD.
	Service string
	// The webhook that should receive notifications about order updates to this order
	Webhook string
	// 	The company that this order should be associated with
	Company string
	// True if the document should be printed one page to a sheet, false if the document can be printed on both sides of a sheet
	Simplex bool
	// True if the document should be printed in color, false if the document should be printed in black and white
	Color bool
	// True if the document MUST be mailed in a flat envelope, false if it is acceptable to mail the document folded
	Flat bool
	// 	True if the document MUST use a real postage stamp, false if it is acceptable to mail the document using metered postage or an imprint
	Stamp bool
	// The message to be printed on the non-picture side of a postcard.
	Message string
	// The name of the recipient of this envelope or postcard
	ToName string
	// The organization or company associated with the recipient of this envelope or postcard
	ToOrganization string
	// The street number and name of the recipient of this envelope or postcard
	ToAddress1 string
	// The suite or room number of the recipient of this envelope or postcard
	ToAddress2 string
	// The address city of the recipient of this envelope or postcard
	ToCity string
	// The address state of the recipient of this envelope or postcard
	ToState string
	// The address postcode or zip code of the recipient of this envelope or postcard
	ToPostcode string
	// 	The address country of the recipient of this envelope or postcard
	ToCountry string
	// The name of the sender of this envelope or postcard
	FromName string
	// The organization or company associated with this address
	FromOrganization string
	// 	The street number and name of the sender of this envelope or postcard
	FromAddress1 string
	// The suite or room number of the sender of this envelope or postcard
	FromAddress2 string
	// The address city of the sender of this envelope or postcard
	FromCity string
	// The address state of the sender of this envelope or postcard
	FromState string
	// The address postcode or zip code of the sender of this envelope or postcard
	FromPostcode string
	// 	The address country of the sender of this envelope or postcard
	FromCountry string
	// The identifier of the bank account for the check associated with this order. Required if a check is to be included in this order.
	BankAccount string
	// The amount of the check associated with this order, in cents. Required if a check is to be included in this order.
	Amount int
	// The name of the recipient of the check associated with this order. Required if a check is to be included in this order.
	CheckName string
	// The number of the check associated with this order. Required if a check is to be included in this order.
	CheckNumber int
	// The memo line for the check associated with this order.
	CheckMemo string
}

OrderInput is the input used to create an order. Representative of the example here: https://www.mailform.io/docs/api/#/orders

func (*OrderInput) FormData

func (o *OrderInput) FormData() map[string]string

FormData converts order input fields to a map[string]string of form data.

func (*OrderInput) Validate

func (o *OrderInput) Validate() error

Validate validates an order input by checking all required fields. https://www.mailform.io/docs/api/#/orders