{"id":50112659,"url":"https://github.com/core-euler/tg_mailer","last_synced_at":"2026-05-23T13:05:57.653Z","repository":{"id":280424856,"uuid":"941917772","full_name":"core-euler/tg_mailer","owner":"core-euler","description":"Easy mailer for TG admins","archived":false,"fork":false,"pushed_at":"2025-03-03T17:24:59.000Z","size":57,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-28T18:54:06.712Z","etag":null,"topics":["aiogram","aiogram3","json","yaml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/core-euler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-03T09:18:17.000Z","updated_at":"2025-04-24T14:55:44.000Z","dependencies_parsed_at":"2025-03-03T11:30:51.923Z","dependency_job_id":"3992ab85-d839-43a0-8787-1429e90d950c","html_url":"https://github.com/core-euler/tg_mailer","commit_stats":null,"previous_names":["okoloboga/tg_mailer","core-euler/tg_mailer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/core-euler/tg_mailer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-euler%2Ftg_mailer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-euler%2Ftg_mailer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-euler%2Ftg_mailer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-euler%2Ftg_mailer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/core-euler","download_url":"https://codeload.github.com/core-euler/tg_mailer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/core-euler%2Ftg_mailer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33396646,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiogram","aiogram3","json","yaml"],"created_at":"2026-05-23T13:05:55.461Z","updated_at":"2026-05-23T13:05:57.646Z","avatar_url":"https://github.com/core-euler.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram Mailer Bot\n\nA Telegram bot built with Aiogram 3 to manage and schedule messages for Telegram channels. The bot allows an admin to send messages immediately, with a delay, or on a daily schedule to specified channels. It also supports editing and deleting scheduled tasks.\n\n## Features\n\n### Message Scheduling:\n- Send messages immediately.\n- Schedule messages with a delay (specific date and time).\n- Schedule daily recurring messages at a fixed time.\n\n### Channel Management:\n- Select a channel from a predefined list to send messages to.\n\n### Task Management:\n- Edit existing tasks (update message text or scheduled time).\n- Delete scheduled tasks.\n\n### Interactive Interface:\n- Uses inline keyboards for a seamless user experience.\n- Supports navigation with \"Back\" buttons.\n\n### Persistent Storage:\n- Tasks are stored in a `tasks.json` file for persistence across restarts.\n\n### Systemd Service:\n- Deployed as a systemd service for reliable operation on a Linux server.\n\n## Requirements\n\n- Python 3.7+\n- Aiogram 3.x (`aiogram`)\n- Pydantic (`pydantic`)\n- PyYAML (`pyyaml`)\n\n## Installation\n\n### Clone the Repository:\n```bash\ngit clone git@github.com:okoloboga/tg_mailer.git\ncd tg_mailer\n```\n\n### Set Up a Virtual Environment:\n```bash\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n```\n\n### Install Dependencies:\n```bash\npip install aiogram pydantic pyyaml\n```\n\n### Configure the Bot:\nCreate a `config.yaml` file in the project root with the following structure:\n```yaml\nbot:\n  token: \"your-bot-token-here\"  # Get this from @BotFather\nadmin:\n  id: \"your-admin-id-here\"  # Your Telegram user ID (find via @userinfobot)\nchannels:\n  - url: \"@yourchannel1\"\n    id: \"-100123456789\"  # Channel ID (find via @username_to_id_bot)\n  - url: \"@yourchannel2\"\n    id: \"-100987654321\"\n```\n\nEnsure the bot is added as an admin to the specified channels with permissions to send messages.\n\n### Run the Bot Locally (for testing):\n```bash\npython __main__.py\n```\n\n## Deployment with Systemd\n\nTo run the bot as a background service on a Linux server:\n\n### Copy the Project to the Server:\n```bash\nsudo mkdir -p /opt/tg_mailer\nsudo chown $USER:$USER /opt/tg_mailer\nscp -r . user@your-server-ip:/opt/tg_mailer\n```\n\n### Set Up the Environment on the Server:\n```bash\ncd /opt/tg_mailer\npython3 -m venv venv\nsource venv/bin/activate\npip install aiogram pydantic pyyaml\n```\n\n### Create a Systemd Service:\nCreate a service file:\n```bash\nsudo nano /etc/systemd/system/tg_mailer.service\n```\nAdd the following content (replace `user` with your username):\n```ini\n[Unit]\nDescription=Telegram Mailer Bot Service\nAfter=network.target\n\n[Service]\nType=simple\nUser=user\nWorkingDirectory=/opt/tg_mailer\nExecStart=/opt/tg_mailer/venv/bin/python /opt/tg_mailer/__main__.py\nRestart=always\nRestartSec=10\nEnvironment=\"PYTHONUNBUFFERED=1\"\n\n[Install]\nWantedBy=multi-user.target\n```\nSave and exit (Ctrl+O, Enter, Ctrl+X in nano).\n\n### Enable and Start the Service:\n```bash\nsudo systemctl daemon-reload\nsudo systemctl start tg_mailer\nsudo systemctl enable tg_mailer\n```\n\n### Check the Service Status:\n```bash\nsudo systemctl status tg_mailer\n```\nYou should see the bot running:\n```text\n● tg_mailer.service - Telegram Mailer Bot Service\n     Loaded: loaded (/etc/systemd/system/tg_mailer.service; enabled; vendor preset: enabled)\n     Active: active (running) since Mon 2025-03-03 12:00:00 UTC; 2s ago\n```\n\n### View Logs:\n```bash\njournalctl -u tg_mailer -f\n```\n\n## Usage\n\n### Start the Bot:\n- Send `/start` to the bot in Telegram.\n- If you're the admin (as specified in `config.yaml`), you'll see a menu with two options:\n  - **Create Task**: Start creating a new message.\n  - **Manage Tasks**: View, edit, or delete existing tasks.\n\n### Create a Task:\n1. Choose \"Create Task\" and follow the prompts:\n   - Enter the message text.\n   - Select the schedule type:\n     - **Immediate**: Sends the message right away.\n     - **Delayed**: Sends the message at a specific date and time.\n     - **Daily**: Sends the message every day at a fixed time.\n   - For \"Delayed\", select the date and time.\n   - For \"Daily\", select only the time.\n   - Choose the channel to send the message to.\n2. Once created, the task will be scheduled (or sent immediately for \"Immediate\").\n\n### Manage Tasks:\n- Choose \"Manage Tasks\" to see a list of scheduled tasks.\n- Select a task to:\n  - **Edit**: Update the message text or scheduled time.\n  - **Delete**: Remove the task.\n- Use the \"Back\" button to return to previous menus.\n\n## Project Structure\n\n- `__main__.py`: Entry point for the bot, initializes and starts the bot.\n- `config.py`: Handles configuration loading from `config.yaml`.\n- `handlers.py`: Contains all command and callback handlers for user interactions.\n- `keyboards.py`: Defines inline keyboards for interactive menus.\n- `utils.py`: Manages task storage (`tasks.json`) and the scheduling logic.\n- `config.yaml`: Configuration file for bot token, admin ID, and channels.\n- `tasks.json`: Persistent storage for scheduled tasks (created automatically).\n\n## Task Storage Format\n\nTasks are stored in `tasks.json` with the following structure:\n```json\n[\n    {\n        \"id\": 1,\n        \"message\": \"Hello, channel!\",\n        \"channel_id\": \"-100123456789\",\n        \"schedule_type\": \"daily\",\n        \"schedule_time\": \"12:00:00\",\n        \"status\": \"pending\",\n        \"last_sent_date\": \"2025-03-03\"\n    }\n]\n```\n\n## Known Issues\n\n- **Timezone**: The bot uses the server's local time. Ensure the server is set to the correct timezone (e.g., MSK for Moscow) to avoid scheduling issues.\n- **Task Migration**: If updating the bot, you may need to manually adjust the format of `schedule_time` in `tasks.json` for existing daily tasks.\n\n## Contributing\n\nFeel free to submit pull requests or open issues for bug reports and feature requests.\n\n## License\n\nThis project is licensed under the MIT License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcore-euler%2Ftg_mailer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcore-euler%2Ftg_mailer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcore-euler%2Ftg_mailer/lists"}