cloudmailin

README

CloudMailin Go Package

A Go SDK for CloudMailin incoming and outbound email via JSON HTTP POST.

Please see the Documentation for more details and examples.

Usage

Installation

You can install the package using:

go get -u github.com/cloudmailin/cloudmailin-go

Receiving Email

We recommend you take a look at our Documentation for a more detailed example but here's a snippet:

import (
	"fmt"
	"net/http"

	"github.com/cloudmailin/cloudmailin-go"
)

func handleIncomingPOST(w http.ResponseWriter, req *http.Request) {
	// Parse the message from the request body
	message, err := cloudmailin.ParseIncoming(req.Body)
	if err != nil {
		// Print an error message if parsing fails
		fmt.Fprint(w, "Error parsing message: ", err)
	}

	// Output the first instance of the message-id in the headers to show
	// that we correctly parsed the message. We could also use the helper
	// message.Headers.MessageID().
	fmt.Fprint(w, "Thanks for message: ", message.Headers.First("message_id"))
}

// This example shows how to parse the incoming JSON sent by Cloudmailin
// and create an instance of the IncomingMail type.
func main() {
	http.HandleFunc("/", handleIncomingPOST)

	// Start the HTTP server to listen for HTTP POST
	http.ListenAndServe(":8080", nil)
}

Sending Email

We recommend you take a look at our Documentation for a more detailed example:

package main

import (
	"fmt"

	"github.com/cloudmailin/cloudmailin-go"
)

func main() {
	// Create the default CloudMailin Client. This example will
	// panic if there are any failures at all.
	client, err := cloudmailin.NewClient()
	if err != nil {
			panic(err)
	}

// SMTP Settings will be taken from CLOUDMAILIN_SMTP_URL env variable by
// default but they can be overridden.
// client.SMTPAccountID = ""
// client.SMTPToken = ""

	// Create an instance of cloudmailin.OutboundMailAttachment
	attachment, err := cloudmailin.AttachmentFromFile("./logo.png")
	if err != nil {
		panic(err)
	}

// Generate an example email
message := cloudmailin.OutboundMail{
		From:     "sender@example.com",
		To:       []string{"debug@example.net"},
		CC:       []string{"carbon@example.net"},
		Headers:  map[string][]string{"x-agent": {"cloudmailin-go"}},
		Subject:  "Hello From Go",
		Plain:    "Hello World",
		HTML:     "<h1>Hello!</h1>\nWorld",
		Priority: "",
		Tags:     []string{"go"},
		Attachments: []cloudmailin.OutboundMailAttachment{attachment},
		TestMode: true,
}

// This will re-write the message struct based on the
// JSON returned from the call if successful.
_, err = client.SendMail(&message)
if err != nil {
		panic(err)
}

// The message.ID should now be populated
fmt.Printf("ID: %t, Tags: %s", message.ID != "", message.Tags)
}

Development

Although we experimented with code generators none of them provided the experience that we desired.

This code was built inside a docker container in VSCode. Contact us if you would like to make use of any of those tools.

Documentation

Index

• type Client
  • func NewClient() (client Client, err error)
  • func (client Client) Do(method string, path string, body interface{}, kind RequestType) (res *http.Response, err error)
  • func (client Client) SendMail(message *OutboundMail) (res *http.Response, err error)
• type IncomingMail
  • func ParseIncoming(data io.Reader) (mail IncomingMail, err error)
  • func ParseIncomingBytes(data []byte) (mail IncomingMail, err error)
• type IncomingMailAttachment
• type IncomingMailAttachmentScan
• type IncomingMailEnvelope
• type IncomingMailEnvelopeSPAMD
• type IncomingMailEnvelopeSPF
• type IncomingMailHeader
  • func (i IncomingMailHeader) First() string
  • func (i IncomingMailHeader) Last() string
  • func (i *IncomingMailHeader) UnmarshalJSON(b []byte) error
• type IncomingMailHeaders
  • func (i IncomingMailHeaders) Find(key string) IncomingMailHeader
  • func (i IncomingMailHeaders) First(key string) string
  • func (i IncomingMailHeaders) From() string
  • func (i IncomingMailHeaders) Last(key string) string
  • func (i IncomingMailHeaders) MessageID() string
  • func (i IncomingMailHeaders) Subject() string
  • func (i IncomingMailHeaders) To() string
• type OutboundMail
• type OutboundMailAttachment
  • func AttachmentFromFile(filepath string) (att OutboundMailAttachment, err error)
• type RequestType

Examples

• Client.SendMail
• ParseIncoming

Types

type Client

type Client struct {
	HTTPClient    http.Client
	BaseURL       string
	SMTPToken     string
	SMTPAccountID string

	// For future use with the API
	AccountID    string
	AccountToken string
}

Client is the base of an API Client for CloudMailin. It provides a struct to put credentials, base URL and the HTTP Client.

func NewClient

func NewClient() (client Client, err error)

NewClient returns an instance of the DefaultClient. DefaultClient assumes that the ENV variable CLOUDMAILIN_SMTP_URL is set containing the SMTP credentials and sets the BaseURL to CLOUDMAILIN_API_BASE_URL if present.

If these are not set create a client instance manually and set the required credentials.

func (Client) Do

func (client Client) Do(method string, path string, body interface{}, kind RequestType) (
	res *http.Response, err error)

Do Performs the HTTP request with SMTP or Account credentials, SMTP credentials work in a really similar way to normal API credentials but use the SMTP Server ID instead of the AccountID and the SMTP Password as the Authorization Bearer Token.

func (Client) SendMail

func (client Client) SendMail(message *OutboundMail) (res *http.Response, err error)

SendMail will make a POST to send the OutboundMail email via the HTTP API.

Example

// Create the default CloudMailin Client. This example will
// panic if there are any failures at all.
client, err := cloudmailin.NewClient()
if err != nil {
	panic(err)
}

// SMTP Settings will be taken from CLOUDMAILIN_SMTP_URL env variable by
// default but they can be overridden.
// client.SMTPAccountID = ""
// client.SMTPToken = ""

// Create an instance of cloudmailin.OutboundMailAttachment
attachment, err := cloudmailin.AttachmentFromFile("./test/fixtures/pixel.png")
if err != nil {
	panic(err)
}

// Generate an example email
message := cloudmailin.OutboundMail{
	From:        "sender@example.com",
	To:          []string{"debug@example.net"},
	CC:          []string{"carbon@example.net"},
	Headers:     map[string][]string{"x-agent": {"cloudmailin-go"}},
	Subject:     "Hello From Go",
	Plain:       "Hello World",
	HTML:        "<h1>Hello!</h1>\nWorld",
	Priority:    "",
	Tags:        []string{"go"},
	Attachments: []cloudmailin.OutboundMailAttachment{attachment},
	TestMode:    true,
}

// This will re-write the message struct based on the
// JSON returned from the call if successful.
_, err = client.SendMail(&message)
if err != nil {
	panic(err)
}

// The message.ID should now be populated
fmt.Printf("ID: %t, Tags: %s", message.ID != "", message.Tags)

Output:

ID: true, Tags: [go api]

type IncomingMail

type IncomingMail struct {
	Envelope    IncomingMailEnvelope     `json:"envelope"`
	Headers     IncomingMailHeaders      `json:"headers"`
	Plain       string                   `json:"plain"`
	HTML        string                   `json:"html"`
	ReplyPlain  string                   `json:"reply_plain"`
	Attachments []IncomingMailAttachment `json:"attachments"`
}

IncomingMail represents an email received via HTTP from the CloudMailin email to Webhook.

func ParseIncoming

func ParseIncoming(data io.Reader) (mail IncomingMail, err error)

ParseIncoming parses an IO reader and emits an IncomingMail. This is most useful to parse the http.Request.Body.

Example

This example shows how to parse the incoming JSON sent by Cloudmailin and create an instance of the IncomingMail type.

package main

import (
	"fmt"
	"net/http"

	"github.com/cloudmailin/cloudmailin-go"
)

func handleIncomingPOST(w http.ResponseWriter, req *http.Request) {
	// Parse the message from the request body
	message, err := cloudmailin.ParseIncoming(req.Body)
	if err != nil {
		// Print an error message if parsing fails
		fmt.Fprint(w, "Error parsing message: ", err)
	}

	// Output the first instance of the message-id in the headers to show
	// that we correctly parsed the message. We could also use the helper
	// message.Headers.MessageID().
	fmt.Fprint(w, "Thanks for message: ", message.Headers.First("message_id"))
}

// This example shows how to parse the incoming JSON sent by Cloudmailin
// and create an instance of the IncomingMail type.
func main() {
	http.HandleFunc("/", handleIncomingPOST)

	// Start the HTTP server to listen for HTTP POST
	http.ListenAndServe(":8080", nil)
}

func ParseIncomingBytes

func ParseIncomingBytes(data []byte) (mail IncomingMail, err error)

ParseIncomingBytes parses a []byte and returns an IncomingMail.

type IncomingMailAttachment

type IncomingMailAttachment struct {
	// Base64 encoded string containing the attachment content
	Content     string `json:"content"`
	FileName    string `json:"file_name"`
	ContentType string `json:"content_type"`
	Size        uint64 `json:"size,string"`
	Disposition string
	ContentID   string `json:"content_id"`
	URL         string
	Scan        IncomingMailAttachmentScan
}

IncomingMailAttachment represents email attachments.

type IncomingMailAttachmentScan

type IncomingMailAttachmentScan struct {
	Status  string
	ID      string
	Matches []string
}

IncomingMailAttachmentScan represents the result of virus scanning the email attachments (if enabled).

type IncomingMailEnvelope

type IncomingMailEnvelope struct {
	To         string                    `json:"to"`
	From       string                    `json:"from"`
	Recipients []string                  `json:"recipients"`
	HeloDomain string                    `json:"helo_domain"`
	RemoteIP   string                    `json:"remote_ip"`
	TLS        bool                      `json:"tls"`
	TLSCipher  string                    `json:"tls_cipher"`
	MD5        string                    `json:"md5"`
	StoreURL   string                    `json:"store_url"`
	SPF        IncomingMailEnvelopeSPF   `json:"spf"`
	SPAMD      IncomingMailEnvelopeSPAMD `json:"spamd,omitempty"`
}

IncomingMailEnvelope represents the CloudMailin Email Envelope containing information passed to the SMTP server.

type IncomingMailEnvelopeSPAMD

type IncomingMailEnvelopeSPAMD struct {
	Score       uint     `json:"score,string"`
	Symbols     []string `json:"symbols"`
	Success     bool     `json:"success"`
	Description string   `json:"description"`
}

IncomingMailEnvelopeSPAMD contains the result of the SpamAssassin scan of the email (if enabled).

type IncomingMailEnvelopeSPF

type IncomingMailEnvelopeSPF struct {
	Result string `json:"result"`
	Domain string `json:"domain"`
}

IncomingMailEnvelopeSPF contains the SPF result and domain for the Envelope.

type IncomingMailHeader

type IncomingMailHeader []string

IncomingMailHeader contains a single header value. This is an array because each header can be received more than once.

func (IncomingMailHeader) First

func (i IncomingMailHeader) First() string

First will return the occurrence of this header appearing at the Bottom of the headers i.e. the first header value.

func (IncomingMailHeader) Last

func (i IncomingMailHeader) Last() string

Last will return the occurrence of this header appearing at the Top of the headers i.e. the most recent header value.

func (*IncomingMailHeader) UnmarshalJSON

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

UnmarshalJSON takes the CloudMailin JSON format and handles the parsing into the struct. It ensures that every response is an array of strings.

type IncomingMailHeaders

type IncomingMailHeaders map[string]IncomingMailHeader

IncomingMailHeaders contains the received email headers.

func (IncomingMailHeaders) Find

func (i IncomingMailHeaders) Find(key string) IncomingMailHeader

Find will return a header by it's name Email headers are ordered bottom up so they will be top first in this array.

func (IncomingMailHeaders) First

func (i IncomingMailHeaders) First(key string) string

First will return the first entry for a header by it's name.

func (IncomingMailHeaders) From

func (i IncomingMailHeaders) From() string

From is a helper function to find the From Header.

func (IncomingMailHeaders) Last

func (i IncomingMailHeaders) Last(key string) string

Last will find and return the most recent entry for a header by it's name.

func (IncomingMailHeaders) MessageID

func (i IncomingMailHeaders) MessageID() string

MessageID is a helper function to find the Message-ID Header.

func (IncomingMailHeaders) Subject

func (i IncomingMailHeaders) Subject() string

Subject is a helper function to find the Subject Header.

func (IncomingMailHeaders) To

func (i IncomingMailHeaders) To() string

To is a helper function to find the To Header.

type OutboundMail

type OutboundMail struct {
	From        string                   `json:"from"`
	To          []string                 `json:"to,omitempty"`
	CC          []string                 `json:"cc,omitempty"`
	Headers     map[string][]string      `json:"headers,omitempty"`
	Subject     string                   `json:"subject,omitempty"`
	Plain       string                   `json:"plain,omitempty"`
	HTML        string                   `json:"html,omitempty"`
	Priority    string                   `json:"priorty,omitempty"`
	Tags        []string                 `json:"tags,omitempty"`
	Attachments []OutboundMailAttachment `json:"attachments,omitempty"`
	TestMode    bool                     `json:"test_mode,omitempty"`

	ID string `json:"id,omitempty"`
}

OutboundMail represents an email message ready to be sent. The ID will be populated by the API call once the message has been sent.

type OutboundMailAttachment

type OutboundMailAttachment struct {
	// The Base64 encoded representation of the content.
	Content string `json:"content"`

	// An optional content id for the embedded attachment
	ContentID string `json:"content_id,omitempty"`

	// The mime content type of the file such as `image/jpeg`
	ContentType string `json:"content_type"`

	// The file name of the attachment
	FileName string `json:"file_name"`
}

OutboundMailAttachment represents the format of attachments to be sent in an OutboundMail. Content must be a Base64 encoded string.

func AttachmentFromFile

func AttachmentFromFile(filepath string) (att OutboundMailAttachment,
	err error)

AttachmentFromFile is a convenience function to prepare an OutboundMailAttachment from a local file (given as the filepath argument). The content will be Base64 encoded automatically and the filename included. This uses http.DetectContentType to guess the content type of the file.

type RequestType

type RequestType string

RequestType is used to differentiate between account and SMTP requests.

const (
	// RequestTypeAccount is used for account API calls
	// (currently not implemented).
	RequestTypeAccount RequestType = "account"

	// RequestTypeSMTP is used for SMTP related API calls.
	RequestTypeSMTP RequestType = "smtp"
)