gosms-python 1.1.0

Official Python SDK for GoSMS.GE SMS Gateway

GoSMS.GE Python SDK

Official Python SDK for the GoSMS.GE SMS gateway. Send SMS messages, manage OTP verification, and check balances with both sync and async clients.

Installation

pip install gosms-python

For async support:

pip install gosms-python[async]

Quick Start

from gosms import SMS

sms = SMS("your_api_key")

# Send a message
result = sms.send("995555123456", "Hello!", "GOSMS.GE")
print(result.message_id)  # 12345
print(result.balance)     # 99

# Check balance
balance = sms.balance()
print(balance.balance)  # 500

All Endpoints

Send SMS

result = sms.send("995555123456", "Hello!", "GOSMS.GE")
result = sms.send("995555123456", "Urgent!", "GOSMS.GE", urgent=True)

Send Bulk SMS

result = sms.send_bulk(
    "GOSMS.GE",
    ["995555111111", "995555222222"],
    "Hello everyone!",
)
print(result.total_count)    # 2
print(result.success_count)  # 2

for msg in result.messages:
    print(f"{msg.to}: {msg.message_id}")

Send OTP

result = sms.send_otp("995555123456")
print(result.hash)  # "abc123hash" — save this for verification

# Rate limit info (available since v2.1.0)
if result.rate_limit:
    print(result.rate_limit.remaining)  # 9
    print(result.rate_limit.limit)      # 10

Verify OTP

result = sms.verify_otp("995555123456", "abc123hash", "1234")
print(result.verify)  # True

# Rate limit info
if result.rate_limit:
    print(result.rate_limit.remaining)  # 8

Check Message Status

result = sms.status(12345)
print(result.status)  # "delivered"

Check Balance

result = sms.balance()
print(result.balance)  # 500

Create Sender Name

result = sms.create_sender("MyBrand")
print(result.success)  # True

Async Usage

import asyncio
from gosms import AsyncSMS

async def main():
    async with AsyncSMS("your_api_key") as sms:
        result = await sms.send("995555123456", "Hello!", "GOSMS.GE")
        print(result.message_id)

        balance = await sms.balance()
        print(balance.balance)

asyncio.run(main())

All methods from the sync client are available as async equivalents with the same signatures.

Django Integration

Add to your settings.py:

GOSMS_SETTINGS = {
    "api_key": "your_api_key",
    "timeout": 30,    # optional
    "retries": 1,     # optional
}

Use anywhere in your project:

from gosms.django import get_sms_client

sms = get_sms_client()
sms.send("995555123456", "Hello!", "GOSMS.GE")

The client is created lazily on first call and reused as a singleton.

Configuration

sms = SMS(
    "your_api_key",
    timeout=30,   # request timeout in seconds (default: 30)
    retries=3,    # retry attempts on failure (default: 1)
    debug=True,   # enable debug logging (default: False)
)

Error Handling

from gosms import SMS, GoSmsApiError, GoSmsErrorCode

sms = SMS("your_api_key")

try:
    result = sms.send("995555123456", "Hello!", "GOSMS.GE")
except GoSmsApiError as e:
    print(e.error_code)  # 100
    print(e.message)     # "Invalid API key"

    if e.error_code == GoSmsErrorCode.INVALID_API_KEY:
        print("Check your API key")

Rate Limit Errors

When OTP rate limits are exceeded, the error includes retry_after (seconds until the lockout expires):

try:
    result = sms.send_otp("995555123456")
except GoSmsApiError as e:
    if e.error_code == GoSmsErrorCode.TOO_MANY_REQUESTS:
        print(f"Too many attempts. Retry after {e.retry_after}s")
    elif e.error_code == GoSmsErrorCode.ACCOUNT_LOCKED:
        print(f"Account locked. Retry after {e.retry_after}s")

Error Codes

Code	Constant	Description
100	INVALID_API_KEY	Invalid API key
101	INVALID_SENDER	Invalid sender name
102	INSUFFICIENT_BALANCE	Insufficient balance
103	INVALID_PARAMETERS	Invalid request parameters
104	MESSAGE_NOT_FOUND	Message not found
105	INVALID_PHONE	Invalid phone number
106	OTP_FAILED	OTP verification failed
107	SENDER_EXISTS	Sender name already exists
108	NOT_CONFIGURED	API key not configured
109	TOO_MANY_REQUESTS	Too many OTP requests
110	ACCOUNT_LOCKED	Account temporarily locked
111	OTP_EXPIRED	OTP code expired
112	OTP_ALREADY_USED	OTP already verified
113	INVALID_NO_SMS_NUMBER	Invalid no-SMS number

Response Types

All methods return typed frozen dataclasses:

Method	Return Type	Key Fields
send()	SmsSendResponse	success, message_id, balance
send_bulk()	SendBulkSmsResponse	success, total_count, messages
send_otp()	OtpSendResponse	success, hash, balance, rate_limit
verify_otp()	OtpVerifyResponse	success, verify, rate_limit
status()	CheckStatusResponse	success, status, message_id
balance()	BalanceResponse	success, balance
create_sender()	SenderCreateResponse	success

RateLimitInfo

The rate_limit field on OTP responses is a RateLimitInfo object (or None if the server didn't return rate limit headers):

Field	Type	Description
limit	int | None	Maximum attempts allowed
remaining	int | None	Attempts remaining
retry_after	int | None	Seconds until lockout expires (only on error)

Migration from v1.x

v2.0 is a complete rewrite. Key changes:

# v1.x (old)
from gosms import sms                    # module-level singleton
sms.send('995...', 'text', 'SENDER')

# v2.0 (new)
from gosms import SMS                    # explicit instantiation
sms = SMS('your_api_key')
sms.send('995...', 'text', 'SENDER')

# v1.x Django (old)
from gosms import sms                    # import-time side effect

# v2.0 Django (new)
from gosms.django import get_sms_client  # lazy factory
sms = get_sms_client()

Other changes:

• GoSmsApiError now extends Exception (was BaseException)
• Added GoSmsErrorCode constants for typed error handling
• Added send_bulk() and create_sender() endpoints
• Added async client (AsyncSMS) via pip install gosms-python[async]
• All responses are typed frozen dataclasses
• Removed dev_mode / RequestMock in favor of standard test mocking

License

MIT

Links

• Website: https://gosms.ge
• PyPI: https://pypi.org/project/gosms-python/
• GitHub: https://github.com/gosms-ge/gosmsge-python
• Support: [e-mail]