Skip to content

Commit 5554e77

Browse files
committed
[commands] send MMS support
1 parent 154f199 commit 5554e77

13 files changed

Lines changed: 524 additions & 81 deletions

File tree

‎.env.example‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Environment Configuration Template for SMSGate CLI
2+
# Copy this file to .env and fill in your actual values
3+
# This file contains all required environment variables with examples and documentation
4+
5+
# =============================================================================
6+
# API CONFIGURATION
7+
# =============================================================================
8+
9+
# API Endpoint URL
10+
# Purpose: Base URL of the SMS Gateway API used by the smsgate CLI for all requests
11+
# Format: URL
12+
# Default: https://api.sms-gate.app/3rdparty/v1
13+
# Example: https://api.sms-gate.app/3rdparty/v1
14+
# Example: http://localhost:8080/3rdparty/v1
15+
ASG_ENDPOINT=https://api.sms-gate.app/3rdparty/v1
16+
17+
# API Username
18+
# Purpose: Username for authenticating with the SMS Gateway API
19+
# Format: String
20+
# Example: myuser
21+
ASG_USERNAME=your-username
22+
23+
# API Password
24+
# Purpose: Password for authenticating with the SMS Gateway API
25+
# Format: String
26+
# Example: mypassword
27+
ASG_PASSWORD=your-password
28+
29+
# =============================================================================
30+
# CERTIFICATE AUTHORITY CONFIGURATION
31+
# =============================================================================
32+
33+
# CA Request Timeout
34+
# Purpose: Timeout for requests made by the smsgate-ca CLI tool when issuing TLS certificates
35+
# Format: Duration (e.g. 30s, 1m, 5m)
36+
# Default: 30s
37+
# Example: 30s
38+
# Example: 1m
39+
ASG_CA_TIMEOUT=30s

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6+
7+
## [Unreleased]
8+
9+
### New Features
10+
11+
- **MMS message support** — send MMS messages via the `send` command with media attachments

‎README.md‎

Lines changed: 118 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -25,50 +25,55 @@
2525
</div>
2626

2727
<!-- TABLE OF CONTENTS -->
28-
- [📱 About The Project](#-about-the-project)
29-
- [⚙️ Built With](#️-built-with)
30-
- [💻 Getting Started](#-getting-started)
28+
- [About The Project](#about-the-project)
29+
- [Built With](#built-with)
30+
- [Getting Started](#getting-started)
3131
- [Prerequisites](#prerequisites)
3232
- [Installation](#installation)
3333
- [Option 1: Download from GitHub Releases](#option-1-download-from-github-releases)
3434
- [Option 2: Install using Go](#option-2-install-using-go)
3535
- [Option 3: Docker](#option-3-docker)
36-
- [💻 Configuration](#-configuration)
36+
- [Configuration](#configuration)
3737
- [Available Options](#available-options)
3838
- [Output Formats](#output-formats)
39-
- [💻 Usage](#-usage)
39+
- [Usage](#usage)
4040
- [Commands](#commands)
4141
- [Exit codes](#exit-codes)
4242
- [Examples](#examples)
4343
- [Sending messages](#sending-messages)
4444
- [Batch message sending](#batch-message-sending)
4545
- [Getting message status](#getting-message-status)
46+
- [Managing webhooks](#managing-webhooks)
4647
- [Getting logs](#getting-logs)
4748
- [Output formats](#output-formats-1)
48-
- [👥 Contributing](#-contributing)
49-
- [©️ License](#️-license)
50-
- [⚠️ Legal Notice](#️-legal-notice)
49+
- [Certificate Authority (smsgate-ca)](#certificate-authority-smsgate-ca)
50+
- [Global Flags](#global-flags)
51+
- [Commands](#commands-1)
52+
- [`webhooks`](#webhooks)
53+
- [`private`](#private)
54+
- [Command Flags](#command-flags)
55+
- [Contributing](#contributing)
56+
- [License](#license)
57+
- [Legal Notice](#legal-notice)
5158

5259

5360
<!-- ABOUT THE PROJECT -->
54-
## 📱 About The Project
61+
## About The Project
5562

56-
There are two CLI tools in this repository: `smsgate` and `smsgate-ca`. The first one is for SMS Gateway for Android itself, and the second one is for the Certificate Authority.
63+
There are two CLI tools in this repository:
5764

58-
This CLI provides a robust interface for:
59-
- Sending and managing SMS messages (including batch operations from CSV and Excel files)
60-
- Configuring webhook integrations
61-
- Issuing certificates for private deployments
65+
- **`smsgate`** -- Interact with the [SMS Gateway for Android](https://sms-gate.app) API to send SMS/MMS messages, manage webhooks, and retrieve logs.
66+
- **`smsgate-ca`** -- Issue TLS certificates for private deployments (webhook receivers and private servers on RFC 1918 addresses).
6267

63-
### ⚙️ Built With
68+
### Built With
6469

6570
- [![Go][Go-shield]][Go-url]
6671
- [![Goreleaser][Goreleaser-shield]][Goreleaser-url]
6772

6873
<p align="right">(<a href="#readme-top">back to top</a>)</p>
6974

7075
<!-- GETTING STARTED -->
71-
## 💻 Getting Started
76+
## Getting Started
7277

7378
### Prerequisites
7479

@@ -101,9 +106,9 @@ docker run -it --rm --env-file .env ghcr.io/android-sms-gateway/cli \
101106

102107
<p align="right">(<a href="#readme-top">back to top</a>)</p>
103108

104-
## 💻 Configuration
109+
## Configuration
105110

106-
The CLI can be configured using environment variables or command-line flags. You can also use a `.env` file in the working directory to set these variables.
111+
The CLI can be configured using environment variables or command-line flags. You can also use a `.env` file in the working directory to set these variables (loaded automatically via [godotenv](https://github.com/joho/godotenv)).
107112

108113
### Available Options
109114

@@ -127,7 +132,7 @@ Please note that when the exit code is not `0`, the error description is printed
127132

128133
<p align="right">(<a href="#readme-top">back to top</a>)</p>
129134

130-
## 💻 Usage
135+
## Usage
131136

132137
```bash
133138
smsgate [global options] command [command options] [arguments...]
@@ -137,8 +142,8 @@ smsgate [global options] command [command options] [arguments...]
137142

138143
The CLI offers three main groups of commands:
139144

140-
- **Messages**: Commands for sending messages and checking their status, including batch operations from CSV and Excel files.
141-
- **Webhooks**: Commands for managing webhooks, including creating, updating, and deleting them.
145+
- **Messages**: Commands for sending SMS, MMS, and data messages, and checking their status, including batch operations from CSV and Excel files.
146+
- **Webhooks**: Commands for managing webhooks, including registering, listing, and deleting them.
142147
- **Logs**: Commands for retrieving logs for a specific time range.
143148

144149
For a complete list of available commands, you can:
@@ -153,6 +158,7 @@ The CLI uses exit codes to indicate the outcome of operations:
153158
- `1`: invalid options or arguments
154159
- `2`: server request error
155160
- `3`: output formatting error
161+
- `4`: internal error
156162

157163
### Examples
158164

@@ -190,7 +196,7 @@ smsgate send --phones '+12025550123' --priority 100 'Urgent message'
190196
smsgate send --phones '+12025550123' --ttl 1h30m 'Expiring message'
191197

192198
# Send with expiration date (RFC3339 format)
193-
smsgate send --phones '+12025550123' --valid-until '2024-12-31T23:59:59Z' 'Message'
199+
smsgate send --phones '+12025550123' --valid-until '2026-12-31T23:59:59Z' 'Message'
194200

195201
# Disable delivery report
196202
smsgate send --phones '+12025550123' --delivery-report=false 'Message'
@@ -204,8 +210,28 @@ smsgate send --phones '+12025550123' --device-active-within 12 'Message'
204210
# Send data message (base64 encoded)
205211
echo -n 'hello world' | base64
206212
smsgate send --phones '+12025550123' --data --data-port 12345 'aGVsbG8gd29ybGQ='
213+
214+
# Send MMS with subject and multiple attachments
215+
smsgate send --mms --subject 'Project update' --phones '+12025550123' \
216+
--attachment /path/to/report.pdf \
217+
--attachment /path/to/chart.png \
218+
'Here are the latest documents'
219+
220+
# Send MMS with attachments only (no text)
221+
smsgate send --mms --phones '+12025550123' \
222+
--attachment /path/to/photo.jpg
223+
224+
# Send MMS to multiple recipients
225+
smsgate send --mms --phones '+12025550123' --phones '+12025550124' \
226+
--subject 'Team update' --attachment /path/to/screenshot.png \
227+
'Please review'
207228
```
208229

230+
**Notes:**
231+
- `--data` and `--mms` are mutually exclusive.
232+
- At least one of text or an attachment is required for MMS.
233+
- MIME type is detected from the file extension (falls back to `application/octet-stream`).
234+
209235
**Send command options:**
210236

211237
| Option | Description | Default Value | Example |
@@ -219,11 +245,16 @@ smsgate send --phones '+12025550123' --data --data-port 12345 'aGVsbG8gd29ybGQ='
219245
| **Data Message** | | | |
220246
| `--data` | Send data message instead of text (content must be base64 encoded). | `false` | `true` |
221247
| `--data-port` | Destination port for data message (1 to 65535). | `53739` | `12345` |
248+
| **MMS Message** | | | |
249+
| `--mms` | Send MMS message instead of text; text is optional when at least one attachment is provided. | `false` | `true` |
250+
| `--subject` | MMS subject line. Requires `--mms`. | empty | `Photo update` |
251+
| `--attachment` | Path to an attachment file. Repeatable; MIME type is detected from the file extension. Requires `--mms`. | empty | `/path/to/image.jpg` |
222252
| **Options** | | | |
223253
| `--ttl` | Time-to-live (TTL) for the message. Duration format (e.g., `1h30m`). If not provided, the message will not expire.<br>**Conflicts with `--valid-until`.** | empty | `1h30m` |
224-
| `--valid-until` | The expiration date and time for the message. RFC3339 format (e.g., `2006-01-02T15:04:05Z07:00`).<br>**Conflicts with `--ttl`.** | empty | `2024-12-31T23:59:59Z` |
254+
| `--valid-until` | The expiration date and time for the message. RFC3339 format (e.g., `2006-01-02T15:04:05Z07:00`).<br>**Conflicts with `--ttl`.** | empty | `2026-12-31T23:59:59Z` |
225255
| `--skip-phone-validation` | Skip phone number validation. | `false` | `true` |
226256
| `--device-active-within` | Time window in hours for device activity filtering. `0` means no filtering. | `0` | `12` |
257+
| `--schedule-at` | Schedule delivery time (RFC3339 format). If not provided, the message is sent immediately.<br>**Example:** `2026-12-31T23:59:59Z`. | immediate | `2026-12-31T23:59:59Z` |
227258

228259
#### Batch message sending
229260

@@ -351,6 +382,24 @@ Phone,Message,Device,Priority
351382
smsgate status zXDYfTmTVf3iMd16zzdBj
352383
```
353384

385+
#### Managing webhooks
386+
387+
```bash
388+
# Register a webhook for SMS received events
389+
smsgate webhooks register -e sms:received https://example.com/webhook
390+
391+
# Register a device-specific webhook
392+
smsgate webhooks register -e sms:sent --device-id device123 https://example.com/webhook
393+
394+
# List all registered webhooks
395+
smsgate webhooks list
396+
397+
# Delete a webhook by ID
398+
smsgate webhooks delete <webhook-id>
399+
```
400+
401+
**Supported webhook events:** `sms:received`, `sms:sent`, `sms:failed`, `device:connected`, `device:disconnected`
402+
354403
#### Getting logs
355404

356405
The `logs` command retrieves logs for a specific time range. Dates should be in RFC3339 format (e.g., `2024-01-15T10:30:00Z`).
@@ -418,7 +467,50 @@ def45678-e89b-12d3-a456-426614174000 sms:sent https://example.com/other
418467

419468
<p align="right">(<a href="#readme-top">back to top</a>)</p>
420469

421-
## 👥 Contributing
470+
## Certificate Authority (smsgate-ca)
471+
472+
The `smsgate-ca` tool issues TLS certificates for private deployments. It generates ECDSA P-256 certificates signed by the SMS Gateway CA.
473+
474+
```bash
475+
smsgate-ca [global flags] <command> [command flags] [arguments]
476+
```
477+
478+
### Global Flags
479+
480+
| Flag | Aliases | Env Var | Default | Description |
481+
| ----------- | ------- | ---------------- | ------- | --------------- |
482+
| `--timeout` | `-t` | `ASG_CA_TIMEOUT` | `30s` | Request timeout |
483+
484+
### Commands
485+
486+
#### `webhooks`
487+
488+
Issue a TLS certificate for a webhook receiver running on a private IP address.
489+
490+
```bash
491+
smsgate-ca webhooks <ip-address> --out server.crt --keyout server.key
492+
```
493+
494+
#### `private`
495+
496+
Issue a TLS certificate for a private server running on a private IP address.
497+
498+
```bash
499+
smsgate-ca private <ip-address> --out server.crt --keyout server.key
500+
```
501+
502+
### Command Flags
503+
504+
| Flag | Default | Description |
505+
| ---------- | ------------ | ----------------------- |
506+
| `--out` | `server.crt` | Certificate output file |
507+
| `--keyout` | `server.key` | Private key output file |
508+
509+
**Note:** The IP address must be a private/RFC 1918 address (e.g., `10.x.x.x`, `172.16.x.x`, `192.168.x.x`).
510+
511+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
512+
513+
## Contributing
422514

423515
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
424516

@@ -433,13 +525,13 @@ Don't forget to give the project a star! Thanks again!
433525

434526
<p align="right">(<a href="#readme-top">back to top</a>)</p>
435527

436-
## ©️ License
528+
## License
437529

438530
Distributed under the Apache-2.0 license. See [LICENSE](LICENSE) for more information.
439531

440532
<p align="right">(<a href="#readme-top">back to top</a>)</p>
441533

442-
## ⚠️ Legal Notice
534+
## Legal Notice
443535

444536
Android is a trademark of Google LLC.
445537

‎go.mod‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ module github.com/android-sms-gateway/cli
33
go 1.25.0
44

55
require (
6-
github.com/android-sms-gateway/client-go v1.12.10
6+
github.com/android-sms-gateway/client-go v1.15.0
77
github.com/google/uuid v1.6.0
88
github.com/joho/godotenv v1.5.1
99
github.com/samber/lo v1.53.0
@@ -15,7 +15,6 @@ require (
1515
require (
1616
github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
1717
github.com/davecgh/go-spew v1.1.1 // indirect
18-
github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
1918
github.com/pmezard/go-difflib v1.0.0 // indirect
2019
github.com/richardlehane/mscfb v1.0.6 // indirect
2120
github.com/richardlehane/msoleps v1.0.6 // indirect

0 commit comments

Comments
 (0)