Obter e definir cabeçalhos da Internet em uma mensagem em um suplemento do Outlook

Os cabeçalhos da Internet permitem que o suplemento do Outlook anexe dados de chave-valor personalizados a uma mensagem de saída que persiste após a mensagem sair do Exchange. Ao contrário das propriedades personalizadas no nível do item, os cabeçalhos da Internet acompanham o email, para que os suplementos dos destinatários possam lê-los. Este artigo mostra como definir cabeçalhos de internet ao redigir uma mensagem e como lê-los em uma mensagem recebida.

Por que usar cabeçalhos da Internet

Os suplementos do Outlook podem armazenar dados personalizados em diferentes escopos.

• Nível de item: use CustomProperties para valores vinculados a um item entre sessões ou SessionData para valores necessários somente durante a sessão de redação atual.
• Nível da caixa de correio: use RoamingSettings para valores que se aplicam à caixa de correio do usuário.

Essas opções não persistem na mensagem depois que ela sai do Exchange, portanto, os destinatários não podem ler esses valores. Os cabeçalhos da Internet abordam essa limitação.

Introduzidas no conjunto de requisitos de Caixa de correio 1.8, as APIs de cabeçalhos da Internet permitem que você:

• Informações de carimbo em um email que persistem depois que ele sai do Exchange entre clientes.
• Leia informações persistentes de um email em cenários de leitura entre clientes.
• Acesse o cabeçalho MIME completo do email.

Em ambientes locais do Exchange, você pode definir cabeçalhos de Internet por meio de solicitações do Serviços Web do Exchange (EWS). No entanto, alguns cenários podem falhar. Por exemplo, no modo de redação no Outlook para área de trabalho, a ID do item não é sincronizada no saveAsync modo de cache.

Clientes com suporte

Para usar a API de cabeçalhos da Internet no seu suplemento, o cliente do Outlook deve dar suporte ao conjunto de requisitos 1.8 ou posterior. Para obter informações sobre clientes com suporte, consulte Suporte ao cliente Outlook.

A API de cabeçalhos da Internet também tem suporte no Outlook no Android e no iOS a partir da versão 4.2405.0. Para saber mais sobre os recursos compatíveis com o Outlook em dispositivos móveis, confira APIs JavaScript do Outlook com suporte no Outlook em dispositivos móveis.

Definir cabeçalhos da Internet ao redigir uma mensagem

Use a propriedade item.internetHeaders para gerenciar os cabeçalhos personalizados da Internet que você coloca na mensagem atual no modo Compose.

Exemplo de definição, obtenção e remoção de cabeçalhos personalizados da Internet

O exemplo a seguir mostra como definir, obter e remover cabeçalhos personalizados da Internet.

// Set custom internet headers.
function setCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.setAsync(
    { "preferred-fruit": "orange", "preferred-vegetable": "broccoli", "best-vegetable": "spinach" },
    setCallback
  );
}

function setCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully set headers");
  } else {
    console.log("Error setting headers: " + JSON.stringify(asyncResult.error));
  }
}

// Get custom internet headers.
function getSelectedCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.getAsync(
    ["preferred-fruit", "preferred-vegetable", "best-vegetable", "nonexistent-header"],
    getCallback
  );
}

function getCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Selected headers: " + JSON.stringify(asyncResult.value));
  } else {
    console.log("Error getting selected headers: " + JSON.stringify(asyncResult.error));
  }
}

// Remove custom internet headers.
function removeSelectedCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.removeAsync(
    ["best-vegetable", "nonexistent-header"],
    removeCallback);
}

function removeCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed selected headers");
  } else {
    console.log("Error removing selected headers: " + JSON.stringify(asyncResult.error));
  }
}

setCustomHeaders();
getSelectedCustomHeaders();
removeSelectedCustomHeaders();
getSelectedCustomHeaders();

/* Sample output:
Successfully set headers
Selected headers: {"best-vegetable":"spinach","preferred-fruit":"orange","preferred-vegetable":"broccoli"}
Successfully removed selected headers
Selected headers: {"preferred-fruit":"orange","preferred-vegetable":"broccoli"}
*/

Obter cabeçalhos da Internet ao ler uma mensagem

Chame item.getAllInternetHeadersAsync para obter cabeçalhos da Internet na mensagem atual no modo de leitura.

Exemplo de obtenção das preferências do remetente a partir dos cabeçalhos MIME atuais

Com base no exemplo da seção anterior, o código a seguir mostra como obter as preferências do remetente a partir dos cabeçalhos MIME do e-mail atual.

Office.context.mailbox.item.getAllInternetHeadersAsync(getCallback);

function getCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Sender's preferred fruit: " + asyncResult.value.match(/preferred-fruit:.*/gim)[0].slice(17));
    console.log("Sender's preferred vegetable: " + asyncResult.value.match(/preferred-vegetable:.*/gim)[0].slice(21));
  } else {
    console.log("Error getting preferences from header: " + JSON.stringify(asyncResult.error));
  }
}

/* Sample output:
Sender's preferred fruit: orange
Sender's preferred vegetable: broccoli
*/

Práticas recomendadas

Atualmente, os cabeçalhos da Internet são um recurso finito na caixa de correio de um usuário. Quando a cota se esgota, você não pode criar mais cabeçalhos da Internet nessa caixa de correio, o que pode resultar em comportamento inesperado de clientes que dependem disso para funcionar.

Aplique as seguintes diretrizes ao criar cabeçalhos da Internet em seu suplemento.

• Crie o número mínimo de cabeçalhos necessários. A cota de cabeçalho é baseada no tamanho total dos cabeçalhos aplicados a uma mensagem. No Exchange Online, o limite do cabeçalho é limitado a 256 KB, enquanto em um ambiente Exchange local, o limite é determinado pelo administrador da sua organização. Para obter mais informações sobre limites de cabeçalho, consulte Limites de mensagens do Exchange Online e Limites de mensagens do Exchange Server.
• Nomeie cabeçalhos para que você possa reutilizar e atualizar seus valores mais tarde. Dessa forma, evite nomear cabeçalhos de maneira variável (por exemplo, com base na entrada do usuário, carimbo de data/hora etc.).

Confira também

• Obter e definir metadados de suplemento para um suplemento do Outlook
• Limites para ativação e uso da API em suplementos do Outlook