plunk

README

Plunk with Go

Go library for interacting with the Plunk API.

Features

The Plunk Go SDK includes the following features:

Transactional Emails: Use the SendTransactionalEmail method to send one or more emails to your subscribers.

Events: Trigger events and creates it if it doesn't exist. You can also delete events.

Contacts: Create, update, and delete contacts. You can also get a list of contacts, as well as the number of contacts in your account.

Easy integration: The Plunk Go SDK is easy to integrate into your Go applications, with a simple and intuitive API.

Getting started

To get started with the Plunk Go SDK, simply install it using the go get command:

go get github.com/kayode0x/plunk

Then, create a new Plunk object with your Plunk API key and start using the SDK to send and track emails.

Example Here's an example of how to use the Plunk Go SDK to send a simple email:

package main

import (
	"fmt"
	"github.com/kayode0x/plunk"
)

func main() {
	// create a new Plunk object with your API key
	p, _ := plunk.New("YOUR_API_KEY", nil)

    // optionally, you can set some configuration options.
    config := &plunk.Config{
        BaseUrl: "https://api.useplunk.com",
        Debug: true,
        Client: &http.Client{
            Timeout: 10 * time.Second,
        },
    }

    // create a new Plunk object with your API key and config
    p, err := plunk.New("YOUR_API_KEY", config)
    if err != nil {
        fmt.Printf("Error creating Plunk object: %v", err)
        return
    }

	// create a new email payload
	payload := TransactionalEmailPayload{
		To:      "test@example.com",
		Subject: "Test Subject",
		Body:    "Test Body",
	}

	// send the email
	response, err := plunk.SendTransactionalEmail(payload)
	if err != nil {
		fmt.Printf("Error sending email: %v", err)
		return
	}

	fmt.Printf("Email sent: %v", response)
}

Roadmap

• Send transactional emails

• Trigger events

• CRUD contacts

• Get contacts, and number of contacts.

• Your awesome feature 😉

See the open issues for a full list of proposed features (and known issues).

Contributing

Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

1. Fork the Project

2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

3. Commit your Changes (git commit -m 'Add some AmazingFeature')

4. Push to the Branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

Testing

To run tests, you need a Plunk API key. You can get one by signing up for a free account at https://useplunk.com.

Add the environment variable PLUNK_SECRET_KEY in your .env file with your Plunk API key.

Then, run the tests using the following command:

go test -v

If you receive an error that says contact already exists, you can manually delete the contact from your Plunk account, and then run the tests again.

Support

Ping me here, or feel free to reach out on twitter @kayode0x. For Plunk specific issues, please reach out to Plunk.

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Documentation

Index

• Variables
• type Config
• type Contact
  • func (r *Contact) ParseData() error
• type ContactInfo
• type ContactsCountResponse
• type CreateContactPayload
• type CustomError
  • func (e *CustomError) Error() string
• type EmailRecipient
• type Event
• type EventPayload
• type EventResponse
• type Plunk
  • func New(apiKey string, c *Config) (*Plunk, error)
  • func NewFromEnv() (*Plunk, error)
  • func (p *Plunk) CreateContact(payload CreateContactPayload) (*Contact, error)
  • func (p *Plunk) DeleteContact(id string) (*Contact, error)
  • func (p *Plunk) DeleteEvent(id string) (*Event, error)
  • func (p *Plunk) GetContact(id string) (*Contact, error)
  • func (p *Plunk) GetContacts() ([]*Contact, error)
  • func (p *Plunk) GetContactsCount() (int, error)
  • func (p *Plunk) SendMultipleTransactionalEmails(payload []TransactionalEmailPayload) ([]*TransactionalEmailResponse, error)
  • func (p *Plunk) SendTransactionalEmail(payload TransactionalEmailPayload) (*TransactionalEmailResponse, error)
  • func (p *Plunk) SubscribeContact(id string) (*Contact, error)
  • func (p *Plunk) TriggerEvent(payload EventPayload) (*EventResponse, error)
  • func (p *Plunk) UnsubscribeContact(id string) (*Contact, error)
  • func (p *Plunk) UpdateContact(c *Contact) (*Contact, error)
• type Request
• type SendConfig
• type TransactionalEmailPayload
• type TransactionalEmailResponse

Variables

var (
	ErrMissingContactID           = errors.New("missing contact id")
	ErrCouldNotCreateContact      = errors.New("could not create contact")
	ErrCouldNotGetContact         = errors.New("could not get contact")
	ErrCouldNotGetContacts        = errors.New("could not get contacts")
	ErrCouldNotGetCount           = errors.New("could not get count")
	ErrCouldNotSubscribeContact   = errors.New("could not subscribe contact")
	ErrCouldNotUnsubscribeContact = errors.New("could not unsubscribe contact")
	ErrCouldNotDeleteContact      = errors.New("could not delete contact")
	ErrCouldNotUpdateContact      = errors.New("could not update contact")
)

var (
	ErrMissingEvent        = errors.New("missing event")
	ErrMissingEmail        = errors.New("missing email")
	ErrMissingEventID      = errors.New("missing event id")
	ErrCouldNotDeleteEvent = errors.New("could not delete event")
)

var (
	ErrEmptyResponse  = errors.New("empty response")
	ErrMissingTo      = errors.New("missing recipient")
	ErrMissingSubject = errors.New("missing subject")
	ErrMissingBody    = errors.New("missing body or html")
)

var (
	ErrNoAPIKey = errors.New("no API key provided")
)

Types

type Config

type Config struct {
	ApiKey  string
	Client  *http.Client
	BaseUrl string
	Debug   bool
}

type Contact

type Contact struct {
	ID         string                 `json:"id"`
	Email      string                 `json:"email"`
	Subscribed bool                   `json:"subscribed"`
	DataString *string                `json:"data"`
	Data       map[string]interface{} `json:"-"`
}

func (*Contact) ParseData

func (r *Contact) ParseData() error

type ContactInfo

type ContactInfo struct {
	ID    string `json:"id"`
	Email string `json:"email"`
}

type ContactsCountResponse

type ContactsCountResponse struct {
	Count int `json:"count"`
}

type CreateContactPayload

type CreateContactPayload struct {
	Email      string                 `json:"email"`
	Subscribed bool                   `json:"subscribed"`
	Data       map[string]interface{} `json:"data"`
}

type CustomError

type CustomError struct {
	Code    int    `json:"code"`
	Type    string `json:"error"`
	Message string `json:"message"`
	Time    int64  `json:"time"`
}

Define a struct to represent the JSON error data

func (*CustomError) Error

func (e *CustomError) Error() string

type EmailRecipient

type EmailRecipient struct {
	Contact ContactInfo `json:"contact"`
	Email   string      `json:"email"`
}

type Event

type Event struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	CreatedAt  string `json:"createdAt"`
	UpdatedAt  string `json:"updatedAt"`
	ProjectID  string `json:"projectId"`
	CampaignID string `json:"campaignId"`
	TemplateID string `json:"templateId"`
}

type EventPayload

type EventPayload struct {
	Event      string         `json:"event"`
	Email      string         `json:"email"`
	Data       map[string]any `json:"data"`       // See: https://docs.useplunk.com/guides/linking-data-to-contacts#linking-data-on-event-triggers
	Subscribed bool           `json:"subscribed"` // When you trigger an event for a contact, they will automatically be subscribed unless you pass subscribed: false along with the event.
}

type EventResponse

type EventResponse struct {
	Success bool   `json:"success"`
	Contact string `json:"contact"` // the ID of the contact that was triggered
	Event   string `json:"event"`   // the ID of the event that was triggered
}

type Plunk

type Plunk struct {
	*Config
}

func New

func New(apiKey string, c *Config) (*Plunk, error)

New returns a new Plunk client.

func NewFromEnv

func NewFromEnv() (*Plunk, error)

NewFromEnv returns a new Plunk client using the PLUNK_API_KEY environment variable.

func (*Plunk) CreateContact

func (p *Plunk) CreateContact(payload CreateContactPayload) (*Contact, error)

Used to create a new contact in your Plunk project without triggering an event

func (*Plunk) DeleteContact

func (p *Plunk) DeleteContact(id string) (*Contact, error)

Delete a contact from your Plunk project.

func (*Plunk) DeleteEvent

func (p *Plunk) DeleteEvent(id string) (*Event, error)

Deletes an event.

func (*Plunk) GetContact

func (p *Plunk) GetContact(id string) (*Contact, error)

Gets the details of a specific contact.

func (*Plunk) GetContacts

func (p *Plunk) GetContacts() ([]*Contact, error)

Get a list of all contacts in your Plunk account.

func (*Plunk) GetContactsCount

func (p *Plunk) GetContactsCount() (int, error)

Gets the total number of contacts in your Plunk account. Useful for displaying the number of contacts in a dashboard, landing page or other marketing material.

func (*Plunk) SendMultipleTransactionalEmails

func (p *Plunk) SendMultipleTransactionalEmails(payload []TransactionalEmailPayload) ([]*TransactionalEmailResponse, error)

func (*Plunk) SendTransactionalEmail

func (p *Plunk) SendTransactionalEmail(payload TransactionalEmailPayload) (*TransactionalEmailResponse, error)

Used to send transactional emails to a single recipient or multiple recipients at once. Transactional emails are programmatically sent emails that are considered to be part of your application's workflow. This could be a password reset email, a billing email or other non-marketing emails.

Using Markdown

It is possible to use Markdown when sending a transactional email. Plunk will automatically apply the same styling as the email templates you make in the editor. Any email with a body that starts with # will be treated as Markdown.

func (*Plunk) SubscribeContact

func (p *Plunk) SubscribeContact(id string) (*Contact, error)

Updates a contact's subscription status to subscribed.

func (*Plunk) TriggerEvent

func (p *Plunk) TriggerEvent(payload EventPayload) (*EventResponse, error)

Triggers an event and creates it if it doesn't exist.

func (*Plunk) UnsubscribeContact

func (p *Plunk) UnsubscribeContact(id string) (*Contact, error)

Updates a contact's subscription status to unsubscribed.

func (*Plunk) UpdateContact

func (p *Plunk) UpdateContact(c *Contact) (*Contact, error)

Update a contact in your Plunk project.

type Request

type Request struct {
	Url     string
	Headers map[string]string
}

type SendConfig

type SendConfig struct {
	Url    string
	Method string
	Body   interface{}
}

type TransactionalEmailPayload

type TransactionalEmailPayload struct {
	To       string         `json:"to"`
	Subject  string         `json:"subject,omitempty"`
	Body     string         `json:"body,omitempty"`
	From     string         `json:"from,omitempty"`
	Name     string         `json:"name,omitempty"`
	Template string         `json:"template,omitempty"`
	Data     map[string]any `json:"data,omitempty"`
}

type TransactionalEmailResponse

type TransactionalEmailResponse struct {
	Success   bool             `json:"success"`
	Emails    []EmailRecipient `json:"emails"`
	Timestamp string           `json:"timestamp"`
}