📬 Social Spam

Powerful Python package for messaging across multiple platforms

---

Simple • Powerful • Cross-Platform • Well-Documented

Supports: Telegram, VKontakte, WhatsApp, Email

✨ Features

📱 Supported Platforms 📧 Email - SMTP with attachments 💬 Telegram - Pyrogram 2.0+ support 🔵 VKontakte - Full API integration 📲 WhatsApp - Web automation

🎯 Key Features ✅ Easy to use - Simple and intuitive API 🚀 Async ready - Fast and efficient 📦 Bulk sending - Mass messaging support 🎨 Rich content - Text, images, files 🔄 Auto-retry - Built-in error handling 📊 Progress bars - Visual feedback

🆕 What's New in v1.3.0

🎉 Major Update - Completely modernized with 15+ new methods!

+ ✅ 15 new methods across all modules
+ ✅ Email: TLS, CC/BCC, Priority, Templates
+ ✅ Telegram: Documents, Video, Audio, Formatting, User Info
+ ✅ VKontakte: Documents, Audio, Friends, User Info
+ ✅ WhatsApp: File loading, Custom delays
+ ✅ Fixed all import issues (pywhatkit, Mail)
+ ✅ Python 3.8-3.12 support (including latest versions)
+ ✅ Pyrogram 2.0+ compatibility
+ ✅ TgCrypto now optional (better cross-platform support)
+ ✅ All dependencies updated to latest stable versions
+ ✅ Improved error handling and resource management

📖 See CHANGELOG.md for complete details

🌟 New Features Highlights

📧 Email - Enhanced

• TLS Support - Gmail, Outlook compatible (use_tls=True)
• Message Priority - Mark urgent/normal/low
• CC/BCC - Send copies to multiple recipients
• Templates - Use {{variables}} for personalization

💬 Telegram - Expanded

• Documents - Send PDFs, DOCX, ZIP, any files
• Video & Audio - MP4, MP3, and more
• Text Formatting - Markdown & HTML support
• User Info - Get detailed user profiles

🔵 VKontakte - Upgraded

• Documents - Share files with contacts
• Voice Messages - Send audio messages
• Friends API - Get and manage friends list
• User Profiles - Fetch detailed user information

📲 WhatsApp - Improved

• File Messages - Load from .txt/.md files
• Custom Delays - Fine-tune timing control

📦 Installation

# Install from PyPI (recommended)
pip install social-spam

# With optional Telegram speedup (TgCrypto)
pip install social-spam[telegram_speedup]

# Or install from GitHub for latest dev version
pip install -U https://github.com/neluckoff/social_spam/archive/master.zip

Requirements: Python 3.8+

Note: TgCrypto is optional. Telegram works fine without it, but it can be 2-3x faster for bulk operations. If installation fails on your system, the base package will work perfectly.

macOS users: Python 3.8 on macOS may have issues with pywhatkit dependencies (PyObjC requires 3.9+). We recommend Python 3.9+ for macOS.

---

🚀 Quick Start

📧 Email Example

from social_spam import Mail

# Initialize and connect (with TLS for Gmail)
mail = Mail()
mail.set_server('smtp.gmail.com', 587, use_tls=True)
mail.connect_mail('your@gmail.com', 'app_password')

# Send a simple message
mail.set_message('Hello!', 'How are you?')
mail.send_message('friend@gmail.com')

# Send with priority and CC
mail.set_message('Urgent!', 'Please review ASAP')
mail.set_priority('urgent')
mail.send_message_with_cc_bcc(
    to='boss@company.com',
    cc=['team@company.com']
)

# Use templates for personalization
template = "Hello {{name}}, your code is {{code}}"
mail.set_template_message('Code', template, {'name': 'John', 'code': '1234'})
mail.send_message('john@example.com')

💬 Telegram Example

from social_spam import Telegram

# Connect to Telegram
tg = Telegram()
tg.connect_user(
    api_id=12345,
    api_hash="your_api_hash",
    phone_number="+1234567890"
)

# Send formatted message with document
tg.send_message(
    user_id=123456789,
    message="**Important!** Read the `report.pdf`",
    document="report.pdf",
    parse_mode='markdown'
)

# Send video with caption
tg.send_message(
    user_id=123456789,
    message="Check out this video!",
    video="video.mp4"
)

# Get user information
user_info = tg.get_user_info(123456789)
print(f"User: {user_info['username']}, Premium: {user_info['is_premium']}")

# Mass messaging with formatting
user_ids = [111111, 222222, 333333]
tg.start_selective_spam(
    chats=user_ids,
    message="__Hello__ everyone!",
    parse_mode='markdown'
)

🔵 VKontakte Example

from social_spam import Vkontakte

# Connect with token
vk = Vkontakte()
vk.connect_user(token="your_vk_token")

# Send document
vk.send_message(
    user_id=123456,
    message="Вот файл",
    document="document.pdf"
)

# Get friends and send to all
friends = vk.get_friends()
friend_ids = [f['id'] for f in friends]
vk.start_selective_spam(
    chats=friend_ids,
    message="Привет всем друзьям!"
)

# Get user info
user_info = vk.get_user_info(123456)
print(f"User: {user_info['first_name']} {user_info['last_name']}")

📲 WhatsApp Example

from social_spam import WhatsApp

wa = WhatsApp()

# Load message from file
wa.set_file_message('message.txt')
wa.send_message(phone="+1234567890")

# Send with custom delays
wa.start_bombing(
    phone_number="+1234567890",
    amount=5,
    text="Hello!",
    wait_time=10,
    close_time=2
)

# Send with image
wa.send_message(
    phone="+1234567890",
    text="Check this out!",
    image="image.jpg"
)

---

📚 Documentation & Examples

Detailed examples for each platform:

Platform	Documentation	Example Code
📧 Email	Guide	Full SMTP integration with attachments
💬 Telegram	Guide	Pyrogram-based messaging
🔵 VKontakte	Guide	VK API integration
📲 WhatsApp	Guide	Web automation

---

🎯 Use Cases

• 📢 Bulk Notifications - Send updates to multiple recipients
• 🤖 Chatbots - Build automated messaging bots
• 📊 Marketing - Automated marketing campaigns
• 🔔 Alerts - System notifications and alerts
• 💼 Business - Customer communication
• 🎓 Educational - Learning messaging APIs

🛠️ Advanced Usage

Email with HTML Templates

mail = Mail()
mail.connect_mail('your_email@mail.ru', 'password')
mail.set_message_html('Newsletter', 'template.html', ['logo.png'])
mail.send_message('subscriber@example.com')

Telegram Batch Messaging

tg = Telegram()
tg.connect_user(api_id=12345, api_hash="hash", phone_number="+123456")

# Send to all your contacts
tg.start_all_spam(message="Important update!")

# Message bombing (use responsibly!)
tg.start_bombing(user_id=123456, amount=10, message="Hello!")

Custom SMTP Server with TLS

mail = Mail()
mail.set_server('smtp.gmail.com', 587, use_tls=True)  # TLS support
mail.connect_mail('your@gmail.com', 'app_password')

Telegram with Formatted Messages

tg = Telegram()
tg.connect_user(api_id=12345, api_hash="hash", phone_number="+123")

# Markdown formatting
message = """
**Important Announcement!**

__Details:__
• Item 1
• Item 2

Check the `report.pdf`
"""

tg.send_message(
    user_id=123456,
    message=message,
    document='report.pdf',
    parse_mode='markdown'
)

VKontakte Friends Management

vk = Vkontakte()
vk.connect_user(token="your_token")

# Get all friends
friends = vk.get_friends()
print(f"You have {len(friends)} friends")

# Send to specific friends
for friend in friends[:10]:
    vk.send_message(
        user_id=friend['id'],
        message=f"Привет, {friend['first_name']}!"
    )

---

🤝 Contributing

We love contributions! Here's how you can help:

• 🐛 Report Bugs
• 💡 Request Features
• 📝 Improve Documentation
• 🔧 Submit Pull Requests

Development Setup:

git clone https://github.com/neluckoff/social_spam.git
cd social_spam
pip install -r requirements.txt
pip install -e .

See CONTRIBUTING.md for detailed guidelines.

---

💬 Community & Support

💬 Type	🔗 Link
🐛 Bug Reports	Create Issue
💡 Feature Requests	Create Issue
❓ Questions	Ask Question
💬 Discussions	Join Discussion
📧 Email	neluckoff@gmail.com

---

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Copyright © 2022-2025 neluckoff

---

⭐ Show Your Support

If you find this project useful, please consider:

• ⭐ Starring the repository
• 🐦 Sharing it with others
• 💖 Sponsoring the development

Made with ❤️ by @neluckoff

⬆ Back to Top