# Mailgun API

O **Mailgun API** integra-se ao [serviço de entrega de emails do Mailgun](https://documentation.mailgun.com/), permitindo o envio de emails com destinatários, assuntos e conteúdos personalizados, incluindo anexos. Ela auxilia na automação de notificações, emails transacionais e mensagens de marketing dentro dos seus pipelines.

## **Parâmetros**

Dê uma olhada nos parâmetros de configuração do conector. Parâmetros suportados por [expressões Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview) estão marcados com `(DB)`.

### **Aba General**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Account</strong></td><td>A conta usada pelo conector. Tipo suportado: <strong>Basic</strong>.</td><td>N/A</td><td>Account</td></tr><tr><td><strong>Fail On Error</strong></td><td>Se a opção for ativada, a execução do pipeline com erro será interrompida. Caso contrário, a execução do pipeline continua, mas o resultado mostrará um valor falso para a propriedade <code>"success"</code>.</td><td>False</td><td>Booleano</td></tr></tbody></table>

### **Aba Host**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Host</strong> <code>(DB)</code></td><td>A URL base da API do Mailgun.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Path</strong></td><td>O endpoint específico do Mailgun a ser acessado. O caminho selecionado pode determinar opções adicionais de configuração, como parâmetros de consulta. Para detalhes sobre cada endpoint, consulte a <a href="https://documentation.mailgun.com/docs/mailgun/api-reference/">documentação da API do Mailgun</a>.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Method</strong></td><td>O método HTTP usado para a solicitação.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Multi Part Data</strong> <code>(DB)</code></td><td>Dados Multi Part a serem enviados na chamada REST.</td><td>N/A</td><td>JSON</td></tr></tbody></table>

### **Aba Settings**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Connect Timeout (ms)</strong></td><td>Tempo máximo permitido para estabelecer uma conexão, em milissegundos.</td><td>30000</td><td>Integer</td></tr><tr><td><strong>Read Timeout (ms)</strong></td><td>Tempo máximo permitido para ler dados, em milissegundos.</td><td>30000</td><td>Integer</td></tr><tr><td><strong>Stop on Client Error</strong></td><td>Quando ativado, interrompe a execução do pipeline se ocorrer um erro HTTP 4xx.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Stop on Server Error</strong></td><td>Quando ativado, interrompe a execução do pipeline se ocorrer um erro HTTP 5xx.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Override Response Charset</strong></td><td>Quando ativado, substitui o charset retornado pelo endpoint especificado na propriedade <strong>Response Charset</strong>. Caso contrário, o charset do cabeçalho <strong>Content-Type</strong> é usado.</td><td>True</td><td>Booleano</td></tr><tr><td><strong>Response Charset</strong></td><td>Define o charset a ser utilizado quando <strong>Override Response Charset</strong> estiver ativado. Padrão: UTF-8.</td><td>UTF-8</td><td>String</td></tr></tbody></table>

### **Aba Documentation**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Seção para documentar qualquer informação necessária sobre a configuração do conector e regras de negócio.</td><td>N/A</td><td>String</td></tr></tbody></table>

## **Exemplos de uso**

### **Enviando um email**

Este conector permite o envio de emails especificando componentes da mensagem, como `to`, `from`, `subject`, `HTML` e partes em texto. Se você estiver usando um plano gratuito para testes, só poderá enviar e-mails para [Destinatários Autorizados](https://help.mailgun.com/hc/en-us/articles/217531258-Authorized-Recipients).

{% hint style="info" %}
**Campos obrigatórios:** Os campos `from`, `to` e `subject` devem estar incluídos no body da requisição para que o email seja enviado com sucesso.
{% endhint %}

Na Digibee Integration Platform, você pode enviar emails de duas formas:

* Passando o body completo diretamente no conector
* Usando expressões [Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview)

<details>

<summary><strong>Passando o body completo</strong></summary>

**Configuração do conector**

**Aba API:**

* **Host:** [`https://api.mailgun.net`](https://api.mailgun.net)
* **Path:** `v3/{domain_name}/messages`
* **Method:** `POST`
* **Path {domain\_name):** `sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org`
* **Header {Content-Type}:** `Multipart/form-data`
* **Multi Part Data:**

```json
{
  "fields": {
    "from": "Mailgun Sandbox <postmaster@sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org>",
    "to": "John Doe <john.doe@email.com>",
    "subject": "Hello John",
    "text": "Congratulations John, you just sent an email with Mailgun! You are truly awesome!"
  }
}
```

**Exemplo de resposta:**

```json
{
  "status": 200,
  "statusMessage": "",
  "body": {
    "id": "<20250318144251.422a1712bf6c5a4c@sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org>",
    "message": "Queued. Thank you."
  },
  "headers": {
    "access-control-allow-credentials": "true",
    "access-control-allow-origin": "*",
    "account-id": "67d2d0ac0f6261b4526226e2",
    "cache-control": "no-store",
    "content-length": "126",
    "content-type": "application/json; charset=utf-8",
    "date": "Tue, 18 Mar 2025 14:42:51 GMT",
    "strict-transport-security": "max-age=63072000; includeSubDomains",
    "x-mailgun-key-id": "623424ea-c0c80f74",
    "x-ratelimit-limit": "80000",
    "x-ratelimit-remaining": "79999",
    "x-ratelimit-reset": "1742308981236",
    "x-recipient-limit": "2000000",
    "x-recipient-remaining": "1999999",
    "x-recipient-reset": "1742308981236",
    "x-server": "influx",
    "x-xss-protection": "1; mode=block"
  }
}
```

</details>

<details>

<summary><strong>Usando expressões Double Braces</strong></summary>

Para enviar um e-mail usando expressões [Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview), siga estes passos:

1. Adicione um conector [**JSON Generator**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/tools/json-generator) antes do conector **Mailgun API**.
2. Utilize o seguinte payload JSON:

```json
{
    "from": "Mailgun Sandbox <postmaster@sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org>",
    "to": "John Doe <john.doe@email.com>",
    "subject": "Hello!",
    "text": "Welcome to Digibee"
}
```

3\. No conector **Mailgun API**, configure:

**Aba API:**

* **Host:** [`https://api.mailgun.net`](https://api.mailgun.net)
* **Path:** `v3/{domain_name}/messages`
* **Method:** `POST`
* **Path {domain\_name):** `sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org`
* **Header {Content-Type}:** `Multipart/form-data`
* **Multi Part Data:**

```json
{
  "fields": {
    "from": {{ message.from }},
    "to": {{ message.to }},
    "subject": {{ message.subject}},
    "text": {{ message.text }}
  }
}
```

**Exemplo de resposta:**

```json
{
  "status": 200,
  "statusMessage": "",
  "body": {
    "id": "<20250319125318.152d650c9d0e220e@sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org>",
    "message": "Queued. Thank you."
  },
  "headers": {
    "access-control-allow-credentials": "true",
    "access-control-allow-origin": "*",
    "account-id": "67d2d0ac0f6261b4526226e2",
    "cache-control": "no-store",
    "content-length": "126",
    "content-type": "application/json; charset=utf-8",
    "date": "Wed, 19 Mar 2025 12:53:18 GMT",
    "strict-transport-security": "max-age=63072000; includeSubDomains",
    "x-mailgun-key-id": "623424ea-c0c80f74",
    "x-ratelimit-limit": "80000",
    "x-ratelimit-remaining": "79999",
    "x-ratelimit-reset": "1742388808749",
    "x-recipient-limit": "2000000",
    "x-recipient-remaining": "1999999",
    "x-recipient-reset": "1742388808749",
    "x-server": "influx",
    "x-xss-protection": "1; mode=block"
  }
}
```

</details>

### **Anexando arquivos ao email**

Você pode anexar um ou mais arquivos ao seu email.

<details>

<summary><strong>Anexo único</strong></summary>

Adicione o campo `attachment` ao body do JSON, como mostrado abaixo:

```json
{
  "fields": {
    "from": "Mailgun Sandbox <postmaster@sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org>",
    "to": "John Doe <john.doe@email.com>",
    "subject": "Hello!",
    "html":"<h1>Hello</h1><p>This is the email content.</p>",
    "attachment": {{ message.fileName}}
  }
}
```

</details>

<details>

<summary><strong>Múltiplos anexos</strong></summary>

Cada anexo deve ter um identificador único enquanto mantém o nome base como `attachment`. Você pode usar variações como `attachmentPDF`, `attachment2` ou `attachment_2`. Veja um exemplo:

```json
{
  "fields": {
    "from": "Mailgun Sandbox <postmaster@sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org>",
    "to": "John Doe <john.doe@email.com>",
    "subject": "Hello!",
    "html":"<h1>Hello</h1><p>This is the email content.</p>",
    "attachment": {{ message.fileName}},
    "attachment2": {{ message.fileName2}}
  }
}
```

{% hint style="warning" %}
Se múltiplos anexos forem enviados sem identificadores únicos, apenas o último anexo será incluído no email.
{% endhint %}

</details>

### **Recuperando uma lista paginada de eventos**

O Mailgun rastreia todos os eventos de mensagens enviadas e recebidas, armazenando esses dados por pelo menos três dias. Você pode recuperar uma lista paginada desses eventos.

Neste exemplo, filtramos os eventos do tipo **delivered** (entregue) e **opened** (aberto).

<details>

<summary><strong>Eventos de entrega (delivered)</strong></summary>

**Configuração do conector**

**Aba API:**

* **Host:** [`https://api.mailgun.net`](https://api.mailgun.net)
* **Path:** `v3/{domain_name}/events`
* **Method:** `GET`
* **Query {event}:** `delivered`

**Exemplo de resposta:**

```json
{
  "status": 200,
  "statusMessage": "",
  "body": {
    "items": [
      {
        "tags": [
          
        ],
        "delivery-status": {
          "first-delivery-attempt-seconds": 0.28,
          "attempt-no": 1,
          "mx-host": "aspmx.l.google.com",
          "tls": true,
          "utf8": true,
          "code": 250,
          "session-seconds": 1.066,
          "certificate-verified": true,
          "message": "OK",
          "enhanced-code": "",
          "description": ""
        },
        "id": "KEsUGyjdTJ602U6INUgxbA",
        "user-variables": {
          
        },
        "event": "delivered",
        "primary-dkim": "mx._domainkey.sandbox.mgsend.net",
        "flags": {
          "is-test-mode": false,
          "is-authenticated": true,
          "is-system-test": false,
          "is-routed": false
        },
        "message": {
          "size": 420,
          "headers": {
            "from": "Mailgun Sandbox <postmaster@sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org>",
            "subject": "Hello!",
            "message-id": "20250318144251.422a1712bf6c5a4c@sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org",
            "to": "John Doe <john.doe@email.com>"
          },
          "attachments": [
            
          ]
        },
        "recipient": "john.doe@email.com",
        "recipient-domain": "email.com",
        "log-level": "info",
        "recipient-provider": "Google Workspace",
        "envelope": {
          "targets": "john.doe@email.com",
          "sender": "postmaster@sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org",
          "sending-ip": "159.135.228.60",
          "transport": "smtp"
        },
        "campaigns": [
          
        ],
        "storage": {
          "region": "us-west1",
          "key": "BAABAQXGi0zYUlTqvp1H269ssre_PkBIYw",
          "env": "production",
          "url": "https://storage-us-west1.api.mailgun.net/v3/domains/sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org/messages/BAABAQXGi0zYUlTqvp1H269ssre_PkBIYw"
        },
        "timestamp": 1742308972.4313374
      }
    ],
    "paging": {
      "previous": "https://api.mailgun.net/v3/sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org/events/WzMseyJiIjoiMjAyNS0wMy0xOVQxMjozMDo0OC44ODMrMDA6MDAiLCJlIjoiMjAyNS0wMy0xOFQxMjozMDo0OC44OTIrMDA6MDAifSx7ImIiOiIyMDI1LTAzLTE4VDE0OjQyOjUyLjQzMSswMDowMCIsImUiOiIyMDI1LTAzLTE5VDEyOjMwOjQ4Ljg4MyswMDowMCJ9LCJfZG9jI0tFc1VHeWpkVEo2MDJVNklOVWd4YkEiLFsiZiIsInAiXSxudWxsLFtbImFjY291bnQuaWQiLCI2N2QyZDBhYzBmNjI2MWI0NTI2MjI2ZTIiXSxbImRvbWFpbi5uYW1lIiwic2FuZGJveDE5NDcwMDRiZDhhMTQ5OTZiYzg2MTA5NzhiY2UzN2U3Lm1haWxndW4ub3JnIl0sWyJldmVudCIsImRlbGl2ZXJlZCJdXSwxMDBd",
      "next": "https://api.mailgun.net/v3/sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org/events/WzMseyJiIjoiMjAyNS0wMy0xOVQxMjozMDo0OC44ODMrMDA6MDAiLCJlIjoiMjAyNS0wMy0xOFQxMjozMDo0OC44OTIrMDA6MDAifSx7ImIiOiIyMDI1LTAzLTE4VDE0OjQyOjUyLjQzMSswMDowMCIsImUiOiIyMDI1LTAzLTE4VDEyOjMwOjQ4Ljg5MiswMDowMCJ9LCJfZG9jI0tFc1VHeWpkVEo2MDJVNklOVWd4YkEiLFsiZiJdLG51bGwsW1siYWNjb3VudC5pZCIsIjY3ZDJkMGFjMGY2MjYxYjQ1MjYyMjZlMiJdLFsiZG9tYWluLm5hbWUiLCJzYW5kYm94MTk0NzAwNGJkOGExNDk5NmJjODYxMDk3OGJjZTM3ZTcubWFpbGd1bi5vcmciXSxbImV2ZW50IiwiZGVsaXZlcmVkIl1dLDEwMF0=",
      "first": "https://api.mailgun.net/v3/sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org/events/WzMseyJiIjoiMjAyNS0wMy0xOVQxMjozMDo0OC44ODMrMDA6MDAiLCJlIjoiMjAyNS0wMy0xOFQxMjozMDo0OC44OTIrMDA6MDAifSx7ImIiOiIyMDI1LTAzLTE5VDEyOjMwOjQ4Ljg4MyswMDowMCIsImUiOiIyMDI1LTAzLTE4VDEyOjMwOjQ4Ljg5MiswMDowMCJ9LG51bGwsWyJmIl0sbnVsbCxbWyJhY2NvdW50LmlkIiwiNjdkMmQwYWMwZjYyNjFiNDUyNjIyNmUyIl0sWyJkb21haW4ubmFtZSIsInNhbmRib3gxOTQ3MDA0YmQ4YTE0OTk2YmM4NjEwOTc4YmNlMzdlNy5tYWlsZ3VuLm9yZyJdLFsiZXZlbnQiLCJkZWxpdmVyZWQiXV0sMTAwXQ==",
      "last": "https://api.mailgun.net/v3/sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org/events/WzMseyJiIjoiMjAyNS0wMy0xOVQxMjozMDo0OC44ODMrMDA6MDAiLCJlIjoiMjAyNS0wMy0xOFQxMjozMDo0OC44OTIrMDA6MDAifSx7ImIiOiIyMDI1LTAzLTE4VDEyOjMwOjQ4Ljg5MiswMDowMCIsImUiOiIyMDI1LTAzLTE5VDEyOjMwOjQ4Ljg4MyswMDowMCJ9LG51bGwsWyJmIiwicCJdLG51bGwsW1siYWNjb3VudC5pZCIsIjY3ZDJkMGFjMGY2MjYxYjQ1MjYyMjZlMiJdLFsiZG9tYWluLm5hbWUiLCJzYW5kYm94MTk0NzAwNGJkOGExNDk5NmJjODYxMDk3OGJjZTM3ZTcubWFpbGd1bi5vcmciXSxbImV2ZW50IiwiZGVsaXZlcmVkIl1dLDEwMF0="
    }
  },
  "headers": {
    "access-control-allow-credentials": "true",
    "access-control-allow-origin": "*",
    "cache-control": "no-store",
    "content-type": "application/json",
    "date": "Wed, 19 Mar 2025 12:30:48 GMT",
    "server": "TwistedWeb/22.10.0",
    "strict-transport-security": "max-age=63072000; includeSubDomains",
    "x-xss-protection": "1; mode=block"
  }
}
```

</details>

<details>

<summary><strong>Eventos de abertura (opened)</strong></summary>

**Configuração do conector**

**Aba API:**

* **Host:** [`https://api.mailgun.net`](https://api.mailgun.net)
* **Path:** `v3/{domain_name}/events`
* **Method:** `GET`
* **Query {event}:** `opened`

**Exemplo de resposta:**

```json
{
  "status": 200,
  "statusMessage": "",
  "body": {
    "items": [
      
    ],
    "paging": {
      "previous": "https://api.mailgun.net/v3/sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org/events/WzMseyJiIjoiMjAyNS0wMy0xOVQxMjo1NTowNi4xMzMrMDA6MDAiLCJlIjoiMjAyNS0wMy0xOFQxMjo1NTowNi4xNDkrMDA6MDAifSx7ImIiOiIyMDI1LTAzLTE5VDEyOjU1OjA2LjEzMyswMDowMCIsImUiOiIyMDI1LTAzLTE5VDEyOjU1OjA2LjEzMyswMDowMCJ9LG51bGwsWyJmIiwicCJdLG51bGwsW1siYWNjb3VudC5pZCIsIjY3ZDJkMGFjMGY2MjYxYjQ1MjYyMjZlMiJdLFsiZG9tYWluLm5hbWUiLCJzYW5kYm94MTk0NzAwNGJkOGExNDk5NmJjODYxMDk3OGJjZTM3ZTcubWFpbGd1bi5vcmciXSxbImV2ZW50Iiwib3BlbmVkIl1dLDEwMF0=",
      "next": "https://api.mailgun.net/v3/sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org/events/WzMseyJiIjoiMjAyNS0wMy0xOVQxMjo1NTowNi4xMzMrMDA6MDAiLCJlIjoiMjAyNS0wMy0xOFQxMjo1NTowNi4xNDkrMDA6MDAifSx7ImIiOiIyMDI1LTAzLTE5VDEyOjU1OjA2LjEzMyswMDowMCIsImUiOiIyMDI1LTAzLTE4VDEyOjU1OjA2LjE0OSswMDowMCJ9LG51bGwsWyJmIl0sbnVsbCxbWyJhY2NvdW50LmlkIiwiNjdkMmQwYWMwZjYyNjFiNDUyNjIyNmUyIl0sWyJkb21haW4ubmFtZSIsInNhbmRib3gxOTQ3MDA0YmQ4YTE0OTk2YmM4NjEwOTc4YmNlMzdlNy5tYWlsZ3VuLm9yZyJdLFsiZXZlbnQiLCJvcGVuZWQiXV0sMTAwXQ==",
      "first": "https://api.mailgun.net/v3/sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org/events/WzMseyJiIjoiMjAyNS0wMy0xOVQxMjo1NTowNi4xMzMrMDA6MDAiLCJlIjoiMjAyNS0wMy0xOFQxMjo1NTowNi4xNDkrMDA6MDAifSx7ImIiOiIyMDI1LTAzLTE5VDEyOjU1OjA2LjEzMyswMDowMCIsImUiOiIyMDI1LTAzLTE4VDEyOjU1OjA2LjE0OSswMDowMCJ9LG51bGwsWyJmIl0sbnVsbCxbWyJhY2NvdW50LmlkIiwiNjdkMmQwYWMwZjYyNjFiNDUyNjIyNmUyIl0sWyJkb21haW4ubmFtZSIsInNhbmRib3gxOTQ3MDA0YmQ4YTE0OTk2YmM4NjEwOTc4YmNlMzdlNy5tYWlsZ3VuLm9yZyJdLFsiZXZlbnQiLCJvcGVuZWQiXV0sMTAwXQ==",
      "last": "https://api.mailgun.net/v3/sandbox1947004bd8a14996bc8610978bce37e7.mailgun.org/events/WzMseyJiIjoiMjAyNS0wMy0xOVQxMjo1NTowNi4xMzMrMDA6MDAiLCJlIjoiMjAyNS0wMy0xOFQxMjo1NTowNi4xNDkrMDA6MDAifSx7ImIiOiIyMDI1LTAzLTE4VDEyOjU1OjA2LjE0OSswMDowMCIsImUiOiIyMDI1LTAzLTE5VDEyOjU1OjA2LjEzMyswMDowMCJ9LG51bGwsWyJmIiwicCJdLG51bGwsW1siYWNjb3VudC5pZCIsIjY3ZDJkMGFjMGY2MjYxYjQ1MjYyMjZlMiJdLFsiZG9tYWluLm5hbWUiLCJzYW5kYm94MTk0NzAwNGJkOGExNDk5NmJjODYxMDk3OGJjZTM3ZTcubWFpbGd1bi5vcmciXSxbImV2ZW50Iiwib3BlbmVkIl1dLDEwMF0="
    }
  },
  "headers": {
    "access-control-allow-credentials": "true",
    "access-control-allow-origin": "*",
    "cache-control": "no-store",
    "content-type": "application/json",
    "date": "Wed, 19 Mar 2025 12:55:06 GMT",
    "server": "TwistedWeb/22.10.0",
    "strict-transport-security": "max-age=63072000; includeSubDomains",
    "x-xss-protection": "1; mode=block"
  }
}
```

</details>