Compartilhar via


Office.Recipients interface

Representa os destinatários de um item. Somente modo de redação.

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose

Métodos

addAsync(recipients, options, callback)

Adiciona uma lista de destinatários aos destinatários existentes para um compromisso ou uma mensagem.

addAsync(recipients, callback)

Adiciona uma lista de destinatários aos destinatários existentes para um compromisso ou uma mensagem.

getAsync(options, callback)

Obtém uma lista de destinatários para um compromisso ou uma mensagem.

getAsync(callback)

Obtém uma lista de destinatários para um compromisso ou uma mensagem.

setAsync(recipients, options, callback)

Define uma lista de destinatários para um compromisso ou uma mensagem.

O método setAsync substitui a lista de destinatários atual.

setAsync(recipients, callback)

Define uma lista de destinatários para um compromisso ou uma mensagem.

O método setAsync substitui a lista de destinatários atual.

Detalhes do método

addAsync(recipients, options, callback)

Adiciona uma lista de destinatários aos destinatários existentes para um compromisso ou uma mensagem.

addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parâmetros

recipients

Array<string | Office.EmailUser | Office.EmailAddressDetails>

Os destinatários a serem adicionados à lista de destinatários. A matriz de destinatários pode conter cadeias de endereços de e-mail SMTP, objetos EmailUser ou objetos EmailAddressDetails .

options
Office.AsyncContextOptions

Um literal de objeto que contém uma ou mais das seguintes propriedades: asyncContext: os programadores podem fornecer qualquer objeto a que pretendam aceder na função de chamada de retorno.

callback

(asyncResult: Office.AsyncResult<void>) => void

Opcional. Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult. Se a adição de destinatários falhar, a propriedade asyncResult.error conterá um código de erro.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: item de leitura/escrita

Modo Outlook aplicável: Compose

Importante: com o addAsync método , pode adicionar um máximo de 100 destinatários a um item de correio no Outlook na Web, no Windows (novo e clássico), no Mac (IU clássica), no Android e no iOS. No entanto, tome nota do seguinte:

  • No Outlook na Web, no Windows (novo e clássico) e no Mac (IU clássica), pode ter um máximo de 500 destinatários num campo de destino. Se precisar de adicionar mais de 100 destinatários a um item de correio, pode ligar addAsync repetidamente, mas tenha em atenção o limite de destinatários do campo.

  • No Outlook para Android e no iOS, o addAsync método não é suportado no modo Compose mensagens. Apenas o modo Organizador de Compromissos é suportado. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Não existe limite de destinatários se ligar addAsync para o Outlook no Mac (nova IU).

Erros:

  • NumberOfRecipientsExceeded : o número de destinatários excedeu as 100 entradas.

Exemplos

// The following example creates an array of EmailUser objects
// and adds them to the To recipients of the message.
const newRecipients = [
    {
        "displayName": "Allie Bellew",
        "emailAddress": "allieb@contoso.com"
    },
    {
        "displayName": "Alex Darrow",
        "emailAddress": "alexd@contoso.com"
    }
];

Office.context.mailbox.item.to.addAsync(newRecipients, function(result) {
    if (result.error) {
        console.log(result.error);
    } else {
        console.log("Recipients added");
    }
});

addAsync(recipients, callback)

Adiciona uma lista de destinatários aos destinatários existentes para um compromisso ou uma mensagem.

addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parâmetros

recipients

Array<string | Office.EmailUser | Office.EmailAddressDetails>

Os destinatários a serem adicionados à lista de destinatários. A matriz de destinatários pode conter cadeias de endereços de e-mail SMTP, objetos EmailUser ou objetos EmailAddressDetails .

callback

(asyncResult: Office.AsyncResult<void>) => void

Opcional. Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult. Se a adição de destinatários falhar, a propriedade asyncResult.error conterá um código de erro.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: item de leitura/escrita

Modo Outlook aplicável: Compose

Importante: com o addAsync método , pode adicionar um máximo de 100 destinatários a um item de correio no Outlook na Web, no Windows, no Mac (IU clássica), no Android e no iOS. No entanto, tome nota do seguinte:

  • No Outlook na Web, no Windows e no Mac (IU clássica), pode ter um máximo de 500 destinatários num campo de destino. Se precisar de adicionar mais de 100 destinatários a um item de correio, pode ligar addAsync repetidamente, mas tenha em atenção o limite de destinatários do campo.

  • No Outlook para Android e no iOS, o addAsync método não é suportado no modo Compose mensagens. Apenas o modo Organizador de Compromissos é suportado. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Não existe limite de destinatários se ligar addAsync para o Outlook no Mac (nova IU).

Erros:

  • NumberOfRecipientsExceeded : o número de destinatários excedeu as 100 entradas.

getAsync(options, callback)

Obtém uma lista de destinatários para um compromisso ou uma mensagem.

getAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<EmailAddressDetails[]>) => void): void;

Parâmetros

options
Office.AsyncContextOptions

Um literal de objeto que contém uma ou mais das seguintes propriedades: asyncContext: os programadores podem fornecer qualquer objeto a que pretendam aceder na função de chamada de retorno.

callback

(asyncResult: Office.AsyncResult<Office.EmailAddressDetails[]>) => void

Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro,asyncResult , do tipo Office.AsyncResult. A asyncResult.value propriedade do resultado é uma matriz de objetos EmailAddressDetails .

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose

Importante:

O número máximo de destinatários devolvidos por este método varia consoante o cliente do Outlook.

  • Windows (novo e clássico), browser, Mac (IU clássica): 500 destinatários

  • Android, iOS: 100 destinatários

  • Mac (nova IU): sem limite

O getAsync método só devolve destinatários resolvidos pelo cliente do Outlook. Um destinatário resolvido tem as seguintes características.

  • Se o destinatário tiver uma entrada guardada no livro de endereços do remetente, o Outlook resolve o endereço de e-mail para o nome a apresentar guardado do destinatário.

  • É apresentado um ícone de status de reunião do Teams antes do nome ou endereço de e-mail do destinatário.

  • É apresentado um ponto e vírgula após o nome ou endereço de e-mail do destinatário.

  • O nome ou endereço de e-mail do destinatário está sublinhado ou colocado numa caixa.

Para resolve um endereço de e-mail depois de ser adicionado a um item de correio, o remetente tem de utilizar a Tecla de Tabulação ou selecionar um contacto ou endereço de e-mail sugerido a partir da lista de conclusão automática.

No Outlook na Web e no Windows (novo e clássico), se um utilizador criar uma nova mensagem ao ativar a ligação do endereço de e-mail de um contacto a partir do respetivo contacto ou perfil card, a chamada do Recipients.getAsync seu suplemento devolve o endereço de e-mail do contacto na displayName propriedade do objeto EmailAddressDetails associado em vez do nome guardado do contacto. Para obter mais detalhes, veja o problema relacionado com o GitHub.

Ao compor um item de correio, quando muda para uma conta de remetente que está num domínio diferente do da conta de remetente selecionada anteriormente, o valor da recipientType propriedade para destinatários existentes não é atualizado e continuará a ser baseado no domínio da conta selecionada anteriormente. Para obter os tipos de destinatários corretos depois de mudar de conta, primeiro tem de remover os destinatários existentes e, em seguida, adicioná-los novamente ao item de correio.

getAsync(callback)

Obtém uma lista de destinatários para um compromisso ou uma mensagem.

getAsync(callback: (asyncResult: Office.AsyncResult<EmailAddressDetails[]>) => void): void;

Parâmetros

callback

(asyncResult: Office.AsyncResult<Office.EmailAddressDetails[]>) => void

Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro,asyncResult , do tipo Office.AsyncResult. A asyncResult.value propriedade do resultado é uma matriz de objetos EmailAddressDetails .

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose

Importante:

O número máximo de destinatários devolvidos por este método varia consoante o cliente do Outlook.

  • Windows (novo e clássico), browser, Mac (IU clássica): 500 destinatários

  • Android, iOS: 100 destinatários

  • Mac (nova IU): sem limite

O getAsync método só devolve destinatários resolvidos pelo cliente do Outlook. Um destinatário resolvido tem as seguintes características.

  • Se o destinatário tiver uma entrada guardada no livro de endereços do remetente, o Outlook resolve o endereço de e-mail para o nome a apresentar guardado do destinatário.

  • É apresentado um ícone de status de reunião do Teams antes do nome ou endereço de e-mail do destinatário.

  • É apresentado um ponto e vírgula após o nome ou endereço de e-mail do destinatário.

  • O nome ou endereço de e-mail do destinatário está sublinhado ou colocado numa caixa.

Para resolve um endereço de e-mail depois de ser adicionado a um item de correio, o remetente tem de utilizar a Tecla de Tabulação ou selecionar um contacto ou endereço de e-mail sugerido a partir da lista de conclusão automática.

No Outlook na Web e no Windows (novo e clássico), se um utilizador criar uma nova mensagem ao ativar a ligação do endereço de e-mail de um contacto a partir do respetivo contacto ou perfil card, a chamada do Recipients.getAsync seu suplemento devolve o endereço de e-mail do contacto na displayName propriedade do objeto EmailAddressDetails associado em vez do nome guardado do contacto. Para obter mais detalhes, veja o problema relacionado com o GitHub.

Ao compor um item de correio, quando muda para uma conta de remetente que está num domínio diferente do da conta de remetente selecionada anteriormente, o valor da recipientType propriedade para destinatários existentes não é atualizado e continuará a ser baseado no domínio da conta selecionada anteriormente. Para obter os tipos de destinatários corretos depois de mudar de conta, primeiro tem de remover os destinatários existentes e, em seguida, adicioná-los novamente ao item de correio.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-bcc-message-compose.yaml

Office.context.mailbox.item.bcc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgBcc = asyncResult.value;
    console.log("Message being blind-copied to:");
    for (let i = 0; i < msgBcc.length; i++) {
      console.log(msgBcc[i].displayName + " (" + msgBcc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.cc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgCc = asyncResult.value;
    console.log("Message being copied to:");
    for (let i = 0; i < msgCc.length; i++) {
      console.log(msgCc[i].displayName + " (" + msgCc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.optionalAttendees.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const apptOptionalAttendees = asyncResult.value;
    for (let i = 0; i < apptOptionalAttendees.length; i++) {
      console.log(
        "Optional attendees: " +
          apptOptionalAttendees[i].displayName +
          " (" +
          apptOptionalAttendees[i].emailAddress +
          ") - response: " +
          apptOptionalAttendees[i].appointmentResponse
      );
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.requiredAttendees.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const apptRequiredAttendees = asyncResult.value;
    for (let i = 0; i < apptRequiredAttendees.length; i++) {
      console.log(
        "Required attendees: " +
          apptRequiredAttendees[i].displayName +
          " (" +
          apptRequiredAttendees[i].emailAddress +
          ") - response: " +
          apptRequiredAttendees[i].appointmentResponse
      );
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.to.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgTo = asyncResult.value;
    console.log("Message being sent to:");
    for (let i = 0; i < msgTo.length; i++) {
      console.log(msgTo[i].displayName + " (" + msgTo[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

setAsync(recipients, options, callback)

Define uma lista de destinatários para um compromisso ou uma mensagem.

O método setAsync substitui a lista de destinatários atual.

setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<void>) => void): void;

Parâmetros

recipients

Array<string | Office.EmailUser | Office.EmailAddressDetails>

Os destinatários a serem adicionados à lista de destinatários. A matriz de destinatários pode conter cadeias de endereços de e-mail SMTP, objetos EmailUser ou objetos EmailAddressDetails .

options
Office.AsyncContextOptions

Um literal de objeto que contém uma ou mais das seguintes propriedades: asyncContext: os programadores podem fornecer qualquer objeto a que pretendam aceder na função de chamada de retorno.

callback

(asyncResult: Office.AsyncResult<void>) => void

Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult. Se a configuração de destinatários falha, a propriedade asyncResult.error conterá um código que indica quaisquer erros que ocorreram ao adicionar os dados.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: item de leitura/escrita

Modo Outlook aplicável: Compose

Importante: com o setAsync método , pode definir um máximo de 100 destinatários no Outlook na Web, no Windows (novo e clássico), no Mac (IU clássica), no Android e no iOS. No entanto, tome nota do seguinte:

  • No Outlook na Web, no Windows (novo e clássico) e no Mac (IU clássica), pode ter um máximo de 500 destinatários num campo de destino. Se precisar de definir mais de 100 destinatários, pode ligar setAsync repetidamente, mas tenha em atenção o limite de destinatários do campo.

  • No Outlook para Android e no iOS, o setAsync método não é suportado no modo Compose Mensagens. Apenas o modo Organizador de Compromissos é suportado. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Não existe limite de destinatários se ligar setAsync para o Outlook no Mac (nova IU).

Erros:

  • NumberOfRecipientsExceeded : o número de destinatários excedeu as 100 entradas.

setAsync(recipients, callback)

Define uma lista de destinatários para um compromisso ou uma mensagem.

O método setAsync substitui a lista de destinatários atual.

setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback: (asyncResult: Office.AsyncResult<void>) => void): void;

Parâmetros

recipients

Array<string | Office.EmailUser | Office.EmailAddressDetails>

Os destinatários a serem adicionados à lista de destinatários. A matriz de destinatários pode conter cadeias de endereços de e-mail SMTP, objetos EmailUser ou objetos EmailAddressDetails .

callback

(asyncResult: Office.AsyncResult<void>) => void

Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult. Se a configuração de destinatários falha, a propriedade asyncResult.error conterá um código que indica quaisquer erros que ocorreram ao adicionar os dados.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: item de leitura/escrita

Modo Outlook aplicável: Compose

Importante: com o setAsync método , pode definir um máximo de 100 destinatários no Outlook na Web, no Windows (novo e clássico), no Mac (IU clássica), no Android e no iOS. No entanto, tome nota do seguinte:

  • No Outlook na Web, no Windows (novo e clássico) e no Mac (IU clássica), pode ter um máximo de 500 destinatários num campo de destino. Se precisar de definir mais de 100 destinatários, pode ligar setAsync repetidamente, mas tenha em atenção o limite de destinatários do campo.

  • No Outlook para Android e no iOS, o setAsync método não é suportado no modo Compose Mensagens. Apenas o modo Organizador de Compromissos é suportado. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Não existe limite de destinatários se ligar setAsync para o Outlook no Mac (nova IU).

Erros:

  • NumberOfRecipientsExceeded : o número de destinatários excedeu as 100 entradas.

Exemplos

// The following example creates an array of EmailUser objects and
// replaces the CC recipients of the message with the array.
const newRecipients = [
    {
        "displayName": "Allie Bellew",
        "emailAddress": "allieb@contoso.com"
    },
    {
        "displayName": "Alex Darrow",
        "emailAddress": "alexd@contoso.com"
    }
];

Office.context.mailbox.item.cc.setAsync(newRecipients, function(result) {
    if (result.error) {
        console.log(result.error);
    } else {
        console.log("Recipients overwritten");
    }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-bcc-message-compose.yaml

const email = $("#emailBcc")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.bcc.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting Bcc field.");
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = $("#emailCc")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.cc.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting Cc field.");
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = $("#emailOptional")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.optionalAttendees.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting optional attendees field.");
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = $("#emailRequired")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.requiredAttendees.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting required attendees field.");
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = $("#emailTo")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.to.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting To field.");
  } else {
    console.error(asyncResult.error);
  }
});