API de e-mail

  • Versão de lançamento: Zurich
  • Atualizado 13 de mar. 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/email/

    Retorna os detalhes do 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 REST APIs com script, há informações adicionais de versão no Formulário de 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 a ser acessado. 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. Solicitar parâmetros do corpo (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 de 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 Códigos de resposta HTTP da REST API .

    Tabela 6. Códigos de status
    Código do 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 e as permissões de acesso apropriadas.
    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 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 Processando estado 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 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
    • send-failed
    • send-ignored
    • send-ready
    • 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/api/email

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para REST APIs com script, há informações adicionais de versão no Formulário de 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 a ser acessado. 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. Solicitar parâmetros do corpo (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:
    Só é possível 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:
    Só é possível 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 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 no sistema.
    Nota:
    Este parâmetro também requer a especificação do 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 no sistema.
    Nota:
    Este parâmetro também requer a especificação do table_nameparâmetro.

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

    Tipo de dados: Cadeia de caracteres
    para Obrigatório. Lista de endereços de e-mail dos destinatários diretos da mensagem de e-mail. Mapeia para o campo Destinatários.
    Nota:
    Só é possível 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 de 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 Códigos de resposta HTTP da REST API .

    Tabela 12. Códigos de status
    Código do 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 e as permissões de acesso apropriadas.
    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 GET 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:
    • A API de e-mail OBTER solicitação para o registro de e-mail.
    • Status: A API de e-mail OBTER solicitação 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"
     }
   ]
 }
}