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

Histórico

Um requisito comum no desenvolvimento de suplementos do Outlook é armazenar propriedades personalizadas associadas a um suplemento em níveis diferentes. Atualmente, as propriedades personalizadas são armazenadas no nível do item ou da caixa de correio.

• Nível do item – Para propriedades que se aplicam a um item específico, use o objeto CustomProperties . Por exemplo, armazene um código de cliente associado à pessoa que enviou o email.
• Nível da caixa de correio – Para propriedades que se aplicam a todos os itens de email na caixa de correio do usuário, use o objeto RoamingSettings . Por exemplo, armazene a preferência de um usuário para mostrar a temperatura em uma determinada escala.

Ambos os tipos de propriedades não são preservados depois que o item sai do servidor exchange, portanto, os destinatários de email não podem obter nenhuma propriedade definida no item. Portanto, os desenvolvedores não podem acessar essas configurações ou outras propriedades MIME (Extensão multiuso do Internet Mail) para habilitar cenários de leitura melhores.

Embora haja uma maneira de definir os cabeçalhos da Internet por meio de solicitações do EWS (Exchange Web Services), em alguns cenários, fazer uma solicitação EWS não funcionará. Por exemplo, no modo Compose na área de trabalho do Outlook, a ID do item não é sincronizada no saveAsync modo armazenado em cache.

Dica

Para saber mais sobre como usar essas opções, consulte Obter e definir metadados de suplemento para um suplemento do Outlook.

Finalidade da API de cabeçalhos da Internet

Introduzidas no conjunto de requisitos da caixa de correio 1.8, as APIs de cabeçalhos da Internet permitem que os desenvolvedores:

• Carimbo de informações em um email que persiste depois que ele deixa o Exchange entre todos os clientes.
• Leia informações sobre um email que persistiu depois que o email deixou o Exchange entre todos os clientes em cenários de leitura por email.
• Acesse todo o cabeçalho MIME do email.

Clientes com suporte

Para usar a API de cabeçalhos da Internet no suplemento, seu 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 do 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 com suporte no Outlook em dispositivos móveis, confira APIs JavaScript do Outlook com suporte no Outlook em dispositivos móveis.

Definir cabeçalhos de Internet ao compor uma mensagem

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

Definir, obter e remover o exemplo 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 durante a leitura de uma mensagem

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

Obter preferências de remetente do exemplo de 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 dos cabeçalhos MIME do email 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
*/

Importante

Este exemplo funciona para casos simples. Para obter uma recuperação de informações mais complexa (por exemplo, cabeçalhos de várias instâncias ou valores dobrados, conforme descrito no RFC 2822), tente usar uma biblioteca de análise MIME apropriada.

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 estiver esgotada, você não poderá criar mais cabeçalhos de Internet nessa caixa de correio, o que pode resultar em um comportamento inesperado de clientes que dependem disso para funcionar.

Aplique as diretrizes a seguir ao criar cabeçalhos da Internet no suplemento.

• Create 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. Em Exchange Online, o limite de cabeçalho é limitado a 256 KB, enquanto em um ambiente local do Exchange, o limite é determinado pelo administrador da sua organização. Para obter mais informações sobre limites de cabeçalho, consulte Exchange Online limites de mensagem e Exchange Server limites de mensagem.
• Nomeie cabeçalhos para que você possa reutilizar e atualizar seus valores posteriormente. Como tal, 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