---
title: "Conector Mailgun"
description: "Guia completo de integração do Mailgun para sincronizar dados de entrega de e-mail, métricas de engajamento e eventos de e-mail transacional com o Brevo através do Tajo."
url: https://tajo.io/pt/docs/connectors/marketing/mailgun/
markdown: https://tajo.io/pt/docs/connectors/marketing/mailgun.md
lang: pt-BR
robots: noindex
---

Solicite acesso antecipado

Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo.

# Conector Mailgun

Status do conector: Planejado Ainda não construído. O Tajo não executa este conector hoje.

| Campo de origem | Campo de destino | Valor de exemplo |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Conecte o Mailgun ao Brevo através do Tajo para unificar seus dados de e-mail transacional e de marketing, sincronizar eventos de entrega e métricas de engajamento, e consolidar sua infraestrutura de e-mail em uma única visão do cliente.

## Visão geral

| Propriedade | Valor |
| --- | --- |
| **Plataforma** | Mailgun (by Sinch) |
| **Categoria** | E-mail Marketing |
| **Complexidade de configuração** | Fácil |
| **Integração oficial** | Não |
| **Dados sincronizados** | Eventos, Contatos, Entregabilidade, Campanhas |
| **Método de autenticação** | Chave API (HTTP Basic Auth) |

## Recursos

- **Sincronização de eventos de entrega** - Rastreie eventos de entregue, com bounce, aberto e clicado
- **Métricas de engajamento** - Sincronize taxas de abertura e clique para atributos de contato do Brevo
- **Gestão de bounces** - Suprima automaticamente endereços com bounce no Brevo
- **Tratamento de reclamações** - Sincronize reclamações de spam para higiene de lista
- **Reputação de domínio** - Monitore a saúde do domínio de envio e a entregabilidade
- **Rastreamento de e-mail transacional** - Correlacione envios transacionais com dados de marketing

## Pré-requisitos

Antes de começar, certifique-se de ter:

1. Uma conta Mailgun com um domínio de envio verificado
2. Uma chave API do Mailgun no [Mailgun Dashboard](https://app.mailgun.com/settings/api_security)
3. Uma conta Brevo com acesso à API
4. Uma conta Tajo com permissões de conector

## Autenticação

### Autenticação por chave API

O Mailgun usa HTTP Basic Authentication com `api` como nome de usuário e sua chave API como senha:

```bash
# Get your API key from https://app.mailgun.com/settings/api_security
export MAILGUN_API_KEY=key-your-api-key
export MAILGUN_DOMAIN=your-domain.com
export TAJO_API_KEY=your_tajo_api_key
export BREVO_API_KEY=your_brevo_api_key
```

```javascript
// HTTP Basic Auth format
const headers = {
  'Authorization': `Basic ${Buffer.from(
    `api:${process.env.MAILGUN_API_KEY}`
  ).toString('base64')}`
};

// Or using curl
// curl -s --user 'api:YOUR_API_KEY' ...
```

Tipos de chave API

O Mailgun fornece chaves de envio específicas de domínio e chaves API de nível de conta. Use chaves de envio de domínio para operações de mensagem e a chave API da conta para operações de gerenciamento.

## Configuração

### Configuração básica

```yaml
connectors:
  mailgun:
    enabled: true
    api_key: "${MAILGUN_API_KEY}"
    domain: "${MAILGUN_DOMAIN}"
    region: "us"  # or "eu" for EU region

    sync:
      events: true
      contacts: true
      bounces: true
      complaints: true
      schedule: "*/15 * * * *"  # Every 15 minutes

    webhook:
      signing_key: "${MAILGUN_WEBHOOK_SIGNING_KEY}"

    lists:
      engaged: 30
      bounced: 31
      complained: 32
```

### Mapeamento de campos

```yaml
field_mapping:
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  open_rate: MG_OPEN_RATE
  click_rate: MG_CLICK_RATE
  last_delivered: MG_LAST_DELIVERED
  bounce_type: MG_BOUNCE_TYPE
  engagement_score: MG_ENGAGEMENT
  unsubscribed: MG_UNSUBSCRIBED
```

## Endpoints da API

| Endpoint | Método | Descrição |
| --- | --- | --- |
| `https://api.mailgun.net/v3/{domain}/messages` | POST | Enviar mensagens de e-mail |
| `https://api.mailgun.net/v3/{domain}/events` | GET | Consultar logs de eventos |
| `https://api.mailgun.net/v3/{domain}/bounces` | GET | Listar bounces |
| `https://api.mailgun.net/v3/{domain}/complaints` | GET | Listar reclamações |
| `https://api.mailgun.net/v3/{domain}/unsubscribes` | GET | Listar descadastros |
| `https://api.mailgun.net/v3/{domain}/tags` | GET | Listar tags |
| `https://api.mailgun.net/v3/{domain}/tags/{tag}/stats` | GET | Obter estatísticas de tag |
| `https://api.mailgun.net/v3/lists` | GET | Listar mailing lists |
| `https://api.mailgun.net/v3/domains` | GET | Listar domínios |
| `https://api.mailgun.net/v4/address/validate` | POST | Validar endereço de e-mail |

Região da UE

Para contas Mailgun baseadas na UE, use `https://api.eu.mailgun.net` em vez de `https://api.mailgun.net` para todos os endpoints da API.

## Exemplos de código

### Inicializar o conector

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('mailgun', {
  apiKey: process.env.MAILGUN_API_KEY,
  domain: process.env.MAILGUN_DOMAIN,
  region: 'us'
});
```

### Enviar uma mensagem via Mailgun API

```javascript
// Send an email using Mailgun's Messages API
const formData = new URLSearchParams();
formData.append('from', `Your App <noreply@${domain}>`);
formData.append('to', 'recipient@example.com');
formData.append('subject', 'Welcome to our platform');
formData.append('html', '<h1>Welcome!</h1><p>Thanks for signing up.</p>');
formData.append('o:tag', 'welcome-email');
formData.append('o:tracking', 'yes');

const response = await fetch(
  `https://api.mailgun.net/v3/${domain}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${Buffer.from(`api:${apiKey}`).toString('base64')}`
    },
    body: formData
  }
);

const result = await response.json();
// { id: '<message-id@domain.com>', message: 'Queued. Thank you.' }
```

### Sincronizar eventos de e-mail para o Brevo

```javascript
// Query Mailgun events and sync engagement data
const eventsResponse = await fetch(
  `https://api.mailgun.net/v3/${domain}/events?` +
    new URLSearchParams({
      begin: lastSyncDate,
      ascending: 'yes',
      limit: 300,
      event: 'delivered OR opened OR clicked'
    }),
  {
    headers: {
      'Authorization': `Basic ${Buffer.from(`api:${apiKey}`).toString('base64')}`
    }
  }
);

const { items, paging } = await eventsResponse.json();

for (const event of items) {
  const email = event.recipient;

  switch (event.event) {
    case 'delivered':
      await tajo.contacts.update(email, {
        attributes: { MG_LAST_DELIVERED: event.timestamp }
      });
      break;
    case 'opened':
      await tajo.events.track({
        email,
        event: 'email_opened',
        properties: { subject: event.message.headers.subject }
      });
      break;
    case 'clicked':
      await tajo.events.track({
        email,
        event: 'email_clicked',
        properties: { url: event.url }
      });
      break;
  }
}

// Follow pagination for more events
if (paging.next) {
  // Fetch next page using paging.next URL
}
```

### Tratar webhooks do Mailgun

```javascript
const crypto = require('crypto');

app.post('/webhooks/mailgun', async (req, res) => {
  // Verify webhook signature
  const { timestamp, token, signature } = req.body.signature;
  const encodedToken = crypto
    .createHmac('sha256', process.env.MAILGUN_WEBHOOK_SIGNING_KEY)
    .update(timestamp.concat(token))
    .digest('hex');

  if (encodedToken !== signature) {
    return res.status(401).send('Unauthorized');
  }

  const eventData = req.body['event-data'];
  const event = eventData.event;
  const email = eventData.recipient;

  await tajo.connectors.handleWebhook('mailgun', {
    topic: event,
    payload: eventData
  });

  // Handle bounce suppression
  if (event === 'failed' && eventData.severity === 'permanent') {
    await tajo.contacts.update(email, {
      attributes: { MG_BOUNCE_TYPE: 'hard_bounce' },
      emailBlacklisted: true
    });
  }

  res.status(200).send('OK');
});
```

### Sincronizar bounces e reclamações

```javascript
// Sync bounced addresses for list hygiene
const bouncesResponse = await fetch(
  `https://api.mailgun.net/v3/${domain}/bounces?limit=100`,
  {
    headers: {
      'Authorization': `Basic ${Buffer.from(`api:${apiKey}`).toString('base64')}`
    }
  }
);

const { items: bounces } = await bouncesResponse.json();

for (const bounce of bounces) {
  await tajo.contacts.update(bounce.address, {
    attributes: {
      MG_BOUNCE_TYPE: bounce.error.includes('550') ? 'hard_bounce' : 'soft_bounce',
      MG_BOUNCE_DATE: bounce.created_at
    },
    emailBlacklisted: bounce.error.includes('550')
  });
}
```

## Limites de taxa

| Endpoint | Limite | Observações |
| --- | --- | --- |
| Messages API | Varia por plano | 100/hora (grátis), ilimitado (pagos) |
| Events API | Sem limite explícito | Use paginação com máx. 300 itens |
| Validation API | Baseado no plano | Pagamento por validação |
| Webhooks | Tempo real | Sem limite de taxa na entrega |
| Suppressions API | Sem limite explícito | Aplica-se rate limiting padrão |

Limites de envio

O Mailgun aplica limites de envio baseados no seu plano e na reputação do domínio. Novos domínios começam com limites menores que aumentam conforme a reputação do remetente melhora. Monitore as estatísticas do seu domínio no dashboard do Mailgun.

## Solução de problemas

| Problema | Causa | Solução |
| --- | --- | --- |
| 401 Unauthorized | Chave API inválida | Verifique a chave API no dashboard do Mailgun |
| Domínio não verificado | Registros DNS ausentes | Adicione os registros TXT, CNAME, MX necessários |
| Webhook não recebido | URL não acessível | Certifique-se de que a URL do webhook seja acessível publicamente |
| Eventos ausentes | Intervalo de tempo muito estreito | Expanda os parâmetros `begin`/`end` |
| Baixa entregabilidade | Reputação de domínio | Verifique as estatísticas do domínio e a autenticação |

### Modo de depuração

```yaml
connectors:
  mailgun:
    debug: true
    log_level: verbose
    log_webhooks: true
    log_events: true
```

## Melhores práticas

1. **Verifique domínios de envio** - Complete a verificação DNS para entregabilidade ideal
2. **Use webhooks para eventos** - Entrega de webhook em tempo real vs. polling da Events API
3. **Trate bounces proativamente** - Suprima hard bounces imediatamente no Brevo
4. **Marque suas mensagens com tags** - Use tags para categorizar e analisar o desempenho de e-mail
5. **Monitore a reputação do domínio** - Acompanhe métricas de entregabilidade no dashboard do Mailgun
6. **Use validação de e-mail** - Valide endereços antes de adicioná-los a listas do Brevo

## Segurança

- **HTTP Basic Auth** - Chave API transmitida via cabeçalho Authorization
- **Assinaturas de webhook** - Verificação de assinatura HMAC-SHA256
- **Verificação de domínio** - Autenticação DNS SPF, DKIM e DMARC
- **IP whitelisting** - Disponível para planos de IP dedicado
- **Criptografia TLS** - Todos os endpoints da API exigem HTTPS
- **Rotação de chave** - Rotacione as chaves API periodicamente via dashboard do Mailgun

## Recursos relacionados

- [Conector Brevo](https://tajo.io/pt/docs/connectors/marketing/brevo)
- [Conector Segment](https://tajo.io/pt/docs/connectors/custom/segment)
- [Skill de sincronização de clientes](https://tajo.io/pt/docs/skills/data-sync/customer-sync)
- [Documentação da API do Mailgun](https://documentation.mailgun.com/)