lob

package module
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: May 11, 2026 License: MIT Imports: 20 Imported by: 0

README

go-lob

Lob.com API client in Go.

Install

Install with

go get github.com/seedco/go-lob

Use

Use by creating a Lob struct with NewLob, and calling the methods it offers.

// fill in your API key and user agent here
l := lob.NewLob(lob.BaseAPI, apiKey, userAgent)

testAddress := &Address{
  Name:           "Lobster Test",
  Email:          "lobtest@example.com",
  Phone:          "5555555555",
  AddressLine1:   "1005 W Burnside St", // Powell's City of Books, the best book store in the world.
  AddressCity:    "Portland",
  AddressState:   "OR",
  AddressZip:     "97209",
  AddressCountry: "US",
}

verify, err := l.VerifyAddress(testAddress)
// ...

You can see the full docs here.

Test

You can run the tests if you set the TEST_LOB_API_KEY environment variable, i.e.,

TEST_LOB_API_KEY=test_yourtestkeyhere go test .

License

Licensed under the MIT license. See LICENSE for more details.

Documentation

Index

Constants

View Source 
const (
	BaseAPI    = "https://api.lob.com/v1/"
	APIVersion = "2020-02-11"
)

Base URL and API version for Lob.

View Source 
const (
	MailTypeUspsStandard   = "usps_standard"
	MailTypeUspsFirstClass = "usps_first_class"
	MailTypeUpsNextDayAir  = "ups_next_day_air"
)

Mail types that lob supports.

Variables

View Source 
var (
	ErrInvalidHeader    = errors.New("webhook has invalid Lob-Signature header(s)")
	ErrNotTimestamped   = errors.New("no Lob-Signature-Timestamp header provided")
	ErrNotSigned        = errors.New("no Lob-Signature header provided")
	ErrNoValidSignature = errors.New("webhook has no valid signature")
	ErrTooOld           = errors.New("timestamp wasn't within tolerance")
)

Errors returned by the webbook parsing

View Source 
var Non200Error = errors.New("Non-200 Status code returned")

Functions

func Bool 

func Bool(val bool) *bool

Bool is a helper function for creating a pointer boolean

func NewFakeLob 

func NewFakeLob() *fakeLob

func NewLob 

func NewLob(baseAPI, apiKey, userAgent string) *lob

NewLob creates an object that can be used to connect to the lob.com API.

func String 

func String(val string) *string

String is a helper function for creating a pointer string

func Uint64 

func Uint64(val uint64) *uint64

Uint64 is a helper function for creating a pointer uint64

func ValidateWebhookPayload 

func ValidateWebhookPayload(payload []byte, timestampHeader, signatureHeader, secret string, tolerance time.Duration) error

ValidateWebhookPayload valides the passed in payload and signature header

Types

type Address 

type Address struct {
	Error          *Error            `json:"error"`
	AddressCity    *string           `json:"address_city"`
	AddressCountry *string           `json:"address_country"`
	AddressLine1   string            `json:"address_line1"`
	AddressLine2   *string           `json:"address_line2"`
	AddressState   *string           `json:"address_state"`
	AddressZip     *string           `json:"address_zip"`
	Company        *string           `json:"company"`
	DateCreated    string            `json:"date_created"`
	DateModified   string            `json:"date_modified"`
	Deleted        *bool             `json:"deleted"`
	Description    *string           `json:"description"`
	Email          *string           `json:"email"`
	ID             string            `json:"id"`
	Metadata       map[string]string `json:"metadata"`
	Name           *string           `json:"name"`
	Object         string            `json:"object"`
	Phone          *string           `json:"phone"`
}

Address represents an address stored in the Lob's system.

type AddressVerificationRequestCasing 

type AddressVerificationRequestCasing string

AddressVerificationRequestCasing states how the verified address should be returned 

var (
	AddressVerificationRequestCasingUpper  AddressVerificationRequestCasing = "upper"
	AddressVerificationRequestCasingProper AddressVerificationRequestCasing = "proper"
)

possible values of AddressVerificationRequestCasing

type BankAccount 

type BankAccount struct {
	Error         *Error            `json:"error"`
	AccountNumber string            `json:"account_number"`
	BankName      string            `json:"bank_name"`
	DateCreated   string            `json:"date_created"`
	DateModified  string            `json:"date_modified"`
	Description   *string           `json:"description"`
	ID            string            `json:"id"`
	Metadata      map[string]string `json:"metadata"`
	Object        string            `json:"object"`
	RoutingNumber string            `json:"routing_number"`
	Signatory     string            `json:"signatory"`
	Verified      bool              `json:"verified"`
}

BankAccount represents a bank account in lob's system.

type CancelCheckResponse 

type CancelCheckResponse struct {
	ID      string `json:"id"`
	Deleted bool   `json:"deleted"`
}

type CancelLetterResponse 

type CancelLetterResponse struct {
	ID      string `json:"id"`
	Deleted bool   `json:"deleted"`
}

CancelLetterResponse is the response returned when deleting a letter

type Check 

type Check struct {
	Error                *Error              `json:"error"`
	Amount               float64             `json:"amount"`
	BankAccount          *BankAccount        `json:"bank_account"`
	CheckBottom          *string             `json:"check_bottom"`
	CheckNumber          int                 `json:"check_number"`
	Data                 map[string]string   `json:"data"`
	DateCreated          string              `json:"date_created"`
	DateModified         string              `json:"date_modified"`
	Description          string              `json:"description"`
	ExpectedDeliveryDate string              `json:"expected_delivery_date"`
	SendDate             time.Time           `json:"send_date"`
	From                 *Address            `json:"from"`
	ID                   string              `json:"id"`
	MailType             *string             `json:"mail_type"`
	Memo                 string              `json:"memo"`
	Message              *string             `json:"message"`
	Metadata             map[string]string   `json:"metadata"`
	Name                 string              `json:"name"`
	Object               string              `json:"object"`
	Thumbnails           []map[string]string `json:"thumbnails"`
	To                   *Address            `json:"to"`
	Tracking             *Tracking           `json:"tracking"`
	URL                  string              `json:"url"`
}

Check represents a printed check in Lob's system.

type CreateBankAccountRequest 

type CreateBankAccountRequest struct {
	Description   *string           `json:"description"`
	RoutingNumber string            `json:"routing_number"`
	AccountNumber string            `json:"account_number"`
	Signatory     string            `json:"signatory"`
	AccountType   string            `json:"account_type"`
	Metadata      map[string]string `json:"metadata"`
}

CreateBankAccountRequest request has the parameters needed to submit a bank account creation request to Lob.

type CreateCheckRequest 

type CreateCheckRequest struct {
	Amount         float64           `json:"amount"`
	BankAccountID  string            `json:"bank_account"`
	CheckBottom    *string           `json:"check_bottom"` // 400 chars, at bottom (cannot use with message)
	CheckNumber    *string           `json:"check_number"`
	Data           map[string]string `json:"data"`
	Description    *string           `json:"description"`
	FromAddressID  string            `json:"from"`
	MailType       *string           `json:"mail_type"`
	Memo           *string           `json:"memo"`    // 40 chars in memo line
	Message        *string           `json:"message"` // 400 chars, at top (cannot use with check_bottom)
	ToAddressID    string            `json:"to"`
	BillingGroupID *string           `json:"billing_group_id"`
}

CreateCheckRequest specifies options for creating a check.

type CreateLetterRequest 

type CreateLetterRequest struct {
	Description      *string                `json:"description"` //must be no longer than 255 characters
	To               Address                `json:"to"`          //if you need the id, simply do lob.Address{ID: "id-here"}
	From             Address                `json:"from"`        //if you need the id, simply do lob.Address{ID: "id-here"}
	BillingGroupID   *string                `json:"billing_group_id"`
	SendDate         *time.Time             `json:"send_date"`
	Color            bool                   `json:"color"`
	File             string                 `json:"file"` //please see lob's create letter documentation: https://lob.com/docs#letters_create
	DoubleSided      bool                   `json:"double_sided"`
	AddressPlacement LetterAddressPlacement `json:"address_placement"`
	MailType         *string                `json:"mail_type"` //MailTypeUspsFirstClass or MailTypeUspsStandard
	ExtraService     *LetterExtraService    `json:"extra_service"`
	ReturnEnvelope   bool                   `json:"return_envelope"`
	PerforatedPage   *uint64                `json:"perforated_page"`
	CustomEnvelope   *CustomEnvelope        `json:"custom_envelope"`
	MergeVariables   map[string]string      `json:"merge_variables"`
	Metadata         map[string]string      `json:"metadata"`
}

CreateLetterRequest is the object for creating a new letter

type CustomEnvelope 

type CustomEnvelope struct {
	ID     string `json:"id"`
	URL    string `json:"url"`
	Object string `json:"object"` //value should always be "envelope"
}

CustomEnvelope represents a custom envelope in lob's system

type Error 

type Error struct {
	Message    string `json:"message,omitempty"`
	StatusCode int    `json:"status_code,omitempty"`
}

type Letter 

type Letter struct {
	Error                *Error                 `json:"error"`
	ID                   string                 `json:"id"`
	Description          *string                `json:"description"`
	Metadata             map[string]string      `json:"metadata"`
	To                   *Address               `json:"to"`
	From                 *Address               `json:"from"`
	Color                bool                   `json:"color"`
	DoubleSided          bool                   `json:"double_sided"`
	AddressPlacement     LetterAddressPlacement `json:"address_placement"`
	ReturnEnvelope       bool                   `json:"return_envelope"`
	PerforatedPage       *uint64                `json:"perforated_page"`
	CustomEnvelope       *CustomEnvelope        `json:"custom_envelope"`
	ExtraService         *LetterExtraService    `json:"extra_service"`
	MailType             *string                `json:"mail_type"` //MailTypeUspsFirstClass or MailTypeUspsStandard
	URL                  string                 `json:"url"`
	MergeVariables       map[string]string      `json:"merge_variables"`
	TemplateID           *string                `json:"template_id"`
	TemplateVersionID    *string                `json:"template_version_id"`
	Carrier              string                 `json:"carrier"` //value is USPS
	TrackingNumber       *string                `json:"tracking_number"`
	TrackingEvents       []TrackingEvent        `json:"tracking_events"`
	Thumbnails           []LetterThumbnail      `json:"thumbnails"`
	ExpectedDeliveryDate string                 `json:"expected_delivery_date"`
	DateCreated          time.Time              `json:"date_created"`
	DateModified         time.Time              `json:"date_modified"`
	SendDate             time.Time              `json:"send_date"`
	Deleted              bool                   `json:"deleted"`
	Object               string                 `json:"object"` //value will always be letter
}

Letter represents a letter in lob's system

type LetterAddressPlacement 

type LetterAddressPlacement string

LetterAddressPlacement represents where the address should be placed on the letter 

var (
	//LetterAddressPlacementTopFirstPage is for being printed at the top of the first page
	LetterAddressPlacementTopFirstPage LetterAddressPlacement = "top_first_page"
	//LetterAddressPlacementInsertBlankPage is for inserting a blank page (does cost extra)
	LetterAddressPlacementInsertBlankPage LetterAddressPlacement = "insert_blank_page"
)

type LetterExtraService 

type LetterExtraService string

LetterExtraService represents the type of extra service requested 

var (
	//LetterExtraServiceCertified is for certified mail
	LetterExtraServiceCertified LetterExtraService = "certified"
	//LetterExtraServiceCertifiedReturnReceipt is for certified mail with return receipt
	LetterExtraServiceCertifiedReturnReceipt LetterExtraService = "certified_return_receipt"
	//LetterExtraServiceRegistered is for registered mail
	LetterExtraServiceRegistered LetterExtraService = "registered"
)

type LetterThumbnail 

type LetterThumbnail struct {
	Small  string `json:"small"`
	Medium string `json:"medium"`
	Large  string `json:"large"`
}

LetterThumbnail represents the thumbnails of the generated letter

type ListAddressesResponse 

type ListAddressesResponse struct {
	Data        []Address `json:"data"`
	Object      string    `json:"object"`
	NextURL     string    `json:"next_url"`
	PreviousURL string    `json:"previous_url"`
	Count       int       `json:"count"`
}

ListAddressesResponse gives the results for listing all addresses for our account.

type ListBankAccountsResponse 

type ListBankAccountsResponse struct {
	Data        []BankAccount `json:"data"`
	Object      string        `json:"object"`
	NextURL     string        `json:"next_url"`
	PreviousURL string        `json:"previous_url"`
	Count       int           `json:"count"`
}

ListBankAccountsResponse gives the results for listing all addresses for our account.

type ListChecksResponse 

type ListChecksResponse struct {
	Data        []Check `json:"data"`
	Object      string  `json:"object"`
	NextURL     string  `json:"next_url"`
	PreviousURL string  `json:"previous_url"`
	Count       int     `json:"count"`
}

ListChecksResponse details all of the checks we've ever mailed and printed.

type ListLettersResponse 

type ListLettersResponse struct {
	Data        []Letter `json:"data"`
	Object      string   `json:"object"` //value will always be letter
	NextURL     string   `json:"next_url"`
	PreviousURL string   `json:"previous_url"`
	Count       int      `json:"count"`
}

ListLettersResponse details all of the letters we've ever mailed and printed

type Lob 

type Lob interface {
	// Checks
	CreateCheck(*CreateCheckRequest) (*Check, error)
	GetCheck(string) (*Check, error)
	CancelCheck(string) (*CancelCheckResponse, error)
	ListChecks(int) (*ListChecksResponse, error)
	// Addresses
	CreateAddress(*Address) (*Address, error)
	GetAddress(string) (*Address, error)
	DeleteAddress(string) error
	ListAddresses(int) (*ListAddressesResponse, error)
	VerifyUSAddress(*Address) (*USAddressVerificationResponse, error)
	VerifyUSAddressWithCasing(*Address, AddressVerificationRequestCasing) (*USAddressVerificationResponse, error)
	// NamedObject
	GetStates() (*NamedObjectList, error)
	GetCountries() (*NamedObjectList, error)
	// Bank Accounts
	CreateBankAccount(*CreateBankAccountRequest) (*BankAccount, error)
	GetBankAccount(string) (*BankAccount, error)
	ListBankAccounts(int) (*ListBankAccountsResponse, error)
	// Letters
	CreateLetter(CreateLetterRequest) (*Letter, error)
	GetLetter(string) (*Letter, error)
	ListLetters(int) (*ListLettersResponse, error)
	CancelLetter(string) (*CancelLetterResponse, error)
}

type NamedObject 

type NamedObject struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	ShortName string `json:"short_name"`
	Object    string `json:"object"`
}

NamedObject is a datum that contains a name and short name for a state or country.

type NamedObjectList 

type NamedObjectList struct {
	Object string        `json:"object"`
	Data   []NamedObject `json:"data"`
}

NamedObjectList is used to return the list of countries and states.

type Tracking 

type Tracking struct {
	Carrier        string          `json:"carrier"`
	Events         []TrackingEvent `json:"events"`
	ID             string          `json:"id"`
	Link           *string         `json:"link"`
	Object         string          `json:"object"`
	TrackingNumber string          `json:"tracking_number"`
}

Tracking provides information on shipment tracking for a check.

type TrackingEvent 

type TrackingEvent struct {
	ID           string                `json:"id"`
	Type         TrackingEventType     `json:"type"`
	Name         TrackingEventName     `json:"name"`
	Details      *TrackingEventDetails `json:"details"`
	Location     *string               `json:"location"`
	Time         time.Time             `json:"time"`
	DateCreated  time.Time             `json:"date_created"`
	DateModified time.Time             `json:"date_modified"`
	Object       string                `json:"object"` //value will be tracking_event
}

TrackingEvent represents an event from the tracking

type TrackingEventDetails 

type TrackingEventDetails struct {
	Event          string `json:"event"`
	Description    string `json:"description"`
	Notes          string `json:"notes"`
	ActionRequired bool   `json:"action_required"`
}

TrackingEventDetails is for the details of a tracking event, only happens for certified mail

type TrackingEventName 

type TrackingEventName string

TrackingEventName is a special type for event names 

var (
	TrackingEventNameMailed               TrackingEventName = "Mailed"
	TrackingEventNameInTransit            TrackingEventName = "In Transit"
	TrackingEventNameInLocalArea          TrackingEventName = "In Local Area"
	TrackingEventNameProcessedForDelivery TrackingEventName = "Processed for Delivery"
	TrackingEventNameReRouted             TrackingEventName = "Re-Routed"
	TrackingEventNameReturnedToSender     TrackingEventName = "Returned to Sender"
	TrackingEventNamePickupAvailable      TrackingEventName = "Pickup Available"
	TrackingEventNameDelivered            TrackingEventName = "Delivered"
	TrackingEventNameIssue                TrackingEventName = "Issue"
)

list of event names

type TrackingEventType 

type TrackingEventType string

TrackingEventType indicates the type of event 

var (
	//TrackingEventTypeCertified is for certified mail; has the details property on the event
	TrackingEventTypeCertified TrackingEventType = "certified"
	//TrackingEventTypeNormal is for normal non-certified postcards, letters, and checks
	TrackingEventTypeNormal TrackingEventType = "normal"
)

type USAddressComponents 

type USAddressComponents struct {
	PrimaryNumber             string  `json:"primary_number"`
	StreetPredirection        string  `json:"street_predirection"`
	StreetName                string  `json:"street_name"`
	StreetSuffix              string  `json:"street_suffix"`
	StreetPostdirection       string  `json:"street_postdirection"`
	SecondaryDesignator       string  `json:"secondary_designator"`
	SecondaryNumber           string  `json:"secondary_number"`
	PmbDesignator             string  `json:"pmb_designator"`
	PmbNumber                 string  `json:"pmb_number"`
	ExtraSecondary_designator string  `json:"extra_secondary_designator"`
	ExtraSecondary_number     string  `json:"extra_secondary_number"`
	City                      string  `json:"city"`
	State                     string  `json:"state"`
	ZipCode                   string  `json:"zip_code"`
	ZipCodePlus_4             string  `json:"zip_code_plus_4"`
	ZipCodeType               string  `json:"zip_code_type"`
	DeliveryPoint_barcode     string  `json:"delivery_point_barcode"`
	AddressType               string  `json:"address_type"`
	RecordType                string  `json:"record_type"`
	DefaultBuildingAddress    bool    `json:"default_building_address"`
	County                    string  `json:"county"`
	CountyFips                string  `json:"county_fips"`
	CarrierRoute              string  `json:"carrier_route"`
	CarrierRouteType          string  `json:"carrier_route_type"`
	Latitude                  float64 `json:"latitude"`
	Longitude                 float64 `json:"longitude"`
}

USAddressComponents are the components which make up a US address

type USAddressDeliverabilityAnalysis 

type USAddressDeliverabilityAnalysis struct {
	DpvConfirmation string   `json:"dpv_confirmation"`
	DpvCmra         string   `json:"dpv_cmra"`
	DpvVacant       string   `json:"dpv_vacant"`
	DpvFootnotes    []string `json:"dpv_footnotes"`
	EwsMatch        bool     `json:"ews_match"`
	LacsIndicator   string   `json:"lacs_indicator"`
	LacsReturnCode  string   `json:"lacs_return_code"`
	SuiteReturnCode string   `json:"suite_return_code"`
}

type USAddressVerificationDeliverability 

type USAddressVerificationDeliverability string

USAddressVerificationDeliverability is the type for the deliverability of an address verified 

var (
	USAddressVerificationDeliverabilityDeliverable     USAddressVerificationDeliverability = "deliverable"
	USAddressVerificationDeliverabilityUnnecessaryUnit USAddressVerificationDeliverability = "deliverable_unnecessary_unit"
	USAddressVerificationDeliverabilityIncorrectUnit   USAddressVerificationDeliverability = "deliverable_incorrect_unit"
	USAddressVerificationDeliverabilitydMissingUnit    USAddressVerificationDeliverability = "deliverable_missing_unit"
	USAddressVerificationDeliverabilityUndeliverable   USAddressVerificationDeliverability = "undeliverable"
)

list of USAddressVerificationDeliverability values

type USAddressVerificationRequest 

type USAddressVerificationRequest struct {
	Recipient    *string `json:"recipient"`
	AddressLine1 *string `json:"primary_line"`
	AddressLine2 *string `json:"secondary_line"`
	AddressCity  *string `json:"city"`
	AddressState *string `json:"state"`
	AddressZip   *string `json:"zip_code"`
}

AddressVerificationRequest validates the given subset of info from an address.

type USAddressVerificationResponse 

type USAddressVerificationResponse struct {
	Id                     string                              `json:"id"`
	Recipient              string                              `json:"recipient"`
	PrimaryLine            string                              `json:"primary_line"`
	SecondaryLine          string                              `json:"secondary_line"`
	Urbanization           string                              `json:"urbanization,omitempty"`
	LastLine               string                              `json:"last_line"`
	Deliverability         USAddressVerificationDeliverability `json:"deliverability"`
	Components             USAddressComponents                 `json:"components"`
	DeliverabilityAnalysis USAddressDeliverabilityAnalysis     `json:"deliverability_analysis"`
	Object                 string                              `json:"object"`
}

USAddressVerificationResponse gives the response from attempting to verify a US address.

type WebhookEvent 

type WebhookEvent struct {
	ID          string           `json:"id"`
	Body        json.RawMessage  `json:"body"`
	ReferenceID string           `json:"reference_id"`
	EventType   WebhookEventType `json:"event_type"`
	DateCreated time.Time        `json:"date_created"`
	Object      string           `json:"object"`
}

WebhookEvent represents a webhook event

func ConstructWebhookEvent 

func ConstructWebhookEvent(payload []byte, timestampHeader, signatureHeader, secret string, tolerance time.Duration) (WebhookEvent, error)

ConstructWebhookEvent constructs a new webhook event and enforces the header signature

type WebhookEventType 

type WebhookEventType struct {
	ID             string `json:"id"`
	EnabledForTest bool   `json:"enabled_for_test"`
	Resource       string `json:"resource"`
	Object         string `json:"object"`
}

WebhookEventType represents the event type data for an event

Source Files

View all Source files

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.