> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/dev-reference/report-functions/send-rjrbreportemail.md).

# Send-RjRbReportEmail

Enviar e-mails de relatório HTML com a marca a partir de runbooks do Azure Automation via Microsoft Graph usando conteúdo Markdown.

## Visão geral

`Send-RjRbReportEmail` é o auxiliar padrão para enviar emails de relatório a partir dos runbooks de relatórios do RealmJoin. Recebe conteúdo Markdown, converte-o num email HTML responsivo com a marca RealmJoin, anexa ficheiros opcionais e gráficos de marca embutidos (cabeçalho/rodapé) e envia o resultado através do Microsoft Graph `sendMail` endpoint.

> **Renomeado nesta versão.** A função foi renomeada de `Send-RjReportEmail` a `Send-RjRbReportEmail` para manter a consistência de nomes com o restante módulo (`*-RjRb*`). O nome antigo `Send-RjReportEmail` é exportado como um alias compatível com versões anteriores, pelo que os runbooks existentes continuam a funcionar sem alterações — mas os novos runbooks devem chamar `Send-RjRbReportEmail`.

Caraterísticas principais:

* **Markdown de entrada, HTML de saída** — os runbooks compõem o corpo do relatório em Markdown; a função renderiza-o em HTML temático que funciona no Outlook Classic, New Outlook, Outlook Web, clientes móveis e modo escuro.
* **Um email por destinatário** — quando são fornecidos vários destinatários, a função envia uma mensagem individual para cada endereço em vez de um único email com vários destinatários. Trata-se de uma conceção de privacidade/BCC por defeito.
* **Cabeçalho e rodapé com a marca embutidos** — os recursos PNG incluídos são enviados como anexos CID e referenciados pelo HTML incorporado. Ambos podem ser substituídos ou totalmente suprimidos.
* **Cores de modelo personalizáveis** — a cor de destaque e a cor do texto do modelo podem ser substituídas por chamada, para que os emails de relatório possam seguir o design corporativo de um cliente.
* **Proteção de tamanho de anexos incorporada** — um conjunto alternativo opcional de anexos mais pequeno é enviado automaticamente quando o conjunto normal excede o orçamento de tamanho ou quando a tentativa de envio falha.
* **Auto-ligação** — se não existir nenhuma sessão do Graph ativa, a função chama transparentemente `Connect-RjRbGraph` (ou `Connect-MgGraph -Identity` quando `-UseNativeGraphRequest` está definido).
* **Resiliente** — leituras de anexos com falha, substituições de imagens inválidas, cores inválidas ou falhas de sendMail por destinatário são comunicadas, mas não interrompem todo o lote, a menos que *todos* os destinatários falhem.

As definições centralizadas de email (endereço do remetente, informações do service desk) estão documentadas em [Definições de relatório do runbook](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-report-settings.md) — este documento foca-se em chamar a função a partir de um runbook.

## Pré-requisitos

### Caixa de correio do remetente

É necessária uma caixa de correio licenciada do Microsoft 365 (tipicamente uma caixa de correio partilhada dedicada como `realmjoin-report@contoso.com`) como endereço `De` . A identidade gerida da Automation Account deve ter permissão para enviar em nome dessa caixa de correio através da permissão de aplicação do Graph `Mail.Send` (com âmbito via RBAC para Applications se pretender restringir a identidade a uma única caixa de correio).

> **O remetente não pode ser um grupo do Microsoft 365.** A função envia através do endpoint do Graph `/users/{EmailFrom}/sendMail` — um grupo do Microsoft 365 não é um objeto de utilizador, pelo que a chamada falha. Use um utilizador ou uma caixa de correio partilhada.
>
> Os endereços de grupo do Microsoft 365 como **destinatários** são tecnicamente aceites, mas **não recomendados**: a mensagem pode chegar apenas à caixa de correio do grupo (os membros recebem uma cópia pessoal apenas se seguirem o grupo), a gestão de entrega do grupo pode rejeitar o remetente e as falhas de entrega surgem apenas como um NDR na caixa de correio do remetente — o próprio runbook continua a reportar sucesso. Prefira endereços de caixas de correio individuais.

### Permissões do Graph

| Cenário                                     | Permissão necessária                                       |
| ------------------------------------------- | ---------------------------------------------------------- |
| Predefinição (`Invoke-RjRbRestMethodGraph`) | `Mail.Send` (Application) na caixa de correio do remetente |
| Com `-UseNativeGraphRequest`                | O mesmo — a chamada ainda atinge `/users/{id}/sendMail`    |

### Conectividade do módulo

Por predefinição, a função usa `Invoke-RjRbRestMethodGraph` deste módulo. Se não houver uma ligação ativa, faz ligação automática através de `Connect-RjRbGraph`. Quando `-UseNativeGraphRequest` está definido, a função verifica em vez disso `Get-MgContext` e chama `Connect-MgGraph -Identity -NoWelcome` sob pedido.

## Início rápido

A chamada mínima viável requer apenas o remetente, o destinatário, um assunto e o corpo em Markdown:

```powershell
Send-RjRbReportEmail `
    -EmailFrom "realmjoin-report@contoso.com" `
    -EmailTo   "alice@contoso.com" `
    -Subject   "Weekly Report" `
    -MarkdownContent @"
# Weekly Report

Olá Alice,

aqui estão os números desta semana:

- Novos dispositivos inscritos: **42**
- Conformidade de licenças: **98%**
"@
```

Isto produz um email RealmJoin totalmente com a marca, com o cabeçalho e rodapé predefinidos, suporte para modo claro/escuro e o bloco do locatário/versão no rodapé.

## Parâmetros

### Obrigatório

| Parâmetro         | Tipo     | Descrição                                                                                                                                                                                                                                                                                    |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EmailFrom`       | `string` | Nome principal de utilizador ou ID de objeto da caixa de correio do remetente. Utilizado como `/users/{id}/sendMail`. Tem de ser uma caixa de correio de utilizador ou partilhada — um grupo do Microsoft 365 não é um objeto de utilizador e o envio falha.                                 |
| `EmailTo`         | `string` | Endereço do destinatário. **Cadeia única** — vários endereços são passados como uma lista separada por vírgulas, veja abaixo. Os endereços de grupos do Microsoft 365 são aceites, mas não recomendados — a entrega aos membros não é garantida e as falhas não são visíveis para o runbook. |
| `Assunto`         | `string` | Linha de assunto. Também inserida no HTML `<title>` elemento.                                                                                                                                                                                                                                |
| `MarkdownContent` | `string` | Corpo do relatório em Markdown. Veja [Suporte a Markdown](#markdown-support) para a sintaxe suportada.                                                                                                                                                                                       |

### Opcional — Conteúdo

| Parâmetro           | Tipo       | Padrão  | Descrição                                                                                                                                                                                                     |
| ------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Anexos`            | `string[]` | `@()`   | Caminhos locais de ficheiros a anexar. Os ficheiros em falta são registados e ignorados; os ficheiros ilegíveis emitem um aviso, mas não interrompem o envio. O tipo MIME é derivado da extensão do ficheiro. |
| `saveToSentItems`   | `bool`     | `$true` | Se `$true` a mensagem enviada é mantida na *Itens Enviados*da caixa de correio do remetente. Defina como `$false` para relatórios de grande volume, a fim de evitar encher a caixa de correio.                |
| `TenantDisplayName` | `string`   | —       | Mostrado na caixa de informações do locatário incorporada no fim da área de conteúdo.                                                                                                                         |
| `ReportVersion`     | `string`   | —       | Mostrado na caixa de informações do locatário (use cadeias de versão semântica, números de compilação ou um nome de runbook + data).                                                                          |

### Opcional — Marca

| Parâmetro     | Tipo          | Padrão                        | Descrição                                                                                                                                                                                                                                                                                                                                 |
| ------------- | ------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HeaderImage` | `string`      | incluídos `Assets/Header.png` | Caminho local do ficheiro para um PNG/JPG/GIF que substitui o gráfico de cabeçalho predefinido. **O runbook deve resolver previamente qualquer URL/blob para um ficheiro local** (por exemplo, através de `Get-AzStorageBlobContent`). As substituições em falta/ilegíveis fazem fallback para a predefinição incluída e emitem um aviso. |
| `FooterImage` | `string`      | incluídos `Assets/Footer.png` | O mesmo tratamento que `HeaderImage`. O rodapé é renderizado como uma única imagem clicável — qualquer texto de marca, logótipo ou URL deve estar incorporado no PNG.                                                                                                                                                                     |
| `FooterLink`  | `string`      | `https://www.realmjoin.com`   | URL usada como o `href` e `title` da âncora que envolve a imagem do rodapé.                                                                                                                                                                                                                                                               |
| `NoHeader`    | `interruptor` | desligado                     | Suprime totalmente o gráfico do cabeçalho. Se combinado com `HeaderImage`, é emitido um aviso e a substituição é ignorada.                                                                                                                                                                                                                |
| `NoFooter`    | `interruptor` | desligado                     | Suprime totalmente o gráfico do rodapé e a respetiva ligação. Se combinado com `FooterImage` ou um `FooterLink`, é emitido um aviso e esses valores são ignorados.                                                                                                                                                                        |
| `AccentColor` | `string`      | `#f8842c`                     | *Novo na 0.8.9.* Cor hexadecimal de 6 dígitos para linhas de cabeçalho de tabelas, botões de ação e as margens de destaque das caixas de informação. Um valor vazio ou malformado emite um aviso e faz fallback para o predefinido.                                                                                                       |
| `TextColor`   | `string`      | `#011e33`                     | *Novo na 0.8.9.* Cor hexadecimal de 6 dígitos para o texto do corpo, títulos, itens de lista e código. Mesmo comportamento de fallback que `AccentColor`.                                                                                                                                                                                 |

**Dimensões de imagem recomendadas:** PNG 750 × 200 px. Isto corresponde à largura do contentor de email e às predefinições incluídas. Proporções significativamente diferentes podem parecer distorcidas em larguras de visualização estreitas. Cada gráfico deve ficar bem abaixo de 3 MB — o Graph limita o total `sendMail` do pedido a 4 MB e é emitido um aviso se qualquer imagem exceder 3 MB.

**Cores:** sem `AccentColor`/`TextColor` o HTML gerado é byte a byte idêntico às versões anteriores do módulo — os predefinidos são o laranja e o azul-marinho do RealmJoin. As cores de estado (verde/vermelho/âmbar) e os cinzentos neutros não são parametrizados de propósito porque transmitem significado. Verifique as cores personalizadas em modo claro e escuro: o cartão de conteúdo mantém-se branco em modo escuro, pelo que uma cor de texto muito clara se torna ilegível.

### Opcional — Proteção do tamanho dos anexos

*Novo na 0.8.9.* O Graph rejeita o pedido inteiro `sendMail` quando a mensagem excede cerca de 4 MB. Em vez de falhar o relatório, a função pode recorrer a um conjunto de anexos mais pequeno. Esta lógica era anteriormente duplicada como o auxiliar inline do runbook `Send-RjRbGuardedReportEmail` e agora faz parte da própria função.

| Parâmetro                 | Tipo       | Padrão                     | Descrição                                                                                                                                                                                                                                                               |
| ------------------------- | ---------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FallbackAttachments`     | `string[]` | —                          | Conjunto de anexos mais pequeno utilizado quando o conjunto normal excede `MaxAttachmentBytes`, ou quando o envio com o conjunto normal falha para todos os destinatários. Sem este parâmetro não existe fallback e um envio com falha lança imediatamente uma exceção. |
| `FallbackMarkdownContent` | `string`   | valor de `MarkdownContent` | Corpo usado quando o conjunto de fallback é enviado — use-o para explicar que ficheiros foram omitidos e como obtê-los.                                                                                                                                                 |
| `MaxAttachmentBytes`      | `long`     | `2,5 MB`                   | Orçamento de tamanho bruto para o conjunto normal de anexos. Permanece seguramente abaixo do limite do Graph de cerca de 4 MB após a codificação base64 (+33%), corpo HTML e imagens de marca embutidas. Só é avaliado quando `FallbackAttachments` é fornecido.        |

A proteção funciona em duas fases:

1. **Antes de enviar** — se o conjunto normal exceder o orçamento, o conjunto de fallback é enviado diretamente e uma mensagem indica ambos os tamanhos.
2. **Após um envio com falha** — se o envio com o conjunto normal falhar para *todos* destinatários, é tentada uma nova tentativa com o conjunto de fallback antes de a função lançar uma exceção.

### Opcional — Transporte

| Parâmetro               | Tipo          | Padrão    | Descrição                                                                                                                                                                                                                                             |
| ----------------------- | ------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UseNativeGraphRequest` | `interruptor` | desligado | Envia através de `Invoke-MgGraphRequest` (requer `Microsoft.Graph` módulo e uma sessão `Connect-MgGraph` ) em vez de `Invoke-RjRbRestMethodGraph`. Use isto quando o runbook estiver construído em torno do SDK nativo em vez do invólucro RealmJoin. |

## Exemplos de utilização

### Vários destinatários

`EmailTo` aceita uma única cadeia contendo um ou mais endereços separados por vírgulas. Cada endereço é aparado, entradas vazias são removidas e **é enviado um email individual por destinatário** — os destinatários não se veem uns aos outros.

```powershell
Send-RjRbReportEmail `
    -EmailFrom "realmjoin-report@contoso.com" `
    -EmailTo   "alice@contoso.com, bob@contoso.com, team-lead@contoso.com" `
    -Subject   "Monthly Inventory" `
    -MarkdownContent $reportMd
```

### Com anexos e metadados do locatário

```powershell
$csvPath = Join-Path $env:TEMP 'devices.csv'
$exportData | Export-Csv -Path $csvPath -NoTypeInformation -Encoding UTF8

Send-RjRbReportEmail `
    -EmailFrom         "realmjoin-report@contoso.com" `
    -EmailTo           "it-reports@contoso.com" `
    -Subject           "Device Inventory — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent   $reportMd `
    -Attachments       @($csvPath, "$env:TEMP\summary.xlsx") `
    -TenantDisplayName "Contoso Ltd" `
    -ReportVersion     "DeviceInventory v1.4.2"
```

Os ficheiros anexados são listados numa caixa "Ficheiros anexados" na parte inferior do corpo do email, para além de serem adicionados como anexos reais à mensagem.

### Branding personalizado de cabeçalho/rodapé

Traga a sua própria marca descarregando primeiro os recursos para um caminho local e, depois, passe os caminhos resultantes. A função não faz o fetch dos URLs por si.

```powershell
# Resolva os recursos de marca do Azure Blob Storage para a pasta temporária do runbook
$headerPath = Join-Path $env:TEMP 'contoso-header.png'
$footerPath = Join-Path $env:TEMP 'contoso-footer.png'

Get-AzStorageBlobContent -Container 'branding' -Blob 'header.png' -Destination $headerPath -Force | Out-Null
Get-AzStorageBlobContent -Container 'branding' -Blob 'footer.png' -Destination $footerPath -Force | Out-Null

Send-RjRbReportEmail `
    -EmailFrom        "realmjoin-report@contoso.com" `
    -EmailTo          "alice@contoso.com" `
    -Subject          "Branded Report" `
    -MarkdownContent  $reportMd `
    -HeaderImage      $headerPath `
    -FooterImage      $footerPath `
    -FooterLink       "https://intranet.contoso.com/it-reports"
```

Se `$headerPath` está em falta ou é ilegível, a chamada continua a ter sucesso — a predefinição RealmJoin incluída é usada e é registado um aviso.

### Cores de modelo personalizadas

Adapte o email ao design corporativo de um cliente. Ambos os parâmetros são independentes — ao substituir apenas a cor de destaque, mantém-se a cor de texto predefinida:

```powershell
Send-RjRbReportEmail `
    -EmailFrom       "realmjoin-report@contoso.com" `
    -EmailTo         "alice@contoso.com" `
    -Subject         "Branded Report" `
    -MarkdownContent $reportMd `
    -AccentColor     "#0052cc" `
    -TextColor       "#1a1a2e"
```

Um valor inválido (por exemplo `blue` ou `#05c`) não faz falhar o envio: é emitido um aviso que indica o parâmetro e é usada a cor predefinida.

### Relatórios grandes com um conjunto de anexos de fallback

Gere um CSV e uma pasta de trabalho Excel, mas faça fallback apenas para a pasta de trabalho quando o par exceder o orçamento de tamanho:

```powershell
$sizeHint = "A exportação CSV foi omitida porque os anexos excederam o limite de tamanho do email. A pasta de trabalho Excel contém os dados completos."

Send-RjRbReportEmail `
    -EmailFrom                "realmjoin-report@contoso.com" `
    -EmailTo                  "it-reports@contoso.com" `
    -Subject                  "Device Inventory" `
    -MarkdownContent          $reportMd `
    -Attachments              @($csvPath, $xlsxPath) `
    -FallbackAttachments      @($xlsxPath) `
    -FallbackMarkdownContent  ($reportMd + "`n`n> **Nota:** $sizeHint")
```

Runbooks que migram do auxiliar inline `Send-RjRbGuardedReportEmail` podem remover essa função e renomear a chamada para `Send-RjRbReportEmail` — os nomes dos parâmetros (`Anexos`, `FallbackAttachments`, `FallbackMarkdownContent`, `MaxAttachmentBytes`) não sofreram alterações.

### Conteúdo simples (sem cabeçalho/rodapé)

Para notificações ao estilo de alerta que não devem parecer um email de marketing:

```powershell
Send-RjRbReportEmail `
    -EmailFrom       "realmjoin-report@contoso.com" `
    -EmailTo         "oncall@contoso.com" `
    -Subject         "[ALERT] License threshold exceeded" `
    -MarkdownContent "## License threshold exceeded`n`nConsulte o painel para detalhes." `
    -NoHeader `
    -NoFooter
```

### Usando o SDK nativo Microsoft.Graph

Se o runbook já estiver autenticado através de `Connect-MgGraph` (identidade gerida) e preferir não misturar o invólucro RealmJoin:

```powershell
Connect-MgGraph -Identity -NoWelcome

Send-RjRbReportEmail `
    -EmailFrom             "realmjoin-report@contoso.com" `
    -EmailTo               "alice@contoso.com" `
    -Subject               "Native Graph send" `
    -MarkdownContent       $reportMd `
    -UseNativeGraphRequest
```

### Ler o corpo do relatório a partir de um ficheiro

Para relatórios maiores, gere o Markdown num ficheiro `.md` e leia-o:

```powershell
$reportMd = Get-Content -Path .\generated-report.md -Raw

Send-RjRbReportEmail `
    -EmailFrom       "realmjoin-report@contoso.com" `
    -EmailTo         "alice@contoso.com" `
    -Subject         "Weekly Report" `
    -MarkdownContent $reportMd
```

### Botões de ação (call-to-action)

Renderize um ou mais botões com marca anexando `{button}` a uma ligação Markdown. Os botões colocados na mesma linha são agrupados numa única linha:

```powershell
$reportMd = @"
# Pedido de acesso

Está à espera da sua decisão um novo pedido de acesso a um dispositivo.

[Aprovar](https://portal.contoso.com/approve/123){button} [Rejeitar](https://portal.contoso.com/reject/123){button}
"@

Send-RjRbReportEmail `
    -EmailFrom       "realmjoin-report@contoso.com" `
    -EmailTo         "approver@contoso.com" `
    -Subject         "Ação necessária: pedido de acesso a dispositivo" `
    -MarkdownContent $reportMd
```

Cada botão é uma hiperligação normal estilizada como uma CTA — segura em todos os clientes, com cantos arredondados em clientes modernos e cantos quadrados no Outlook Classic.

## Suporte a Markdown

A função inclui um conversor incorporado leve de Markdown → HTML. **Não é necessário nenhum módulo externo de Markdown.** Sintaxe suportada:

| Markdown                                      | Notas                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `# … ######` cabeçalhos                       | Todos os seis níveis. O espaço após `#` é opcional. `h1` ganha uma linha sublinhada; espaçamento ajustado para o Outlook.                                                                                                                                                                                                                                         |
| `**negrito**`, `*itálico*`, `~~rasurado~~`    | Apenas inline (não deve abranger várias linhas).                                                                                                                                                                                                                                                                                                                  |
| `` `código inline` ``                         | Renderizado como `<code>` com um fundo cinzento-claro.                                                                                                                                                                                                                                                                                                            |
| blocos de código cercados por lang ...        | A etiqueta de linguagem é preservada como `class="language-…"`. Também tolera cercas de um único backtick malformadas.                                                                                                                                                                                                                                            |
| `[texto](url)` ligações                       | Abrir num novo separador com `noopener noreferrer`.                                                                                                                                                                                                                                                                                                               |
| `[etiqueta](url){button}` botões de ligação   | É renderizado como um botão laranja de call-to-action com marca em vez de uma ligação simples. Várias `{button}` ligações na **mesma linha** são renderizadas lado a lado numa única linha (largura dividida igualmente). Cantos arredondados aparecem em clientes modernos (New Outlook, OWA, móvel); o Outlook Classic (motor Word) renderiza cantos quadrados. |
| `![alt](url)` imagens                         | Inseridas como `<img>` (sem magia de anexo inline — o URL tem de ser alcançável pelo cliente de email).                                                                                                                                                                                                                                                           |
| `- item` / `1. item` listas                   | Listas aninhadas suportadas por meio de indentação de 2 espaços por nível. Misturar listas ordenadas e não ordenadas encerra a lista anterior.                                                                                                                                                                                                                    |
| Itens de lista em várias linhas               | Uma linha indentada, não vazia, diretamente abaixo de um `<li>` é incorporada ao mesmo item com um `<br>` quebra suave — não há necessidade de manter cada item em uma única linha.                                                                                                                                                                               |
| `- [ ]` / `- [x]` listas de tarefas           | Renderizado como `☐` / `☑` Glifos Unicode (verdes quando marcados). `<input type="checkbox">` é evitado intencionalmente porque o Outlook Classic remove controles de formulário. Maiúsculo `[X]` também conta como marcado.                                                                                                                                      |
| `> citação em bloco`                          | Renderizado com uma borda esquerda colorida e fundo sombreado.                                                                                                                                                                                                                                                                                                    |
| `> [!NOTE\|TIP\|IMPORTANT\|WARNING\|CAUTION]` | Admoestações no estilo GitHub. A primeira linha da citação em bloco é o marcador (sozinho), as restantes `>`linhas prefixadas são o corpo. Cada tipo recebe sua própria cor de destaque, glifo e barra de título.                                                                                                                                                 |
| `---`, `***`, `___`                           | Regra horizontal.                                                                                                                                                                                                                                                                                                                                                 |
| `\|col\|col\|` tabelas                        | Tabelas padrão com pipe e `:---`, `:---:`, `---:` especificadores de alinhamento. Linha de cabeçalho + separador obrigatórios.                                                                                                                                                                                                                                    |
| `\\` escape                                   | `\*`, `\|` etc. são respeitados, para que caracteres Markdown literais possam ser emitidos.                                                                                                                                                                                                                                                                       |

Os itens não suportados incluem notas de rodapé, listas de definições e passagem direta de HTML — mantenha o Markdown conforme a tabela acima.

## Comportamento e tratamento de erros

### Análise de destinatários

`EmailTo` é dividido por vírgulas, cada entrada é aparada e as entradas vazias são descartadas. Se a lista resultante estiver vazia, a função lança `Nenhum destinatário de e-mail válido encontrado no parâmetro EmailTo.` antes que qualquer chamada ao Graph seja feita.

### Falhas por destinatário

Cada destinatário é enviado independentemente. A função acompanha sucessos e falhas:

* Se **pelo menos um** envio é bem-sucedido, mas outros falham, um aviso é emitido listando os endereços com falha; a função retorna normalmente.
* Se **todos** os envios falham, a função lança `Falha ao enviar e-mail para todos os destinatários: …` para que o runbook falhe de forma explícita.

### Falhas em anexos

* Arquivos ausentes (o caminho não existe) — registrados com verbosidade, ignorados silenciosamente.
* Arquivos existentes, mas ilegíveis (bloqueados, acesso negado) — aviso emitido, ignorados, o restante da chamada prossegue.
* A caixa "Arquivos anexados" na parte inferior do e-mail lista apenas os anexos que foram lidos com sucesso.

### Falhas na substituição de imagem

Ambos `HeaderImage` e `FooterImage` fazem fallback para os padrões incluídos em qualquer erro (arquivo ausente, erro de E/S ou um arquivo que não seja uma imagem válida). Um aviso descreve a falha e identifica qual padrão foi usado.

Desde 0.8.9, o formato da imagem é determinado pela **assinatura do arquivo** (magic bytes) em vez da extensão do arquivo. Um arquivo nomeado `.png` mas que na verdade contém uma página de erro HTML — um resultado comum quando um download retorna silenciosamente um documento de erro — agora é rejeitado com um aviso em vez de produzir um anexo inline quebrado. Por outro lado, um PNG válido salvo com uma extensão enganosa é aceito e tipado corretamente.

### Cores inválidas

`AccentColor` e `TextColor` são validadas contra `^#[0-9A-Fa-f]{6}$`. Um valor que não corresponda emite um aviso nomeando o parâmetro e o envio prossegue com a cor padrão. Cores nunca são motivo para um relatório falhar.

### Limite total de tamanho

O Graph limita `sendMail` requisições a cerca de 4 MB no total (corpo HTML + todos os anexos, codificados em base64). A função emite um aviso quando qualquer imagem de marca excede 3 MB.

Quando `FallbackAttachments` for fornecido, o controle de tamanho do anexo descrito na seção de parâmetros acima trata automaticamente cargas úteis excessivamente grandes. Sem um fallback definido, uma requisição excessivamente grande falha na chamada ao Graph; considere:

* Fornecer um `FallbackAttachments` conjunto (por exemplo, a pasta de trabalho do Excel sem os arquivos CSV brutos).
* Fazer upload de dados grandes para o canal Storage Account, em vez disso — veja [Definições de relatório do runbook](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-report-settings.md#storage-account-delivery).
* Vincular anexos hospedados externamente em vez de incorporá-los.
* Compactar dados tabulares (`Compress-Archive`) antes de anexar.

## Integração com as Configurações de Relatório do Runbook

Os runbooks de relatório não codificam o endereço do remetente nem a identidade visual: eles declaram parâmetros ocultos que o portal RealmJoin preenche a partir do JSON central de personalização. As configurações disponíveis estão documentadas em [Definições de relatório do runbook](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-report-settings.md).

A vinculação acontece no `param()` do runbook por meio de `Use-RJInterface -Type Setting`, e os parâmetros são marcados `"Hide": true` no bloco `.INPUTS RunbookCustomization` para que não sobrecarreguem o formulário do portal:

```powershell
param(
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.EmailSender" } )]
    [string]$EmailFrom,

    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.HeaderImageUrl" } )]
    [string]$BrandingHeaderImageUrl,

    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.FooterImageUrl" } )]
    [string]$BrandingFooterImageUrl,

    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.FooterLink" } )]
    [string]$BrandingFooterLink,

    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.AccentColor" } )]
    [string]$BrandingAccentColor,

    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.TextColor" } )]
    [string]$BrandingTextColor
)

if (-not $EmailFrom) {
    throw "Nenhum EmailSender configurado. Veja https://docs.realmjoin.com/automation/runbooks/runbook-report-settings para instruções de configuração."
}

# Baixa e valida as imagens de identidade visual uma vez por execução; retorna apenas as chaves
# que foram resolvidas com sucesso, de modo que as configurações não definidas caiam para os padrões.
$brandingMailParams = Get-RjRbBrandingMailParams `
    -HeaderImageUrl $BrandingHeaderImageUrl `
    -FooterImageUrl $BrandingFooterImageUrl `
    -FooterLink     $BrandingFooterLink `
    -AccentColor    $BrandingAccentColor `
    -TextColor      $BrandingTextColor

Send-RjRbReportEmail `
    -EmailFrom         $EmailFrom `
    -EmailTo           $RecipientParameter `
    -Subject           $Subject `
    -MarkdownContent   $reportMd `
    -TenantDisplayName $TenantDisplayName `
    -ReportVersion     "MyReport v1.0" `
    @brandingMailParams
```

Consulte [Get-RjRbBrandingMailParams](https://docs.realmjoin.com/pt/dev-reference/report-functions/get-rjrbbrandingmailparams.md) para as regras de download, validação e limpeza.

## Saídas

A função não retorna nada em caso de sucesso. Todo o progresso é escrito por meio de `Write-RjRbLog -Verbose` (visível quando o runbook é executado com `-Verbose` ou `$VerbosePreference = 'Continue'`). Os avisos são forçados por meio de `$WarningPreference = 'Continue'` independentemente de substituições do lado do chamador, para que apareçam de forma confiável no stream de jobs do Azure Automation.

## Helpers Exportados Relacionados

Os blocos de construção por trás de `Send-RjRbReportEmail` agora também são exportados do módulo, para que os runbooks possam compor ou pré-visualizar o HTML sem enviar:

| Função                                                                                                                     | Finalidade                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`Get-RjRbBrandingMailParams`](https://docs.realmjoin.com/pt/dev-reference/report-functions/get-rjrbbrandingmailparams.md) | Transforma os `RJReport.Branding.*` configurações do tenant em parâmetros prontos para splat: baixa e valida as imagens, repassa cores e link de rodapé.                                                                                              |
| `ConvertFrom-RjRbMarkdownToHtml`                                                                                           | Conversor Markdown → HTML autônomo (o mesmo mecanismo leve usado internamente, incluindo a sintaxe `{button}` ). Aceita `-AccentColor`/`-TextColor`.                                                                                                  |
| `Get-RjRbReportEmailBody`                                                                                                  | Monta o corpo HTML completo com identidade visual (cabeçalho/rodapé, caixa de informações do tenant, lista de anexos) a partir de HTML ou Markdown — útil para renderizar e inspecionar o e-mail antes de enviar. Aceita `-AccentColor`/`-TextColor`. |
| `Resolve-RjRbImageSource`                                                                                                  | Resolve um caminho de imagem de cabeçalho/rodapé para sua fonte CID inline. Valida pela assinatura do arquivo e lança erro para qualquer coisa que não seja PNG, JPEG ou GIF.                                                                         |

Exceto por `Get-RjRbBrandingMailParams`, estes são destinados principalmente a cenários avançados/de teste; o caminho normal é chamar `Send-RjRbReportEmail` diretamente.

## Ver também

* [Get-RjRbBrandingMailParams](https://docs.realmjoin.com/pt/dev-reference/report-functions/get-rjrbbrandingmailparams.md) — resolvendo as configurações de identidade visual do tenant dentro de um runbook.
* [Definições de relatório do runbook](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-report-settings.md) — configuração central da caixa de correio do remetente, informações do service desk, identidade visual e canal de entrega Storage Account.
* Microsoft Graph: [Enviar e-mail](https://learn.microsoft.com/en-us/graph/api/user-sendmail) — API subjacente.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/pt/dev-reference/report-functions/send-rjrbreportemail.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
