🎫 Integração com Zammad

Configuração da integração entre Mailcow e Zammad para sistema de tickets via email

📋 Índice

Sobre a Integração
Conta de Email
Configuração IMAP no Zammad
Configuração SMTP no Zammad
Filtros e Regras
Testes
Monitorização

🔗 Sobre a Integração

O Zammad é o sistema de gestão de tickets da FSociety, integrado com Mailcow para receber e enviar tickets via email.

Arquitetura

┌────────────────────────────────────────────────┐
│         Cliente Externo                        │
│    (envia email para tickets@fsociety.pt)      │
└───────────────┬────────────────────────────────┘
                │
                ▼
┌────────────────────────────────────────────────┐
│            MAILCOW (10.0.0.20)                 │
│                                                │
│  ┌──────────┐         ┌──────────┐            │
│  │ POSTFIX  │ ──────→ │ DOVECOT  │            │
│  │  (SMTP)  │         │  (IMAP)  │            │
│  └──────────┘         └─────┬────┘            │
│                             │                  │
└─────────────────────────────┼──────────────────┘
                              │ IMAP:993
                              │
                ┌─────────────▼─────────────┐
                │  ZAMMAD (192.168.1.40)    │
                │                           │
                │  ┌──────────────────┐     │
                │  │  Email Channel   │     │
                │  │  (IMAP/SMTP)     │     │
                │  └──────────────────┘     │
                │           │               │
                │           ▼               │
                │  ┌──────────────────┐     │
                │  │  Ticket System   │     │
                │  └──────────────────┘     │
                └───────────────────────────┘
                              │
                              ▼
                ┌───────────────────────────┐
                │  Notificação para Agente  │
                └───────────────────────────┘

Fluxo de Funcionamento

Cliente envia email para tickets@fsociety.pt
Mailcow recebe email via Postfix
Email armazenado no Dovecot (IMAP)
Zammad consulta IMAP periodicamente
Novo ticket criado automaticamente no Zammad
Agente responde no Zammad
Resposta enviada via SMTP do Mailcow

📧 Conta de Email

Criar Mailbox no Mailcow

A conta tickets@fsociety.pt já está criada com as seguintes especificações:

Campo	Valor
Email	tickets@fsociety.pt
Password	`<senha_configurada>`
Quota	20 GB
Função	Receção de tickets Zammad
Domínio	fsociety.pt

Configurações Recomendadas

Quota: 20 GB (alto volume de tickets)
Archiving: Ativado (retenção de histórico)
Spam Filter: Reduzido (para não bloquear tickets legítimos)

Verificar Mailbox

# Via CLI Mailcow
sudo docker compose exec mysql-mailcow \
  mysql -u mailcow -p mailcow -e \
  "SELECT username, name, quota, active FROM mailbox WHERE username='tickets@fsociety.pt';"

Resultado esperado:

+----------------------+-------------------+-------+--------+
| username             | name              | quota | active |
+----------------------+-------------------+-------+--------+
| tickets@fsociety.pt  | Sistema Tickets   | 20480 | 1      |
+----------------------+-------------------+-------+--------+

📥 Configuração IMAP no Zammad

Aceder às Configurações Zammad

Login no Zammad:
- URL: https://zammad.fsociety.pt (via proxy nginx)
- User: admin
Navegar para Channels:
- Admin → Channels → Email

Adicionar Email Account

Tipo: IMAP

Configurações IMAP

Campo	Valor	Descrição
Inbound	IMAP	Protocolo de receção
Host	mail.fsociety.pt	Hostname do Mailcow
Port	993	Porta IMAP SSL
User	tickets@fsociety.pt	Conta completa
Password	`<senha_configurada>`	Password da mailbox
SSL/TLS	SSL	Encriptação
Folder	INBOX	Pasta a monitorizar

Configuração JSON (Referência)

{
  "adapter": "imap",
  "options": {
    "host": "mail.fsociety.pt",
    "port": 993,
    "ssl": true,
    "user": "tickets@fsociety.pt",
    "password": "SENHA_SEGURA",
    "folder": "INBOX",
    "keep_on_server": false,
    "ssl_verify": true
  }
}

Opções Avançadas

Keep on Server: false (mover emails processados para pasta Zammad)
Trusted: Yes
Active: Yes
Fetch Interval: 5 minutes

Teste de Conexão IMAP

Antes de configurar no Zammad, testar manualmente:

# Testar IMAP do servidor Zammad
openssl s_client -connect mail.fsociety.pt:993 -crlf

# Após conexão:
a1 LOGIN tickets@fsociety.pt SENHA_AQUI
a2 LIST "" "*"
a3 SELECT INBOX
a4 LOGOUT

📤 Configuração SMTP no Zammad

Configurações SMTP

Campo	Valor	Descrição
Outbound	SMTP	Protocolo de envio
Host	mail.fsociety.pt	Hostname do Mailcow
Port	587	Porta SMTP Submission
User	tickets@fsociety.pt	Conta completa
Password	`<senha_configurada>`	Password da mailbox
Authentication	Plain	Método de autenticação
SSL/TLS	STARTTLS	Encriptação

Configuração JSON (Referência)

{
  "adapter": "smtp",
  "options": {
    "host": "mail.fsociety.pt",
    "port": 587,
    "start_tls": true,
    "user": "tickets@fsociety.pt",
    "password": "SENHA_SEGURA",
    "authentication": "plain"
  }
}

Teste de Envio

# Testar SMTP manualmente
openssl s_client -connect mail.fsociety.pt:587 -starttls smtp

# Após conexão:
EHLO zammad.fsociety.pt
AUTH PLAIN <base64_credentials>
MAIL FROM:<tickets@fsociety.pt>
RCPT TO:<test@example.com>
DATA
Subject: Test

Test message
.
QUIT

Verificar Envio no Zammad

Admin → Channels → Email → Test
Enviar email de teste
Verificar se chegou corretamente

🔧 Filtros e Regras

Filtro Anti-Spam no Zammad

# Ignorar emails com score alto de spam
if email.header['X-Spam-Status'] =~ /Yes/
  reject("Spam detected")
end

Auto-Assignment

Configurar regras no Zammad para distribuir tickets:

Se: Email de cliente@empresa.com
Então: Atribuir a → ryan.barbosa@fsociety.pt

Se: Subject contém "urgente"
Então: 
  - Prioridade → Alta
  - Atribuir a → ti@fsociety.pt

Configuração no Mailcow

Whitelist para tickets@fsociety.pt

# Desativar greylisting para tickets
sudo nano /opt/mailcow-dockerized/data/conf/rspamd/local.d/greylist.conf

whitelist_rcpt = [
  "tickets@fsociety.pt"
];

Reduzir Score Anti-spam

sudo nano /opt/mailcow-dockerized/data/conf/rspamd/local.d/multimap.conf

WHITELIST_TICKETS {
  type = "rcpt";
  map = "tickets@fsociety.pt";
  score = -5.0;
  description = "Whitelist para sistema de tickets";
}

✅ Testes

Teste Completo de Integração

1. Enviar Email de Teste

# De outro servidor ou Gmail
echo "Teste de ticket" | mail -s "Ticket de Teste" tickets@fsociety.pt

2. Verificar Receção no Mailcow

# Ver logs do Postfix
sudo docker compose logs postfix-mailcow | grep tickets@fsociety.pt

# Verificar que email chegou ao Dovecot
sudo docker compose exec dovecot-mailcow \
  doveadm search -u tickets@fsociety.pt ALL

3. Verificar Criação de Ticket no Zammad

Aceder ao Zammad Web UI
Verificar se novo ticket foi criado
Ticket ID: #12345
Status: open

4. Responder Ticket

Adicionar resposta no Zammad
Verificar se email foi enviado via SMTP

5. Verificar Logs de Envio

# Ver logs SMTP do Mailcow
sudo docker compose logs postfix-mailcow | grep "from=<tickets@fsociety.pt>"

Checklist de Verificação

Email recebido no Mailcow
Email processado pelo Zammad (ticket criado)
Resposta enviada do Zammad via Mailcow
Cliente recebeu resposta
Thread de conversa mantida (In-Reply-To header)

📊 Monitorização

Ver Status da Integração

No Zammad:

Admin → Channels → Email
Ver status da conexão IMAP/SMTP
Ver últimos emails processados

Logs do Zammad

# No servidor Zammad (192.168.1.40)
tail -f /opt/zammad/log/production.log | grep -i "channel::email"

Logs do Mailcow

# Logs IMAP (conexões do Zammad)
sudo docker compose logs dovecot-mailcow | grep tickets@fsociety.pt

# Logs SMTP (envios do Zammad)
sudo docker compose logs postfix-mailcow | grep "from=<tickets@fsociety.pt>"

Métricas

# Emails na mailbox tickets
sudo docker compose exec dovecot-mailcow \
  doveadm mailbox status -u tickets@fsociety.pt messages INBOX

# Quota utilizada
sudo docker compose exec dovecot-mailcow \
  doveadm quota get -u tickets@fsociety.pt

Alertas

Configurar alertas para:

Mailbox próxima da quota (>80%)
Falhas de conexão IMAP/SMTP
Emails não processados (>30 min)

🔧 Troubleshooting

Zammad não recebe emails

Verificar:

Conexão IMAP no Zammad
Logs do Zammad
Emails chegam ao Mailcow?
Firewall bloqueia 192.168.1.40 → 10.0.0.20:993?

# Testar conectividade do Zammad
# No servidor Zammad:
telnet mail.fsociety.pt 993

Emails enviados vão para spam

Verificar:

SPF/DKIM/DMARC configurados
IP não em blacklist
Reverse DNS configurado

Performance Lenta

Otimizações:

Aumentar intervalo de fetch (10 min em vez de 5 min)
Limpar emails antigos da mailbox
Aumentar quota se necessário

🎓 Informação Académica

Campo	Informação
Instituição	ESTG - Instituto Politécnico do Porto
Unidade Curricular	Administração de Sistemas II
Ano Letivo	2025/2026
Autores	Ryan Barbosa, Hugo Correia, Igor Araújo

**[⬅️ Anterior: Backup](/fsociety-infrastructure/08-mailcow/08-backup.html)** | **[Índice](/fsociety-infrastructure/08-mailcow/)** | **[Próximo: Manutenção ➡️](/fsociety-infrastructure/08-mailcow/10-manutencao.html)**

Última atualização: Dezembro 2025