Instagram Outreach Automation Tool

A powerful Flask-based web application for automating Instagram cold outreach campaigns with advanced follow-up sequences, Google Sheets integration, and comprehensive tracking capabilities.

Key Features

Core Functionality

• Multi-Message Campaigns: Create sophisticated follow-up sequences with multiple messages
• Smart Tracking: Monitor message delivery, read status, and replies
• Google Sheets Integration: Import contacts and sync tracking data with Google Sheets
• Variable Substitution: Personalize messages with dynamic variables from your contact data
• Rate Limiting: Built-in protection to maintain account health
• Campaign Management: Create, edit, duplicate, and manage multiple outreach campaigns
• Real-time Dashboard: Monitor campaign progress with live updates

Advanced Features

• Google Drive Integration: Browse and select contact lists directly from Google Drive
• Tracking Status Columns: Automatically update Google Sheets with message statuses
• 2FA Support: Handle two-factor authentication for Instagram accounts
• Session Management: Persistent login sessions to avoid repeated authentication
• Pause/Resume: Control campaign execution without losing progress
• Bulk Operations: Process hundreds of contacts efficiently

Prerequisites

• Python 3.7+
• Instagram account(s) for sending messages
• Google Cloud Service Account (for Google Sheets integration)
• Modern web browser

Installation

1. Clone the Repository

git clone https://github.com/yourusername/instagram-outreach.git
cd instagram-outreach

2. Set Up Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

Copy the example environment file and configure your credentials:

cp .env.example .env

Edit .env with your settings:

# Instagram Credentials
INSTAGRAM_USERNAME=your_username
INSTAGRAM_PASSWORD=your_password

# Rate Limiting
DM_PER_HOUR=40
DM_PER_DAY=150
DELAY_BETWEEN_DMS=180  # seconds

# Dashboard
DASHBOARD_PORT=8000

5. Set Up Google Sheets Integration

Create a Google Cloud Service Account:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable Google Sheets API and Google Drive API
4. Create a Service Account and download the credentials JSON
5. Save the file as google_credentials.json in the project root

Share Your Google Sheets:

Share your Google Sheets with the service account email (found in google_credentials.json)

Usage

Starting the Application

python app.py

Open http://localhost:8000 in your browser

Main Features

1. Message Tracking

Navigate to the main dashboard to:

• Upload CSV/Excel files with Instagram usernames
• Connect to Google Sheets
• Track message statuses (sent, seen, replied)
• Export tracking results

2. Outreach Campaigns

Go to the Outreach page to:

• Run single-message campaigns
• Execute multi-message follow-up sequences
• Monitor real-time progress
• Pause/resume campaigns

3. Campaign Management

Access the Campaigns section to:

• Create new campaign templates
• Define follow-up sequences
• Set rate limits per campaign
• Use variables for personalization

File Format Requirements

Your contact files (CSV, Excel, or Google Sheets) must include:

• An "instagram" column with usernames or profile URLs
• Additional columns for personalization variables (optional)

Example CSV structure:

instagram,name,company,city
@john_doe,John,Acme Inc,New York
https://instagram.com/jane_smith,Jane,Tech Corp,San Francisco

Campaign Configuration

Creating a Campaign

1. Navigate to Campaigns → New Campaign
2. Set campaign name and description
3. Add messages to your sequence
4. Configure delays between messages
5. Set rate limits

Using Variables

Include variables in your messages using double curly braces:

Hey {{name}}, I noticed you're based in {{city}}...

The system will automatically map these to your contact data columns.

API Endpoints

• GET / - Main dashboard
• GET /outreach - Outreach campaign page
• GET /campaigns - Campaign management
• POST /track - Track message statuses
• POST /start_outreach - Start campaign
• POST /pause_outreach - Pause campaign
• POST /resume_outreach - Resume campaign
• POST /stop_outreach - Stop campaign
• GET /api/campaigns - List all campaigns
• POST /api/campaigns - Create campaign
• PUT /api/campaigns/<id> - Update campaign
• DELETE /api/campaigns/<id> - Delete campaign

Project Structure

instagram-outreach/
├── app.py                      # Main Flask application
├── instagram_client.py         # Instagram API wrapper
├── campaign_manager.py         # Campaign CRUD operations
├── campaign_tracking.py        # Tracking status management
├── variable_substitution.py    # Variable replacement logic
├── google_drive_client.py      # Google Drive/Sheets integration
├── templates/
│   ├── dashboard.html         # Main tracking dashboard
│   ├── outreach.html         # Outreach campaign UI
│   ├── campaigns.html        # Campaign list view
│   └── campaign_editor.html  # Campaign editor
├── static/                    # CSS and JavaScript files
├── campaigns/                 # Campaign JSON storage
├── requirements.txt          # Python dependencies
├── .env.example             # Environment variables template
└── README.md               # This file

Safety & Best Practices

Instagram actively monitors for automated behavior. Follow these guidelines to protect your account from restrictions, action blocks, or permanent bans.

Rate Limiting

• Start with conservative limits (10-20 DMs per hour)
• Gradually increase based on account age and activity
• Use longer delays between messages for new accounts

Account Health

• Warm up new accounts slowly over 2-3 weeks
• Mix automated outreach with manual activity
• Monitor for action blocks or restrictions

Proxy Usage (Highly Recommended)

Why Use Proxies?

• Prevents Instagram from linking multiple accounts to the same IP
• Reduces risk of all accounts being banned simultaneously
• Masks your location and makes activity appear more natural
• Essential for running multiple accounts safely

Proxy Recommendations

1. Residential Proxies (STRONGLY RECOMMENDED)

• Use high-quality residential proxies from reputable providers
• Avoid datacenter proxies - Instagram detects and flags them
• Providers: Bright Data, Smartproxy, Soax, Proxy-Seller

2. One Account Per IP

• NEVER use the same IP for multiple Instagram accounts
• Each account should have a dedicated proxy/IP address
• Keep IP consistent per account (don't rotate IPs for same account)

3. Configuration

• Configure proxy in your Instagram client settings
• Test proxy connection before running campaigns
• Monitor proxy health and rotate if needed
• Use proxies from the same country as your account's registered location

Account Warming Strategy

• Browse feed for 5-10 minutes
• Like 10-20 posts manually
• Follow 5-10 accounts
• Comment on 2-3 posts
• View 5-10 stories
• Continue manual activity
• Gradually increase by 3-5 DMs every 2-3 days
• Never go from 0 to high volume instantly

Multi-Account Strategy

If running large campaigns across multiple accounts:

1. Account Separation

• Use different proxies for each account
• Different email addresses
• Different phone numbers for verification
• Don't follow same accounts across profiles

2. Stagger Activity

• Don't run all accounts simultaneously
• Randomize start times
• Different daily volumes per account

Monitoring & Response

1. Daily Checks

• Monitor for action blocks or warnings
• Check email for Instagram notifications
• Verify messages are being delivered
• Track reply rates (low rates may indicate shadow ban)

2. If You Get Action Blocked

• STOP all automation immediately
• Wait 24-48 hours before any activity
• Resume at 50% previous volume
• Increase manual activity
• Consider it a warning - adjust strategy

Message Personalization

• Always personalize messages with recipient data (name, company, etc.)
• Avoid generic, spam-like content
• Keep messages conversational and authentic
• Test different message variations

Recommended Configuration Example

For a 3-month-old account:

DM_PER_HOUR=15
DM_PER_DAY=50
DELAY_BETWEEN_DMS=180  # 3 minutes

Can increase with time and experiment

Troubleshooting

Common Issues

Login Failed

• Verify Instagram credentials in .env
• Check for 2FA requirements
• Try deleting session files and re-authenticating

Google Sheets Not Loading

• Ensure google_credentials.json is present
• Verify the sheet is shared with service account
• Check API quotas in Google Cloud Console

Messages Not Sending

• Check rate limits haven't been exceeded
• Verify Instagram account isn't restricted
• Ensure target usernames are valid

Tracking Not Updating

• Confirm Google Sheets has write permissions
• Check for protected status values
• Verify column names match expected format

Security Considerations

• Never commit credentials to version control
• Use environment variables for sensitive data
• Regularly rotate Instagram passwords
• Limit Google Service Account permissions
• Use HTTPS in production environments

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

License

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

Disclaimer

This tool is for educational and legitimate business outreach purposes only. Users are responsible for:

• Complying with Instagram's Terms of Service
• Respecting privacy and anti-spam regulations
• Using the tool ethically and responsibly

Misuse may result in account restrictions or legal consequences.

Support

For issues, questions, or contributions:

• Open an issue on GitHub
• Check existing documentation
• Review closed issues for solutions

Acknowledgments

• Built with Flask, Instagrapi, and Google APIs
• Inspired by ethical outreach automation needs
• Community contributions and feedback