This server acts as the backend component of the SMSGate, facilitating the sending of SMS messages through connected Android devices. It includes a RESTful API for message management, integration with Firebase Cloud Messaging (FCM), and a database for persistent storage.
- SMS Messaging: Dispatch SMS and data messages through a RESTful API.
- Message Status: Retrieve status for sent messages.
- Device Management: View information about connected Android devices.
- Webhooks: Configure webhooks for event-driven notifications.
- Health Monitoring: Access health check endpoints to ensure system integrity.
- Access Control: Operate in either public mode for open access or private mode for restricted access.
- Data SMS Support: Send/receive binary payloads via SMS with Base64 encoding and port-based routing.
- JWT Authentication: Secure API access with JSON Web Tokens, including access and refresh token support for enhanced security.
- Go (for development and testing purposes)
- Docker and Docker Compose (for Docker-based setup)
- A configured MySQL/MariaDB database
The easiest way to get started with the server is to use the Docker-based setup in Private Mode. In this mode device registration endpoint is protected, so no one can register a new device without knowing the token.
- Set up MySQL or MariaDB database.
- Create config.yml, based on config.example.yml. The most important sections are
database,httpandgateway. Environment variables can be used to override values in the config file.- In
gateway.modesection setprivate. - In
gateway.private_tokensection set the access token for device registration in private mode. This token must be set on devices with private mode active. - (Optional) In
jwtsection configure JWT authentication:- Set
secretto a secure random string (minimum 32 characters) - Configure
access_ttl(default: 15m) andrefresh_ttl(default: 720h) - Set
issuerto identify your server
- Set
- In
- Start the server in Docker:
docker run -p 3000:3000 -v ./config.yml:/app/config.yml capcom6/sms-gateway:latest. - Set up private mode on devices.
- Use started private server with the same API as the public server at api.sms-gate.app.
See also docker-composee.yml for Docker-based setup.
The server has two work modes: public and private. The public mode allows anonymous device registration and used at api.sms-gate.app. Private mode can be used to send sensitive messages and running server in local infrastructure.
In most operations public and private modes are the same. But there are some differences:
POST /api/mobile/v1/deviceendpoint is protected by API key in private mode. So it is not possible to register a new device on private server without knowing the token.- FCM notifications from private server are sent through
api.sms-gate.app. Notifications don't contain any sensitive data like phone numbers or message text.
See also private mode discussion.
The server supports JWT (JSON Web Token) authentication for secure API access. When enabled, you can generate access tokens with specific scopes and refresh them without re-authenticating.
To enable JWT authentication, configure the jwt section in your config.yml:
jwt:
secret: your-secure-secret-key-minimum-32-characters # Required, minimum 32 characters
access_ttl: 15m # Access token time-to-live (default: 15m)
refresh_ttl: 720h # Refresh token time-to-live (default: 720h)
issuer: your-server-name # Optional issuer identifierImportant: The secret must be at least 32 characters long. The refresh_ttl must be greater than access_ttl.
Generate an access token and refresh token using Basic authentication:
POST /api/3rdparty/v1/auth/token HTTP/1.1
Authorization: Basic <base64-encoded-credentials>
Content-Type: application/json
{
"ttl": 3600,
"scopes": [
"messages:send",
"messages:read",
"devices:list",
"devices:delete",
"webhooks:list",
"webhooks:write",
"settings:read",
"settings:write",
"logs:read"
]
}Response:
{
"id": "token-jti",
"token_type": "Bearer",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2026-03-12T02:00:00Z"
}Use the refresh token to obtain a new access token:
POST /api/3rdparty/v1/auth/token/refresh HTTP/1.1
Authorization: Bearer <refresh_token>Revoke a specific token by its JTI (JWT ID):
DELETE /api/3rdparty/v1/auth/token/<jti> HTTP/1.1
Authorization: Basic <base64-encoded-credentials>Once you have an access token, use it in the Authorization header:
GET /api/3rdparty/v1/messages HTTP/1.1
Authorization: Bearer <access_token>The following scopes are available for token generation:
messages:send- Send SMS messagesmessages:read- Read individual messagesmessages:list- List messagesmessages:export- Export messagesdevices:list- List connected devicesdevices:delete- Delete deviceswebhooks:list- List webhookswebhooks:write- Create and update webhookswebhooks:delete- Delete webhookssettings:read- Read server settingssettings:write- Modify server settingslogs:read- Read server logstokens:manage- Generate and revoke tokens
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the Apache-2.0 license. See LICENSE for more information.
Android is a trademark of Google LLC.