                        How to send an SMS from Linux
                        =============================
                

1. Rationale: on  2025-06-17,  AT&T is going to  discontinue  their  SMS-Email
   interchange,     so    sending     email    to     phone@txt.att.net     or
   phonenumber@mms.att.net,  or from an AT&T  device  to an email is no longer
   going to work. So far there's not been an indication  that TMobile is going
   to pull the same stunt.

2. There are a couple ways to implement at least a unidirectional email-to-SMS
   gateway. This document describes the first of three.

3. Requirements:

   - an Android phone enough RAM and disk space to run TermUX and TermUX:API,

   - a SIM provisioned for unlimited SMSs,

   - the ususal infrastructure, i.e. a Linux box to originate SMSs from, and a
     WiFi access point or router.

4. Installation:

   - on the Linux box, download and install a current Tcl release.

   - phone and Linux box have to be on the same  network,  so that code on the
     Linux box can access the phone via scp and ssh. This can be  accomplished
     by:

     -- either, on the router or access point,  assigning an IP address to the
        phone's MAC address,

     -- or, on the  phone,  for the  WiFi  network  used,  assign a static  IP
        address for that  particular  WiFi  network  (i.e.  override  the DHCP
        address selection with a static one),

     -- if the  phone is not  always  logged  into the same  WiFi as the Linux
        host, run an  OpenVPN  server on the Linux box (this  would be a great
        time to set up PiVPN), generate a configuration for the phone, install
        OpenVPN on the phone, then feed the configuration generated earlier to
        the phone's OpenVPN. 

     -- if your router resolves the names of DHCP-connected clients into local
        IP  addresses,  it might be  possible  for the Linux box to access the
        phone by name and not IP address.

   - on the phone, install  TermUX and  TermUX:API  from either Google Play or
     F-Droid. When rigging mine, Google's TermUX was behind, so mine came from
     F-Droid.  There have been  issues with the on in Google's  Playstore.  No
     matter which one ends up on your device, do no mix and match!

   - on the phone,  invoke  termux, and from within  that, invoke "pkg install
     termux_api sshd screen".  Termux_api within termux invokes TermUX:API, so
     yes, this thing consists of two different components.
  
   - configure  phone  and Linux  host for  key-based  (so not  password-based
     access), by, on the host,  invoke  "ssh-keygen",  unless this has already
     been done, to create a private-public key pair.

   - the  public  key  needs to be copied to the  phone.  For this to  happen,
     obtain the user name within TermUX by locally  invoking  "whoami",  which
     might return  something  like u0_a123.  Chances are that this name is not
     going to change until at least the next phone upgrade, if ever.

   - On the phone, invoke "sshd". Make sure it is running by running "ps -ef".

   - The  phone's  sshd  listens on port 8022, means  rooting the phone is not
     required, but one has to tell ssh-copy-id, as in

    ssh-copy-id -p 8022 u0_a123@phone=IP

    ssh-copy-id -p 8022 u0_a123@phoneName

   - scp termux-sms-send.sh found in this directory to the phone:

     scp -oPort=8022 termux-sms-send.sh u0_a123@phone-IP

   - log into the phone:

     ssh -l u0_a123 -oPort=8022 phone-IP

   - In the phone's(!) TermUX home directory, create a "tmp" folder:

     mkdir tmp
    
   - On the phone, prepare a small text file (see below for limitations), then
     send it to a friendly number by running

     termux-sms-send -n +1-phoneNumber < your-text-file
    
     The  very  first  attempt  of this is going to fail,  because  termux  is
     lacking  some  permissions,  and will be asking.  Grant  these,  then try
     again.
    
This concluced phone setup.

- On Linux, invoke  install.sh to copy  send-sms.tcl and send-time.tcl to your
  $HOME/bin, then edit them to modify  TERMUX_HOSTS and TERMUX_USERS (both are
  Tcl  lists)  to  reflect  your  configuration.   Send-sms.tcl  invokes  ping
  concurrently  against all hosts  within the hosts list so it is able to find
  out if the phone is  connected  via WiFi or VPN, and under which IP address.
  The entries of TERMUX_USERS  have to match the accounts  available at the IP
  addresses,  so if you have two phones,  each of them  available  locally and
  over VPN, then your lists might look like so:

    set  TERMUX_HOSTS [ list  phone1-local-IP  phone1-VPN-IP \ phone2-local-IP
    phone2-VPN-IP ]

    set  TERMUX_USERS [ list  phone1-user-ID  phone1-user-ID  \ phone2-user-ID
    phone2-user-ID ]

  install.sh  creates  symbolic  links named  "send-sms"  and  "send-time"  to
  send-sms.tcl and send-time.sh.
  
- connect  your phone to WiFi. If that WiFi network is the same as the one the
  Linux  box is  connected  to,  skip  to the  next  step.  If not, or WiFi is
  unavailable, connect the phone to VPN.

- ssh into the  phone,  invoke  screen,  and from  within  screen,  run a ping
  against  the  Linux  box. Keep  this ping  running.  The idea is to keep the
  connection  active, since an unused  connected  eventually  gets taken down.
  Might want to keep your phone  plugged in while  using it as a gateway.  The
  reason for using ping from  inside  screen is that this way it stays  active
  even after one disconnects from first screen, then the phone.

- on the  Linux  box, drop the  message  to be sent into a file,  then  invoke
  "send-sms.tcl",  followed by a  comma-separated-list  of phone numbers, then
  the file(s) to be sent.
  
Should termux-send-sms not send messages timely, potential reasons include:

- termux:api was not installed (that has to come from the play store, not "pkg
  install"),

- phone has bad, intermittent or no signal at all,

- termux is confused and might need a phone reboot.

Messages can be longer than 160  characters  (the maximum  payload of a single
SMS), but,  depending  on  provider,  must not contain  certain  phrases.  TMO
allegedly  will not deliver any  messages  containing  the term  "confirmation
code" or any URLs.  Furthermore,  sending  too many  messages  in a short time
(that's  apparently  very  relative),  especially  on new lines, causes TMO to
silently no longer deliver any messages to non-TMO numbers for up to 10 days.
