API de e-mail

  • Versão de lançamento: Yokohama
  • Atualizado 9 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-mail.

    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 de e-mail do registro de e-mail especificado.

    Formato da URL

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

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário 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 acessada. Por exemplo, v1 ou v2. Somente especifique este valor 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 os detalhes serão retornados.

    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 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(a)

    Códigos de status

    Os seguintes códigos de status 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 de 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 dos endereços de e-mail dos destinatários de cópia oculta da mensagem de e-mail. Mapas para o campo "blog_copied".

    Tipo de dados: matriz
    cc Lista dos endereços de e-mail dos destinatários copiados da mensagem de e-mail. Mapas 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. Mapas 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. Mapas para o campo de 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íveis incluem:
    • erro
    • ignorada
    • Processado
    • pronto

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

    Tipo de dados: cadeia de caracteres
    texto Corpo somente texto da mensagem de e-mail. Mapas 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. Mapas 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.
    Valores possíveis:
    • recebido(a)
    • recebido-ignorado
    • send-failed
    • send-ignored
    • send-ready
    • enviado

    Tipo de dados: cadeia de caracteres

    Amostra 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/email

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

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/email

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário 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 acessada. Por exemplo, v1 ou v2. Somente especifique este valor 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 dos endereços de e-mail dos destinatários de cópia oculta da mensagem de e-mail. Mapas para o campo "blog_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. Mapas 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. Mapas para o campo do corpo.

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

    Tipo de dados: cadeia de caracteres
    assunto Assunto da mensagem de e-mail. Mapas 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
    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 parâmetro table_name.

    Tipo de dados: cadeia de caracteres
    texto Corpo somente texto da mensagem de e-mail. Mapas 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. Mapas 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(a)

    Códigos de status

    Os seguintes códigos de status 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 de 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. 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 ID, tipo, estado e erro.

    Tipo de dados: cadeia de caracteres

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