every8d

README

go-every8d

A Go client library for accessing the EVERY8D SMS API.

Installation

Use go get to install.

go get -u github.com/minchao/go-every8d

Usage

Import the go-every8d package.

import "github.com/minchao/go-every8d"

Construct a new API client, then use to access the EVERY8D API. For example:

client := every8d.NewClient("UID", "PWD", nil)

Send an SMS

message := every8d.Message{
    Subject:         "Note",
    Content:         "Hello, 世界",
    Destination:     "+886987654321",
}

result, err := client.Send(context.Background(), message)

Query to retrieve the delivery status

resp, err := client.GetDeliveryStatus(context.Background(), batchID, pageNo)

Query credit

Retrieve your account balance.

credit, err := client.GetCredit(context.Background())

Use webhook to receive the sending report and reply message

func main() {
	http.HandleFunc("/callback", func(w http.ResponseWriter, r *http.Request) {
		report, err := every8d.ParseReportMessage(r)
		if err != nil {
			// Handle error...
			return
		}
		// Process report message...
	})
	if err := http.ListenAndServe(":8080", nil); err != nil {
		log.Printf("ListenAndServe error: %v", err)
	}
}

Develop

Command-line Tool

Change directory to cmd/every8d, and build the tool:

$ cd cmd/every8d
$ go build

Run:

$ ./every8d
EVERY8D SMS CLI tool

Usage:
  every8d [command]

Available Commands:
  credit          Query credit
  delivery-status Query to retrieve the delivery status
  help            Help about any command
  send            Send an SMS
  send-mms        Send an MMS
  webhook         Webhook to receive the sending report and reply message

Flags:
  -h, --help              help for every8d
      --password string   EVERY8D Password
      --username string   EVERY8D Username

Use "every8d [command] --help" for more information about a command.

Example to send SMS:

$ ./every8d send --username=0987654321 --password=password --dest=0987654321 --msg="Hello, 世界"
Credit: 79.00
Sent: 1
Cost: 1.00
Unsent: 0
BatchID: 00000000-00000-0000-0000-000000000000

Run all tests

$ go test -v -race .

License

This library is distributed under the BSD-style license found in the LICENSE file.

Documentation

Index

• Constants
• func CheckResponse(r *http.Response) error
• type Client
  • func NewClient(username, password string, httpClient *http.Client) *Client
  • func (c *Client) Do(ctx context.Context, req *http.Request, fn Parser, v interface{}) (*http.Response, error)
  • func (c *Client) GetCredit(ctx context.Context) (float64, error)
  • func (c *Client) GetDeliveryStatus(ctx context.Context, batchID, pageNo string) (*DeliveryStatusResponse, error)
  • func (c *Client) GetMMSDeliveryStatus(ctx context.Context, batchID, pageNo string) (*DeliveryStatusResponse, error)
  • func (c *Client) NewFormRequest(urlStr string, form url.Values) (*http.Request, error)
  • func (c *Client) NewRequest(method, urlStr string, body io.Reader) (*http.Request, error)
  • func (c *Client) Send(ctx context.Context, message Message) (*SendResponse, error)
  • func (c *Client) SendMMS(ctx context.Context, message MMS) (*SendResponse, error)
• type DeliveryStatus
• type DeliveryStatusResponse
• type ErrorResponse
  • func (r *ErrorResponse) Error() string
• type MMS
• type Message
• type Parser
• type ReportMessage
  • func ParseReportMessage(r *http.Request) (*ReportMessage, error)
• type SendResponse
• type StatusCode
  • func (c StatusCode) Text() string

Constants

const (
	StatusInvalidMobileNumber                  = StatusCode(-3)
	StatusDTFormatErrorOrPassedMoreThan24Hours = StatusCode(-4)
	StatusTheContentIsEmpty                    = StatusCode(-24)
	StatusNoMobile                             = StatusCode(-41)
	StatusServerSiteError                      = StatusCode(-99)
	StatusWrongUsername                        = StatusCode(-100)
	StatusWrongPassword                        = StatusCode(-101)
	StatusUsernameAndPasswordAreRequired       = StatusCode(-300)
	StatusSubjectRequired                      = StatusCode(-303)
	StatusImageRequired                        = StatusCode(-304)
	StatusImageTypeRequired                    = StatusCode(-305)
	StatusImageTooLarge                        = StatusCode(-314)
	StatusSent                                 = StatusCode(0)
	StatusMessageReceived                      = StatusCode(100)
	StatusDeliveryFailureDueMobile             = StatusCode(101)
	StatusDeliveryFailureDueTelecom102         = StatusCode(102)
	StatusMobileNumberNotExist                 = StatusCode(103)
	StatusDeliveryFailureDueTelecom104         = StatusCode(104)
	StatusDeliveryFailureDueTelecom105         = StatusCode(105)
	StatusDeliveryFailureDueTelecom106         = StatusCode(106)
	StatusReceivedAfterDeadline                = StatusCode(107)
	StatusReservationSMS                       = StatusCode(300)
	StatusNoCredit                             = StatusCode(301)
	StatusCanceled                             = StatusCode(303)
	StatusInternationalSMSNotConfigured        = StatusCode(500)
	StatusSMSSent                              = StatusCode(700)
	StatusTestingMode                          = StatusCode(888)
	StatusReplayContent                        = StatusCode(999)
)

List of EVERY8D API status codes.

Functions

func CheckResponse

func CheckResponse(r *http.Response) error

CheckResponse checks the API response for errors.

Types

type Client

type Client struct {

	// Base URL for API requests, should always be specified with a trailing slash.
	BaseURL *url.URL

	// User agent used when communicating with the EVERY8D API.
	UserAgent string
	// contains filtered or unexported fields
}

A Client manages communication with the EVERY8D API.

func NewClient

func NewClient(username, password string, httpClient *http.Client) *Client

NewClient returns a new EVERY8D API client.

func (*Client) Do

func (c *Client) Do(ctx context.Context, req *http.Request, fn Parser, v interface{}) (*http.Response, error)

Do sends an API request and returns the API response.

The provided ctx must be non-nil. If it is canceled or time out, ctx.Err() will be returned.

func (*Client) GetCredit

func (c *Client) GetCredit(ctx context.Context) (float64, error)

GetCredit retrieves your account balance.

func (*Client) GetDeliveryStatus

func (c *Client) GetDeliveryStatus(ctx context.Context, batchID, pageNo string) (*DeliveryStatusResponse, error)

GetDeliveryStatus retrieves the delivery status.

func (*Client) GetMMSDeliveryStatus

func (c *Client) GetMMSDeliveryStatus(ctx context.Context, batchID, pageNo string) (*DeliveryStatusResponse, error)

GetMMSDeliveryStatus retrieves the MMS delivery status.

func (*Client) NewFormRequest

func (c *Client) NewFormRequest(urlStr string, form url.Values) (*http.Request, error)

NewFormRequest creates an API POST request.

func (*Client) NewRequest

func (c *Client) NewRequest(method, urlStr string, body io.Reader) (*http.Request, error)

NewRequest creates an API request.

func (*Client) Send

func (c *Client) Send(ctx context.Context, message Message) (*SendResponse, error)

Send sends an SMS.

func (*Client) SendMMS

func (c *Client) SendMMS(ctx context.Context, message MMS) (*SendResponse, error)

SendMMS sends a MMS.

type DeliveryStatus

type DeliveryStatus struct {
	Name     string
	Mobile   string
	SendTime string
	Cost     float64
	Status   StatusCode
}

DeliveryStatus represents delivery status.

type DeliveryStatusResponse

type DeliveryStatusResponse struct {
	Count   int
	Records []DeliveryStatus
}

DeliveryStatusResponse represents the response of get delivery status.

type ErrorResponse

type ErrorResponse struct {
	Response  *http.Response
	ErrorCode StatusCode
	Message   string
}

ErrorResponse reports error caused by an API request.

func (*ErrorResponse) Error

func (r *ErrorResponse) Error() string

type MMS

type MMS struct {
	// Message title.
	Subject string `form:"SB"`

	// Message content.
	Content string `form:"MSG"`

	// Receiver's mobile number.
	// Format: +88612345678 or 0912345678, Separator: (,) e.g. 0912345678,0922333444
	Destination string `form:"DEST"`

	// Reservation time
	// Format: yyyyMMddHHmnss, e.g. 20090131153000
	// Send immediately: No input (empty).
	ReservationTime string `form:"ST,omitempty"`

	// MMS validity period of unit: minutes.
	// If not specified, then the platform default validity period is 1440 minutes.
	RetryTime int `form:"RETRYTIME,omitempty"`

	// Message record no.
	MessageNo string `form:"MR,omitempty"`

	// Image file, binary base64 encoded.
	Attachment string `form:"ATTACHMENT"`

	// Image file extension, support jpg/jpeg/png/git.
	Type string `form:"TYPE"`
}

MMS represents an MMS object.

type Message

type Message struct {
	// Message title.
	// Empty titles are accepted.
	// The title will not be sent with the SMS; it is just a note.
	Subject string `form:"SB,omitempty"`

	// Message content.
	Content string `form:"MSG"`

	// Receiver's mobile number.
	// Format: +88612345678 or 0912345678, Separator: (,) e.g. 0912345678,0922333444
	Destination string `form:"DEST"`

	// Reservation time
	// Format: yyyyMMddHHmnss, e.g. 20090131153000
	// Send immediately: No input (empty).
	ReservationTime string `form:"ST,omitempty"`

	// SMS validity period of unit: minutes.
	// If not specified, then the platform default validity period is 1440 minutes.
	RetryTime int `form:"RETRYTIME,omitempty"`

	// Message record no.
	MessageNo string `form:"MR,omitempty"`
}

Message represents an SMS object.

type Parser

type Parser func(body io.Reader, v interface{}) error

Parser parses the response body into a object v.

type ReportMessage

type ReportMessage struct {
	// Batch ID.
	BatchID string `url:"BatchID"`

	// Receive's mobile number.
	// Format: +88612345678
	Destination string `url:"RM"`

	// Report time.
	ReportTime string `url:"RT"`

	// Sending status.
	StatusCode StatusCode `url:"STATUS"`

	// Reply message.
	ReplyMessage string `url:"SM,omitempty"`

	// Message record no.
	MessageNo string `url:"MR,omitempty"`
}

ReportMessage represents sending report or reply message.

func ParseReportMessage

func ParseReportMessage(r *http.Request) (*ReportMessage, error)

ParseReportMessage parses an incoming EVERY8D callback request and return the ReportMessage.

type SendResponse

type SendResponse struct {
	// Balance credit.
	// Negative means there was a delivery failure and the system can't process this command.
	Credit float64

	// Sent messages.
	Sent int

	// This shows spent points.
	Cost float64

	// Unsent messages with no credit charged.
	Unsent int

	// Batch ID. e.g. 220478cc-8506-49b2-93b7-2505f651c12e
	BatchID string
}

SendResponse represents the response of send an SMS.

type StatusCode

type StatusCode int

StatusCode of EVERY8D API.

func (StatusCode) Text

func (c StatusCode) Text() string

Text returns status code text.