AWS SMS Blast
Powerful SMS batch sending for the command line, powered by AWS SNS text messaging.
π€ Forgiving phone number parsing with landline rejection.π€ Filters out duplicate phone numbersπ€ Variable interpolation ("Hey {name}, your order will ship on...")β° Smart progress bar with ETAπ€ AWS cost estimation before sending, with interactive prompt.π Fully multithreaded message dispatch
βοΈ Please note: Access to AWS SNS text messaging is tightly regulated by Amazon to prevent abuse. To send any useful amount of messages (> 155/month), you'll need to apply for access)
Installation
Just clone the repo.
Usage
Setup
- Create and configure
.env.json
with your AWS credentials (Copy.example.env.json
and customize) - Create a
data
directory in project root
On every run:
- In
./data
, add:
- A CSV file
recipients.csv
containing the columnphone
(All other columns will be ignored, although you can interpolate variables from them) - Text file:
template.txt
npm run send
Here's what output looks like:
π Start!
π Reading recipient CSV file (.././data/recipients.csv)
π Found 1 recipient
π¬ Checking message...
βΉοΈ "Hey {name}. Your order will be delivered on Friday, between 6 AM - 2PM."
β
Message is ASCII only
β
Message byte length is 88 (Limit is 140)
βΉοΈ Phone numbers without a international country code will be assumed to be North American (+1)
π¬ Validating 1 recipients...
β
All phone numbers normalized
β
No duplicates found
β
Recipient validation complete
β
All validations passed
π Total recipients: 1
β° Estimated send time: 0.25s
πΈ Estimated AWS price to send: $0.00847
π Ready to send to 1 recipients? [y/n] y
π Sending 1 messages...
𧡠16 threads
1/1 = (100%) 0.0
β
All messages sent (0.265s)
π That's all, folks!
Recipients file
- Must be named
recipients.csv
- Must contain a text column
phone
- All other column data can be interpolated into the message text (see below)
The phone
column is forgiving with input formatting. So 123-456-7890
, (123) 456-7890
, and +44 123 456 7890
are all acceptable.
(See this library for exact phone syntax and limitations)
Example:
firstName,lastName,phone
Iarwain,Ben Adar,(123)456-7890
Message
Your message should be a simple text file ./data/template.txt
.
You can interpolate variables from your recipients.csv
with {name}
syntax.
(See this package) for exact interpolation syntax)
Example:
recipients.csv
firstName,lastName,phone
Iarwain,Ben Adar,(123)456-7890
template.txt
Your name is {firstName} {lastName}
Final text output:
Your name is Iarwain Ben Adar
Message size limits
Your message is subject to the limits of SMS messages. Message length must be under 140 bytes. This is 140 ASCII characters.
Longer messages will be split by SNS into separate messages, each of which will be billed individually.
See the official SNS docs.
If your template text is too long, the process will refuse to continue.
Sending
If all validations pass, you'll be presented with the estimated cost of sending in USD, and a time estimate. You'll be prompted to confirm that yu really want to send.
If you confirm, the script will spawn a bunch of workers and will submit your messages to Amazon SNS. Messages typically arrive within seconds.
You'll be shown a true progress bar with live ETA while your messages are being submitted.
That's all, folks!
Appendix
Why multithreading?
Amazon SNS text messaging does not support bulk sending. This means that a separate API call must be made for every message. So 1000 recipients = 1000 API calls.
Additionally, SNS imposes a 100 requests/second limit.
We solve this by spawning worker threads that send the messages in parallel. A worker pool prevents too many messages from being sent at once.
A potential workaround was to generate a throwaway SNS Topic, subscribe all the phone numbers to the topic, and then send a single message to the topic, which SNS would deliver to all phone numbers. Unfortunately SNS subscriptions do not support bulk signup either, so we'd need to make the same amount of API calls.
Applying for SNS bulk limits
To raise your limit, you'll need to request approval using a AWS Support Request. See the official docs
Thank You
- Papa Parse Powerful CSV parsing
phone
Normalizes input phone numbers (even obscure international ones) 8string-template
Runs variable interpolation- yesno Powers interactive prompts
- progress Provides the CLI progress bar
- async/queue Makes multithreaded requests a breeze
- Amazon SNS Sends the actual messages