Go SMS

A simple app for sending Short Message Service (SMS) text messages using AWS Simple Notification Service.

Build

Run make build, and you should see go-sms binary in bin directory. Alternatively you can build a docker image by running make docker-build and run it by make run. Note that config.yaml should be located in the root of this project which should be based on config_sample.yaml.

You also can use go-sms pre-built docker image by docker pull martinsirbe/go-sms.

Configuration

Mandatory

• aws_access_key - AWS account access key id string.
• aws_secret_access_key - AWS account secret access key string.
• aws_region - AWS account secret access key string. (Only certain AWS regions are supported, check AWS documentation.)

Optional

• sender_id - Sender ID which will be visible on the receiver's device. Can be up to 11 alphanumeric characters which must contain at least one latter. When not set will default to NOTICE. This configuration value will be overridden by the CLI sender-id argument. (Note that only certain countries support sender ID, check AWS documentation.)
• max_price - The maximum price in USD that you are willing to pay to send the message. Note that your message won't be sent if the cost to send the message exceeds the set maximum price. This attribute will have no effect if the limit set for the MonthlySpendLimit attribute is exceeded. Check AWS documentation for SMS prices, based on this you can determine the possible max_price.
• sms_type - Signifies SMS type which is being sent. It can be either Promotional (default) or Transactional.
  • Promotional - Noncritical messages with optimised message delivery to incur the lowest cost, e.g. marketing messages.
  • Transactional - Critical messages with optimised message delivery to achieve the highest reliability, e.g. authentication messages.

See config_sample.yaml for an example configuration file.

CLI Options

You can provide options as environment variables, or pass options as CLI arguments.

Usage: go-sms [OPTIONS]

Short Message Service (SMS) text message sender using AWS Simple Notification Service.
                      
Options:              
  --sender-id     The sender ID which will appear on the receiver's device. (Optional, if provided will override sender ID provided via configuration file.) (env $SENDER_ID)
  --receiver      The receiver mobile phone number (in the E.164 format). (Mandatory) (env $RECEIVER)
  --message       The text message you wish to send. (Mandatory) (env $MESSAGE)
  --config-path   The path to the configurations file. (Mandatory) (env $GO_SMS_CONFIG_PATH)

• receiver - A mobile phone number in the E.164 format.
• message - Can be 160 GSM, 140 ASCII or 70 UCS-2 characters long with a total size limit of 1600 bytes per SMS publish action.
• config-path - Should point to the configurations file. You can use config_sample.yaml as a reference.

Examples

CLI

go-sms --sender-id=<sender_id> --receiver=<mobile_phone_number> --message=<your_message> --config-path=<path_to_config_file>

Docker

docker run --rm -v $PWD:/root/home go-sms:latest /bin/sh -c '/bin/go-sms \
    --config-path=/root/home/config_sample.yaml \
    --receiver="+44xxx." \
    --sender-id=TEST \
    --message="Hello world!"'    

Go

package main

import (
	"io/ioutil"

	"github.com/martinsirbe/go-sms/pkg/sms"
	log "github.com/sirupsen/logrus"
	"gopkg.in/yaml.v2"
)

func main() {
	configFile, err := ioutil.ReadFile("path/to/config.yaml")
	if err != nil {
		log.WithError(err).Fatal("failed to load go-sms config.yaml")
	}

	var config sms.Config
	if err = yaml.Unmarshal(configFile, &config); err != nil {
		log.WithError(err).Fatal("failed to unmarshal go-sms config.yaml")
	}

	sender := sms.New(config)
	if _, err := sender.Send("Hello world!", "+44xxx"); err != nil {
		log.WithError(err).Fatal("failed to send the text message")
	}
}

Tests

To run tests, just run make tests.

?   	github.com/martinsirbe/go-sms/cmd/go-sms	[no test files]
...
PASS
coverage: 86.5% of statements
ok  	github.com/martinsirbe/go-sms/pkg/sms	0.043s	coverage: 86.5% of statements
?   	github.com/martinsirbe/go-sms/pkg/sms/mocks	[no test files]

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Contributing

1. Go get it! go get github.com/martinsirbe/go-sms
2. Create your feature branch. (git checkout -b my-feature-branch)
3. Commit your changes. (git commit -m 'Add ...')
4. Push to the branch. (git push origin my-feature-branch)
5. Create a new pull request.