EN: A robust and automated system for mass email delivery using Python, organized JSON queues, high customization, real-time logs, and advanced control of email processing. PT-BR: Um sistema robusto e automatizado para envio massivo de e-mails utilizando Python, filas organizadas em arquivos JSON, alta personalização, logs em tempo real e controle avançado dos envios.
Python Bulk Email Sender is a fully automated batch email system designed to send large volumes of personalized emails using a structured workflow. It processes tasks stored in JSON files, sends emails sequentially, generates detailed logs, handles errors intelligently, supports secure SMTP authentication, and ensures a stable and scalable emailing pipeline.
Python Bulk Email Sender é um sistema totalmente automatizado para envio massivo de e-mails, projetado para enviar grandes quantidades de mensagens personalizadas usando um fluxo de trabalho organizado. Ele processa tarefas salvas em arquivos JSON, envia e-mails de maneira sequencial, gera logs detalhados, lida com erros de forma inteligente, permite autenticação SMTP segura e garante um fluxo de envio estável e escalável.
Each email is represented as a JSON file containing:
id— task IDsender— email and SMTP settingsrecipient— destination emailsubject— subject linemessage— text or HTMLattachment(optional) — file pathstatus— pending/sent/errortimestamp— creation date
All tasks are stored inside the queue folder fila/.
Cada e-mail é representado como um arquivo JSON contendo:
id— identificador da tarefasender— e-mail e configuração SMTPrecipient— destinatáriosubject— assuntomessage— texto ou HTMLattachment(opcional) — arquivostatus— pendente/enviado/errotimestamp— data de criação
As tarefas ficam na pasta fila/.
When the script runs, it:
- Reads all files inside
fila/ - Validates JSON structures
- Loads each task into memory
- Adds everything to the processing queue
Invalid JSON files are ignored and logged.
Ao iniciar, o script:
- Lê todos os arquivos dentro de
fila/ - Valida a estrutura JSON
- Carrega cada tarefa na memória
- Adiciona tudo à fila de processamento
JSON inválido é ignorado e registrado nos logs.
Supports all SMTP providers:
- Gmail
- Outlook / Hotmail
- Yahoo
- Custom domains
- Corporate SMTP servers
The script validates:
- SMTP host
- Port
- Login
- Password
- TLS/SSL
If authentication fails, the task is marked as error and logged.
Suporta qualquer provedor SMTP:
- Gmail
- Outlook / Hotmail
- Yahoo
- Domínios próprios
- Servidores empresariais
O script valida:
- Host SMTP
- Porta
- Login
- Senha
- TLS/SSL
Se falhar, a tarefa recebe status erro e é registrada no log.
The system builds the message using:
- MIMEText
- MIMEMultipart
- MIMEBase
Supports:
- Plain text
- HTML
- Mixed content
- Attachments of any type
O sistema monta o e-mail usando:
- MIMEText
- MIMEMultipart
- MIMEBase
Suporta:
- Texto simples
- HTML
- Conteúdo misto
- Anexos de qualquer tipo
Each email is sent sequentially:
- Open SMTP connection
- Authenticate
- Build message
- Send email
- Close connection
If an error occurs, the script:
- Logs the error
- Updates task to
"error" - Continues processing next tasks
Cada e-mail é enviado de forma sequencial:
- Abre a conexão SMTP
- Autentica
- Monta a mensagem
- Envia o e-mail
- Fecha a conexão
Se ocorrer erro, o script:
- Registra o erro
- Atualiza a tarefa para
"error" - Continua o processamento normalmente
Logs generated:
sent.log— successful emailserror.log— failed taskssystem.log— script activity
Each entry includes:
- Task ID
- Recipient
- Timestamp
- SMTP server used
- Error traceback
Logs gerados:
sent.log— envios bem-sucedidoserror.log— falhassystem.log— atividades do sistema
Cada entrada contém:
- ID da tarefa
- Destinatário
- Data e hora
- Servidor SMTP
- Descrição da falha
After each attempt:
- Success →
"sent" - Failure →
"error"+ reason
JSON files are never deleted automatically.
Após cada tentativa:
- Sucesso →
"sent" - Falha →
"error"+ motivo
O JSON nunca é apagado automaticamente.
The script can:
- Run once
- Or monitor the queue continuously
Useful for:
- CRON
- Background processes
- Automatic pipelines
O script pode:
- Rodar apenas uma vez
- Ou monitorar a fila continuamente
Ideal para:
- CRON
- Processos em background
- Pipelines automáticos
- Bulk email sending
- JSON queue system
- Error-resistant workflow
- Full logging
- Attachments
- Secure SMTP
- HTML support
- Continuous mode
- Envio massivo de e-mails
- Fila baseada em JSON
- Fluxo resiliente a erros
- Logs completos
- Suporte a anexos
- SMTP seguro
- HTML
- Modo contínuo
git clone https://github.com/henriquetourinho/Python-Bulk-Email-Sender
cd Python-Bulk-Email-Sender
pip install -r requirements.txt
python3 sender.py{
"id": 1,
"sender": {
"email": "example@gmail.com",
"password": "password",
"smtp": "smtp.gmail.com",
"port": 587
},
"recipient": "client@example.com",
"subject": "Hello!",
"message": "<h1>Welcome!</h1>",
"attachment": "file.pdf",
"status": "pending",
"timestamp": "2025-11-27 10:00:00"
}Distributed under the GPL-3.0 License. Distribuído sob a Licença GPL-3.0.
Carlos Henrique Tourinho Santana — Salvador, Bahia 🔗 Debian Wiki: https://wiki.debian.org/henriquetourinho 🔗 LinkedIn: https://br.linkedin.com/in/carloshenriquetourinhosantana 🔗 GitHub: https://github.com/henriquetourinho