API de e-mail

  • Versão de lançamento: Yokohama
  • Atualizado 25 de jun. de 2026
  • 7 min. de leitura

    • . E-mail A API fornece endpoints que permitem que você receba e envie mensagens de e-mail usando REST.

    Os usuários devem ter a função EMAIL_api_send para enviar e-mail.

    Nota:
    Você pode obter erros se não tiver acesso de leitura/gravação à tabela E-mail [sys_email].

    E-mail - OBTENHA /now/e-mail/

    Retorna os detalhes de e-mail do registro de e-mail especificado.

    Formato de URL

    URL com controle de versão: /api/now/

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para APIs REST com script, há informações adicionais de versão no Serviço REST com script .

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. Por exemplo, v1 ou v2 . Especifique este valor somente para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: Cadeia de caracteres
    id Sys_id do e-mail para o qual retornar detalhes.

    Tipo de dados: Cadeia de caracteres

    Tabela: E-mail [sys_email]
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    sysparm_fields Lista separada por vírgulas de campos a serem retornados na resposta.

    Tipo de dados: Cadeia de caracteres
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    Nenhum(a)

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos da REST API compatíveis .

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte REST API códigos de resposta HTTP .

    Tabela 6. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Indica que o registro não foi encontrado ou que o usuário solicitante não tem acesso ao registro. Verifique se o usuário tem a função adequada e as permissões de acesso.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Elemento Descrição
    Cco Lista de endereços de e-mail dos destinatários copiados sem confirmação da mensagem de e-mail. Mapeia para o campo blind_copied.

    Tipo de dados: Matriz
    cc Lista de endereços de e-mail dos destinatários copiados da mensagem de e-mail. Mapeia para o campo copiado.

    Tipo de dados: Matriz
    cabeçalhos Pares nome-valor dos cabeçalhos associados à mensagem e seus valores.

    Tipo de dados: Objeto
    html Corpo habilitado para HTML da mensagem de e-mail. Mapeia para o campo do corpo.

    Tipo de dados: Cadeia de caracteres
    id Sys_id do registro de e-mail.

    Tipo de dados: Cadeia de caracteres
    importância Importância da mensagem de e-mail. Mapeia para o campo Importância.

    Tipo de dados: Cadeia de caracteres
    estado Estado de processamento da mensagem de e-mail. Indica se os trabalhos agendados do sistema processaram a mensagem de e-mail.
    Possível incluir:
    • erro
    • ignorada
    • processado
    • pronto

    Tipo de dados: Cadeia de caracteres
    assunto Assunto da mensagem de e-mail. Mapeia para o campo Assunto.

    Tipo de dados: Cadeia de caracteres
    texto Corpo somente de texto da mensagem de e-mail. Mapeia para o campo body_text.

    Tipo de dados: Cadeia de caracteres
    para Lista de endereços de e-mail dos destinatários diretos da mensagem de e-mail. Mapeia para o campo Destinatários.

    Tipo de dados: Matriz
    tipo Estado atual da mensagem de e-mail como e-mail de entrada ou saída.
    Valores possíveis:
    • recebido(a)
    • recebido-ignorado
    • envio-falhou
    • envio-ignorado
    • envio-pronto
    • enviado

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl de amostra

    curl "http://instance.servicenow.com/api/now/email/06e095427f0022007f005212bdfa91b3" \
--request GET \
--header "Accept:application/json" \
--user "user-name":"password"

    {
  "result" : {
    "headers" : {
      "X-ServiceNow-SysEmail-Version" : "2",
      "X-ServiceNow-Source" : "Notification-24e34b54c61122aa0108c1b7a33697cf"
    },
    "cc" : [
      ""
    ],
    "type" : "send-ready",
    "html" : "<html><head></head><body><div><p><font size=\"5\" color=\"#808080\" face=\"helvetica\"><strong>Incident has been closed.</strong></font></p></div>\n\t\t<div><p><font size=\"4\" color=\"#808080\" face=\"helvetica\"><strong>Summary details</strong></font></p><p><font size=\"3\" color=\"#808080\" face=\"helvetica\">Closed by: System Administrator</font></p><p><font size=\"3\" color=\"#808080\" face=\"helvetica\">Closed notes: Fixed</font></p></div>\n\t\t<div><p><font size=\"3\" color=\"#808080\" face=\"helvetica\">You can view all the details of the incident by following the link below:</font></p><font face=\"helvetica\"><a href=\"incident.do?sys_id=e8e875b0c0a80164009dc852b4d677d5&amp;sysparm_stack=incident_list.do?sysparm_query=active=true\" style=\"background-color: #278efc;border: 1px solid #0368d4;color: #ffffff;font-size: 16px;font-family: Helvetica, Arial, sans-serif;text-decoration: none; border-radius: 3px;-webkit-border-radius: 3px;-moz-border-radius: 3px;display: inline-block;padding: 5px;\">Take me to the Incident</a></font><br /><br /><p><font size=\"3\" color=\"#808080\" face=\"helvetica\">Thank you.</font></p></div><div> </div><div style=\"display:inline\">Ref:MSG0000006</div></body></html>",
    "bcc" : [
      ""
    ],
    "subject" : "Your incident INC0000005 has been closed",
    "to" : [
      "alejandro.mascall@example.com"
    ],
    "state" : "ready",
    "id" : "06e095427f0022007f005212bdfa91b3",
    "importance" : "",
    "text" : ""
  }
}

    E-mail - PUBLICAR /now/e-mail

    Cria um registro de e-mail usando as informações aprovadas.

    Formato de URL

    URL com controle de versão: /api/now/

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para APIs REST com script, há informações adicionais de versão no Serviço REST com script .

    Parâmetros de solicitação compatíveis

    Tabela 7. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. Por exemplo, v1 ou v2 . Especifique este valor somente para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: Cadeia de caracteres
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 9. Parâmetros do corpo da solicitação (XML ou JSON)
    Elemento Descrição
    Cco Lista de endereços de e-mail dos destinatários copiados sem confirmação da mensagem de e-mail. Mapeia para o campo blind_copied.
    Nota:
    Você só pode especificar até 100 endereços neste campo.

    Tipo de dados: Matriz
    cc Lista de endereços de e-mail dos destinatários copiados da mensagem de e-mail. Mapeia para o campo copiado.
    Nota:
    Você só pode especificar até 100 endereços neste campo.

    Tipo de dados: Matriz
    cabeçalhos Pares nome-valor dos cabeçalhos associados à mensagem e seus valores.

    Tipo de dados: Objeto
    html Corpo habilitado para HTML da mensagem de e-mail. Mapeia para o campo do corpo.

    Tipo de dados: Cadeia de caracteres
    importância Importância da mensagem de e-mail. Mapeia para o campo Importância.

    Tipo de dados: Cadeia de caracteres
    assunto Assunto da mensagem de e-mail. Mapeia para o campo Assunto.

    Tipo de dados: Cadeia de caracteres
    table_name Nome da tabela para salvar o e-mail. Use este parâmetro para associar uma mensagem de e-mail a um registro relacionado específico em outro lugar do sistema.
    Nota:
    Este parâmetro também requer a especificação de table_record_idparâmetro.

    Tipo de dados: Cadeia de caracteres
    table_record_id Registro relacionado ao destino ao qual o e-mail se aplica. Use este parâmetro para associar uma mensagem de e-mail a um registro relacionado específico em outro lugar do sistema.
    Nota:
    Este parâmetro também requer a especificação de table_nameparâmetro.

    Tipo de dados: Cadeia de caracteres
    texto Corpo somente de texto da mensagem de e-mail. Mapeia para o campo body_text.

    Tipo de dados: Cadeia de caracteres
    para Necessário. Lista de endereços de e-mail dos destinatários diretos da mensagem de e-mail. Mapeia para o campo Destinatários.
    Nota:
    Você só pode especificar até 100 endereços neste campo.

    Tipo de dados: Matriz

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos da REST API compatíveis .

    Tabela 10. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tabela 11. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte REST API códigos de resposta HTTP .

    Tabela 12. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 O usuário solicitante não tem acesso ao registro. Verifique se o usuário tem a função adequada e as permissões de acesso.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Elemento Descrição
    href Link para o registro de e-mail como uma solicitação de OBTENÇÃO da API de e-mail.

    Tipo de dados: Cadeia de caracteres
    id Sys_id do registro de e-mail.

    Tipo de dados: Cadeia de caracteres
    links Lista de links para o registro de e-mail.

    Tipo de dados: Matriz
    rel Tipo de link listado em hrefparâmetro.
    Valores possíveis:
    • Si: A solicitação de OBTENÇÃO da API de e-mail para o registro de e-mail.
    • Status: A solicitação de OBTENÇÃO da API de e-mail para o registro de e-mail mostrando somente os campos ID, tipo, estado e erro.

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl de amostra

    curl "http://instance.servicenow.com/api/now/email" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user 'username':'password'\
--data "{
  \"to\": [
    \"User1 <user1@example.com>\",
    \"User2 <user2@example.com>\"
  ],
  \"cc\": [
    \"User3 <user3@example.com>\",
    \"User4 <user4@example.com>\"
  ],
  \"bcc\": [
    \"User5 <user5@example.com>\",
    \"User6 <user6@example.com>\"
  ],
  \"subject\": \"Hello There\",
  \"text\": \"Test Message\",
  \"html\": \"<b>Test Message</b>\",
  \"table_name\": \"incident\",
  \"table_record_id\": \"136b2140bd0312004d7d1371f1abbdb6\",
  \"headers\": {
    \"X-Custom\": \"header\"
  }
}"
    {
 "result": {
   "id": "b963219a44b02200964f63773cd6adfc",
   "links": [
     {
       "rel": "self",
       "href": "/now/v1/email/b963219a44b02200964f63773cd6adfc"
     },
     {
       "rel": "status",
       "href": "/now/v1/email/b963219a44b02200964f63773cd6adfc?sysparm_fields=id,type,state,error"
     }
   ]
 }
}