esendex

README

esendex

A client for the Esendex REST API.

$ go get github.com/esendex/esendex-go-sdk

Extremely simple example:

import (
    "github.com/esendex/esendex-go-sdk"
)

var (
    accountReference = "EX000000"
    username         = "user"
    password         = "pass"
)

func main() {
    client := esendex.New(username, password)

    accountClient := client.Account(accountReference)

    response, err := accountClient.Received()
    if err == nil {
        // response.Messages contains messages received by the account
    }
}

See the GoDocs for some further examples around sending messages, checking message status etc.

Documentation

Overview

Package esendex is a client for the Esendex REST API.

Example

package main

import (
	"log"
	"time"

	"github.com/esendex/esendex-go-sdk"
)

func sendMessage(c *esendex.Client, to, body string) (id string, err error) {
	account := c.Account("EX00000")

	messages, err := account.Send([]esendex.Message{
		{To: "4498499", Body: "Hey"},
	})

	if err != nil {
		return "", err
	}

	return messages.Messages[0].ID, nil
}

func getStatus(c *esendex.Client, id string) (status string, err error) {
	message, err := c.Message(id)
	if err != nil {
		return "", err
	}

	return message.Status, nil
}

func main() {
	client := esendex.New("user@example.com", "pass")

	messageID, err := sendMessage(client, "538734", "Hey")
	if err != nil {
		log.Fatal(err)
	}

	for i := range []int{0, 1, 2, 3, 4, 5} {
		status, err := getStatus(client, messageID)
		if err != nil {
			log.Fatal(err)
		}

		log.Printf("message status after %d seconds: %s\n", i, status)
		time.Sleep(time.Second)
	}
}

Index

• type AccountClient
  • func (c *AccountClient) Batches(opts ...Option) (*BatchesResponse, error)
  • func (c *AccountClient) Received(opts ...Option) (*ReceivedMessagesResponse, error)
  • func (c *AccountClient) Send(messages []Message) (*SendResponse, error)
  • func (c *AccountClient) SendAt(sendAt time.Time, messages []Message) (*SendResponse, error)
  • func (c *AccountClient) SendFrom(from string, messages []Message) (*SendResponse, error)
  • func (c *AccountClient) Sent(opts ...Option) (*SentMessagesResponse, error)
• type AccountResponse
• type AccountsResponse
• type BatchResponse
• type BatchesResponse
• type Client
  • func New(user, pass string) *Client
  • func (c *Client) Account(reference string) *AccountClient
  • func (c *Client) Accounts() (*AccountsResponse, error)
  • func (c *Client) Batch(id string) (*BatchResponse, error)
  • func (c *Client) Batches(opts ...Option) (*BatchesResponse, error)
  • func (c *Client) Body(message messageWithBody) (*MessageBody, error)
  • func (c *Client) CancelBatch(id string) error
  • func (c *Client) Message(id string) (*MessageResponse, error)
  • func (c *Client) Received(opts ...Option) (*ReceivedMessagesResponse, error)
  • func (c *Client) Sent(opts ...Option) (*SentMessagesResponse, error)
• type ClientError
  • func (e ClientError) Error() string
• type FailureReason
• type Message
• type MessageBody
• type MessageResponse
• type MessageType
• type Option
  • func Between(start, finish time.Time) Option
  • func Page(startIndex, count int) Option
• type Paging
• type ReceivedMessageResponse
• type ReceivedMessagesResponse
• type SendResponse
• type SendResponseMessage
• type SentMessageResponse
• type SentMessagesResponse

Examples

• Package
• AccountClient.Send
• Client.Body
• Client.Received
• Client.Sent

Types

type AccountClient

type AccountClient struct {
	*Client
	// contains filtered or unexported fields
}

AccountClient is a client scoped to a specific account reference.

func (*AccountClient) Batches

func (c *AccountClient) Batches(opts ...Option) (*BatchesResponse, error)

Batches returns a list of batches sent by the account.

func (*AccountClient) Received

func (c *AccountClient) Received(opts ...Option) (*ReceivedMessagesResponse, error)

Received returns the messages sent to the account.

func (*AccountClient) Send

func (c *AccountClient) Send(messages []Message) (*SendResponse, error)

Send dispatches a list of messages.

Example

accountClient := New("user@example.com", "pass").Account("EX00000")

accountClient.Send([]Message{
	{To: "00000000", Body: "Hello"},
})

func (*AccountClient) SendAt

func (c *AccountClient) SendAt(sendAt time.Time, messages []Message) (*SendResponse, error)

SendAt schedules a list of messages for dispatch.

func (*AccountClient) SendFrom

func (c *AccountClient) SendFrom(from string, messages []Message) (*SendResponse, error)

SendFrom dispatches a list of messages and overrides the default originator.

func (*AccountClient) Sent

func (c *AccountClient) Sent(opts ...Option) (*SentMessagesResponse, error)

Sent returns a list of messages sent by the account.

type AccountResponse

type AccountResponse struct {
	ID                string
	URI               string
	Reference         string
	Label             string
	Address           string
	Type              string
	MessagesRemaining int
	ExpiresOn         time.Time
	Role              string
	SettingsURI       string
}

AccountResponse is a single account.

type AccountsResponse

type AccountsResponse struct {
	Accounts []AccountResponse
}

AccountsResponse is a list of accounts.

type BatchResponse

type BatchResponse struct {
	ID                 string
	URI                string
	CreatedAt          time.Time
	BatchSize          int
	PersistedBatchSize int
	Status             map[string]int
	AccountReference   string
	CreatedBy          string
	Name               string
}

BatchResponse is a single sent batch.

type BatchesResponse

type BatchesResponse struct {
	Paging
	Batches []BatchResponse
}

BatchesResponse is a list of returned message batches along with the paging information.

type Client

type Client struct {
	BaseURL   *url.URL
	UserAgent string
	// contains filtered or unexported fields
}

Client is the entry point for accessing the Esendex REST API.

func New

func New(user, pass string) *Client

New returns a new API client that authenticates with the credentials provided.

func (*Client) Account

func (c *Client) Account(reference string) *AccountClient

Account creates a client that can make requests scoped to a specific account reference.

func (*Client) Accounts

func (c *Client) Accounts() (*AccountsResponse, error)

Accounts returns a list of accounts the user is on.

func (*Client) Batch

func (c *Client) Batch(id string) (*BatchResponse, error)

Batch returns the batch with the given id.

func (*Client) Batches

func (c *Client) Batches(opts ...Option) (*BatchesResponse, error)

Batches returns a list of batches sent by the authenticated user.

func (*Client) Body

func (c *Client) Body(message messageWithBody) (*MessageBody, error)

Body returns the full body of a single message.

Example

client := New("user@example.com", "pass")

message, err := client.Message("messageId")
if err != nil {
	log.Fatal(err)
}

body, err := client.Body(message)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("%s: %s", message.ID, body.Text)

func (*Client) CancelBatch

func (c *Client) CancelBatch(id string) error

CancelBatch prevents the messagebatch from being sent if it is scheduled and due to be sent at a point that allows it to be cancelled.

func (*Client) Message

func (c *Client) Message(id string) (*MessageResponse, error)

Message returns the message with the given id.

func (*Client) Received

func (c *Client) Received(opts ...Option) (*ReceivedMessagesResponse, error)

Received returns the messages sent to the user.

Example

client := New("user@example.com", "pass")

now := time.Now()

response, err := client.Received(Between(now.AddDate(0, -6, 0), now))
if err != nil {
	log.Fatal(err)
}

for _, message := range response.Messages {
	fmt.Printf("%v %s: %s\n", message.ReceivedAt, message.From, message.Summary)
}

func (*Client) Sent

func (c *Client) Sent(opts ...Option) (*SentMessagesResponse, error)

Sent returns a list of messages sent by the user.

Example

client := New("user@example.com", "pass")

response, err := client.Sent()
if err != nil {
	log.Fatal(err)
}

for _, message := range response.Messages {
	fmt.Printf("%v %s: %s\n", message.SubmittedAt, message.To, message.Summary)
}

type ClientError

type ClientError struct {
	Method string
	Path   string
	Code   int
}

ClientError is the type of error returned when an unexpected (non-200 range) response is returned by the API.

func (ClientError) Error

func (e ClientError) Error() string

type FailureReason

type FailureReason struct {
	Code        int
	Description string
	Permanent   bool
}

FailureReason gives detailed information for why a message failed to send.

type Message

type Message struct {
	To           string
	From         string
	MessageType  MessageType
	Lang         string
	Validity     int
	CharacterSet string
	Retries      int
	Body         string
}

Message is a message to send.

type MessageBody

type MessageBody struct {
	Text         string
	CharacterSet string
}

MessageBody is the body of a message.

type MessageResponse

type MessageResponse struct {
	ID            string
	URI           string
	Reference     string
	Status        string
	LastStatusAt  time.Time
	SubmittedAt   time.Time
	ReceivedAt    time.Time
	Type          MessageType
	To            string
	From          string
	Summary       string
	Direction     string
	ReadAt        time.Time
	SentAt        time.Time
	DeliveredAt   time.Time
	ReadBy        string
	Parts         int
	Username      string
	FailureReason *FailureReason
	BatchID       *string
	// contains filtered or unexported fields
}

MessageResponse is a single message. It implements messageWithBody.

BatchID might be nil, as inbound messages do not have a batch ID.

type MessageType

type MessageType string

const (
	SMS   MessageType = "SMS"
	Voice MessageType = "Voice"
)

type Option

type Option func(*http.Request)

Option is a function that mutates a request.

func Between

func Between(start, finish time.Time) Option

Between creates an option that sets the start and finish query parameters.

func Page

func Page(startIndex, count int) Option

Page creates an option that sets the startindex and count query parameters.

type Paging

type Paging struct {
	StartIndex int
	Count      int
	TotalCount int
}

Paging gives the details of the page that was accessed.

type ReceivedMessageResponse

type ReceivedMessageResponse struct {
	ID         string
	URI        string
	Reference  string
	Status     string
	ReceivedAt time.Time
	Type       MessageType
	To         string
	From       string
	Summary    string
	Direction  string
	Parts      int
	ReadAt     time.Time
	ReadBy     string
	// contains filtered or unexported fields
}

ReceivedMessageResponse is a single received message. It implements messageWithBody.

type ReceivedMessagesResponse

type ReceivedMessagesResponse struct {
	Paging
	Messages []ReceivedMessageResponse
}

ReceivedMessagesResponse is a list of received messages along with the paging information.

type SendResponse

type SendResponse struct {
	BatchID  string
	Messages []SendResponseMessage
}

SendResponse gives the batchid for the sent batch and lists the details of each message sent.

type SendResponseMessage

type SendResponseMessage struct {
	URI string
	ID  string
}

SendResponseMessage gives the details for a single sent message.

type SentMessageResponse

type SentMessageResponse struct {
	ID            string
	URI           string
	Reference     string
	Status        string
	LastStatusAt  time.Time
	SubmittedAt   time.Time
	Type          MessageType
	To            string
	From          string
	Summary       string
	Direction     string
	Parts         int
	Username      string
	FailureReason *FailureReason
	BatchID       string
	// contains filtered or unexported fields
}

SentMessageResponse is a single sent message. It implements messageWithBody.

type SentMessagesResponse

type SentMessagesResponse struct {
	Paging
	Messages []SentMessageResponse
}

SentMessagesResponse is a list of returned messages along with the paging information.