klaviyo

README

Go Klaviyo

This is the Golang Klaviyo SDK built for Monstercat's purposes. It only includes the functionality which we need, but feel free to make a PR to include any extra functionality you need.

Some Notes

Klaviyo's HTTP API is very messy and has multiple versions thus we have done our best to keep it simple and work around it. Please read the source code to see examples of this.

Testing

You will need to use environment variables to test everything. Please read klaviyo_test.go for a list of them.

Contributing Notes

• You must have tests.
• Keep it simple.

Documentation

Index

• Constants
• Variables
• type APIError
  • func (e *APIError) Error() string
• type Attributes
  • func (a Attributes) ParseBool(key string) bool
• type BadResponseError
  • func (e *BadResponseError) Error() string
• type Client
  • func (c *Client) GetPerson(personId string) (*Person, error)
  • func (c *Client) Identify(person *Person) error
  • func (c *Client) IdentifySafe(person *Person, omit bool) error
  • func (c *Client) InList(listId string, emails, phoneNumbers, pushTokens []string) ([]ListPerson, error)
  • func (c *Client) Subscribe(listId string, emails, phoneNumbers []string) ([]ListPerson, error)
  • func (c *Client) Unsubscribe(listId string, emails, phoneNumbers, pushTokens []string) error
  • func (c *Client) UpdatePerson(person *Person) error
• type KFloat
  • func (f *KFloat) UnmarshalJSON(b []byte) error
• type KInt
  • func (i *KInt) UnmarshalJSON(b []byte) error
• type ListPerson
• type Object
• type Person
  • func (p *Person) GetMap() map[string]interface{}
  • func (p *Person) HasProfileIdentifier() bool
  • func (p *Person) MarshalJSON() ([]byte, error)
  • func (p *Person) UnmarshalJSON(data []byte) error

Constants

const (
	ConsentEmail  = "email"
	ConsentWeb    = "web"
	ConsentSMS    = "sms"
	ConsentDirect = "directmail"
	ConsentMobile = "mobile"

	// Use these instead of the MIME library because this is what is specified in their documentation.
	ContentNone     = ""
	ContentHTML     = "text/html"
	ContentHTMLUTF8 = "text/html; charset=utf-8"
	ContentJSON     = "application/json"

	// They have multiple endpoints unfortunately.
	Endpoint   = "https://a.klaviyo.com/api"
	EndpointV1 = "https://a.klaviyo.com/api/v1"
	EndpointV2 = "https://a.klaviyo.com/api/v2"
)

Variables

var (
	ErrNoPublicKey         = errors.New("missing public key")
	ErrNoPrivateKey        = errors.New("missing private key")
	ErrNoProfileIdentifier = errors.New("there is no unique profile identifier, must have email or phone number")
	ErrFailed              = errors.New("request successful, call failed")
	ErrInvalidOutArg       = errors.New("out arg provided does not match datatype of response")
)

Types

type APIError

type APIError struct {
	// Use this to store the raw error response if the response is not parseable.
	Raw string

	// Klaviyo's documentation details the usage of "message", but returns "detail" in some instances.
	Detail  string `json:"detail"`
	Message string `json:"message"`
}

func (*APIError) Error

func (e *APIError) Error() string

type Attributes

type Attributes map[string]interface{}

func (Attributes) ParseBool

func (a Attributes) ParseBool(key string) bool

type BadResponseError

type BadResponseError struct {
	Body      []byte
	JSONError error
}

func (*BadResponseError) Error

func (e *BadResponseError) Error() string

type Client

type Client struct {
	// Sometimes called "token"
	PublicKey string

	// Sometimes seen as "api_key"
	PrivateKey string

	// The amount of time an HTTP API call should run for before it times out.
	DefaultTimeout time.Duration
}

func (*Client) GetPerson

func (c *Client) GetPerson(personId string) (*Person, error)

https://apidocs.klaviyo.com/reference/profiles#get-profile GET https://a.klaviyo.com/api/v1/person/person_id

func (*Client) Identify

func (c *Client) Identify(person *Person) error

https://apidocs.klaviyo.com/reference/track-identify#identify GET https://a.klaviyo.com/api/identify TODO Update Identify to use POST method version as GET is outdated

func (*Client) IdentifySafe

func (c *Client) IdentifySafe(person *Person, omit bool) error

Use this if you do not want to send values that are not set. This is great for when you want to update a Person without first fetching their information. This will happen if you only have thier email and no Klaviyo Id to utilize.

func (*Client) InList

func (c *Client) InList(listId string, emails, phoneNumbers, pushTokens []string) ([]ListPerson, error)

https://apidocs.klaviyo.com/reference/lists-segments#list-membership GET https://a.klaviyo.com/api/v2/list/list_id/members

func (*Client) Subscribe

func (c *Client) Subscribe(listId string, emails, phoneNumbers []string) ([]ListPerson, error)

https://apidocs.klaviyo.com/reference/lists-segments#subscribe POST https://a.klaviyo.com/api/v2/list/list_id/subscribe

func (*Client) Unsubscribe

func (c *Client) Unsubscribe(listId string, emails, phoneNumbers, pushTokens []string) error

https://apidocs.klaviyo.com/reference/lists-segments#unsubscribe DELETE https://a.klaviyo.com/api/v2/list/list_id/subscribe

func (*Client) UpdatePerson

func (c *Client) UpdatePerson(person *Person) error

https://apidocs.klaviyo.com/reference/profiles#update-profile PUT https://a.klaviyo.com/api/v1/person/person_id Only works to update a persons attributes after they have been identified.

type KFloat

type KFloat float64

KFloat implements the UnmarshalJSON interface to do special processing for Klaviyo. In certain instances (such as when a number field is empty), klaviyo will return the value as a string. Otherwise, it will return the value as a number.

func (*KFloat) UnmarshalJSON

func (f *KFloat) UnmarshalJSON(b []byte) error

type KInt

type KInt int

KInt implements the UnmarshalJSON interface to do special processing for Klaviyo. In certain instances (such as when a number field is empty), klaviyo will return the value as a string. Otherwise, it will return the value as a number.

func (*KInt) UnmarshalJSON

func (i *KInt) UnmarshalJSON(b []byte) error

type ListPerson

type ListPerson struct {
	Id          string `json:"id"`
	Email       string `json:"email"`
	PhoneNumber string `json:"phone_number"`
	Created     string `json:"created"`
}

type Object

type Object struct {
	Id     string `json:"id"`
	Object string `json:"object"` // e.g. person, $list
}

All objects in Klaviyo use this basic structure to identify what kind of object it is and how to identify it.

type Person

type Person struct {
	Object

	// Below are special fields used by Klaviyo, they will be render in special UI for fancy-ness
	// they are identified by the $ prefix in their JSON.
	// Please read here for more: https://help.klaviyo.com/hc/en-us/articles/115005084927-Template-Tags-and-Variable-Syntax#klaviyo-special-properties18
	//
	// Any extra attributes appear in the same flat structure but we store them in Attributes below.
	CustomId     string   `json:"$id"`
	Address1     string   `json:"$address1"`
	Address2     string   `json:"$address2"`
	City         string   `json:"$city"`
	Consent      []string `json:"$consent"`
	Country      string   `json:"$country"`
	Email        string   `json:"$email"`
	FirstName    string   `json:"$first_name"`
	Image        string   `json:"$image"`
	LastName     string   `json:"$last_name"`
	Latitude     KFloat   `json:"$latitude"`
	Longitude    KFloat   `json:"$longitude"`
	Organization string   `json:"$organization"`
	PhoneNumber  string   `json:"$phone_number"`
	Region       string   `json:"$region"`
	Source       KInt     `json:"$source"`
	Timezone     string   `json:"$timezone"`
	Title        string   `json:"$title"`
	Zip          string   `json:"$zip"`

	// Use these to have custom attributes tied to a user that can be used to create segments for lists.
	Attributes Attributes
}

func (*Person) GetMap

func (p *Person) GetMap() map[string]interface{}

func (*Person) HasProfileIdentifier

func (p *Person) HasProfileIdentifier() bool

A profile identifier is an email or phone number. In the case of SMS they must have a phone number.

func (*Person) MarshalJSON

func (p *Person) MarshalJSON() ([]byte, error)

func (*Person) UnmarshalJSON

func (p *Person) UnmarshalJSON(data []byte) error