Sending SMS from the command line

There are two broad approaches to sending text messages via the command line: email-SMS gateways and SMS gateway APIs.


Most phone networks provide email-to-SMS gateways. For example, Verizon will route emails to <phone number> as text messages to that phone number. Not all carriers support this, but most do.

Here are the benefits of the SMS via email approach:

  • Easy to use

  • Can use common email tools, libraries, and clients

Here are the downsides:

  • You must know the carrier associated with the phone number (this is becoming harder as it's much easier to transfer numbers between carriers these days).

  • Some carriers append cruft to the message ("Sent via Email at" or similar).

  • Emails are not handled in a standard way (e.g. some carriers will include the subject, some won't).

  • Carriers restrict email to personal messages and very low volume (if you send many emails over time, expect them to start bouncing).

  • Your email address is exposed to recipients.

In my opinion, the easiest and most beginner-friendly way to send mail from the command line is mutt. Mutt offers a command-line GUI to help with message sending, but you can also construct command-line one-liners to include in scripts. In its simplest form, you can do the following:

echo "my message" | mutt -s "my subject"

If you're a purist or you don't want the fanciness of mutt, you might use ssmtp to send mail via SMTP mail hub, or if you want to just send raw mail, use sendmail.

In all cases, you will probably have to configure your mailer so that it won't be rejected by spam filters. Doing so is beyond the scope of this article.

Textbelt Open Source is a free MIT-licensed library that abstracts many of these issues with using email-to-SMS gateways. However, it still requires your own email setup (it used to be available as a free online service, but it was abused by spammers and taken offline after about 5 years of operation).

Rolling your own email setup can be tricky. Usually it's best to use something like Mailgun, Sendgrid, etc. Textbelt uses Nodemailer which supports standard SMTP as well as email APIs.

SMS services

The next best way to send SMS from the command line is through text message APIs. Textbelt offers a paid SMS API in addition to the free open-source offering. There are many paid offerings in this space and I encourage you to shop around.

However, Textbelt's is probably the simplest API to work with. It was built with command-line use cases in mind. A curl request to Textbelt is simple:

curl -X POST \
       --data-urlencode phone='5557727420' \
       --data-urlencode message='Hello world' \
       -d key=textbelt

It's often useful to save this as an alias. On most Unix-based systems this can be done in your ~/.bashrc file:

text() {
  curl --data-urlencode number="$1" --data-urlencode "message=$2" -d key=textbelt

For example, you can chain a long-running job to notify you via SMS when it completes (I used to do this when I worked at Google and building Google Web Server took forever):

./ && text 5551234567

Deciding your approach

If you're just texting yourself from the command line, it's cheap (free) and relatively easy to use the email-to-SMS gateway of your mobile carrier. You can send this email either manually or via the open source project.

If you want to skip the headache of maintaining a local email setup, you may use Textbelt's hosted service or some other SMS provider. Textbelt lets you send one SMS per day for free, and you can buy quota if you think you'll be sending more.

Any questions? Email about this blog post and I'll get your message. Happy coding!

Last updated