API de e-mail

  • Versão de lançamento: Washingtondc
  • Atualizado 10 de jan. de 2026
  • 7 min. de leitura

    • A API de e- mail fornece endpoints que permitem receber e enviar mensagens de e-mail usando REST.

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

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

    E-mail: GET /now/email/{id}

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

    Formato de URL

    URL com controle de versões: /api/now/{api_version}/email/{id}

    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 acessada. 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 serão retornados detalhes. Localizado na 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

    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/json ou application/xml.

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

    Códigos de status

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

    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 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 dos endereços de e-mail dos destinatários com cópia oculta da mensagem de e-mail. Mapeia para o campo bls_copied.

    Tipo de dados: matriz
    cc Lista dos 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 de nome-valor dos cabeçalhos associados à mensagem e seus valores.

    Tipo de dados: objeto
    html Corpo da mensagem de e-mail habilitado para HTML. 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 de importância.

    Tipo de dados: cadeia de caracteres
    state Estado de processamento da mensagem de e-mail. Indica se os trabalhos programados do sistema processaram a mensagem de e-mail.
    Os valores incluem:
    • Erro
    • ignorada
    • Processado
    • pronto

    Tipo de dados: cadeia de caracteres
    assunto Assunto da mensagem de e-mail. Mapeia para o campo de 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 dos endereços de e-mail dos destinatários diretos da mensagem de e-mail. Mapeia para o campo de destinatários.

    Tipo de dados: matriz
    tipo Estado atual da mensagem de e-mail como e-mail de entrada ou de saída.
    Os valores incluem:
    • recebido(a)
    • recebido-ignorado
    • send-failed
    • send-ignored
    • send-ready
    • enviado

    Tipo de dados: cadeia de caracteres

    Exemplo de solicitação cURL

    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 - POST /now/e-mail

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

    Formato de URL

    URL com controle de versões: /api/now/{api_version}/email

    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 acessada. 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
    Tabela 9. Parâmetros do corpo da solicitação (XML ou JSON)
    Elemento Descrição
    cco Lista dos endereços de e-mail dos destinatários com cópia oculta da mensagem de e-mail. Mapeia para o campo bls_copied.
    Nota:
    Você só pode especificar até 100 endereços neste campo.

    Tipo de dados: matriz
    cc Lista dos 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 de nome-valor dos cabeçalhos associados à mensagem e seus valores.

    Tipo de dados: objeto
    html Corpo da mensagem de e-mail habilitado para HTML. 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 de importância.

    Tipo de dados: cadeia de caracteres
    assunto Assunto da mensagem de e-mail. Mapeia para o campo de 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 parâmetro table_record_id.

    Tipo de dados: cadeia de caracteres
    id_registro_tabela 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 parâmetro table_name.

    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 dos endereços de e-mail dos destinatários diretos da mensagem de e-mail. Mapeia para o campo de 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 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/json ou application/xml.

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

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

    Códigos de status

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

    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. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
    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 no parâmetro href.
    Valores possíveis:
    • self: a solicitação GET da API de e-mail para o registro de e-mail.
    • status: a solicitação GET da API de e-mail para o registro de e-mail mostrando somente os campos de id, tipo, estado e erro.

    Tipo de dados: cadeia de caracteres

    Exemplo de solicitação cURL

    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"
     }
   ]
 }
}