cloudmailin

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Dec 31, 2021 License: MIT Imports: 12 Imported by: 0

README

CloudMailin Logo

CloudMailin Go Package

Go Reference Go Report Card

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client added in v0.2.0 

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 added in v0.2.0 

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 added in v0.2.0 

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 added in v0.2.0 

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 added in v0.1.0 

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)
}

Output:

func ParseIncomingBytes added in v0.1.0 

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 added in v0.1.0 

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 added in v0.2.0 

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 added in v0.2.0 

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 added in v0.2.0 

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 added in v0.2.0 

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"
)

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.