API d’e-mail

  • Rversion finale: Xanadu
  • Mis à jour 9 janv. 2026
  • 6 minutes de lecture

    • L’API de messagerie fournit des points de terminaison qui vous permettent de recevoir et d’envoyer des messages électroniques à l’aide de REST.

    Les utilisateurs doivent disposer du rôle email_api_send pour envoyer des e-mails.

    Remarque :
    Vous pouvez obtenir des erreurs si vous n’avez pas d’accès en lecture/écriture à la table E-mail [sys_email].

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

    Renvoie les détails de l’e-mail pour l’enregistrement d’e-mail spécifié.

    Format d'URL

    URL versionnée : /api/now/{api_version}/email/{id}

    Paramètres de demande pris en charge

    Tableau 1. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. Exemple : v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière.

    Type de données : chaîne
    id Sys_id de l’e-mail pour lequel renvoyer les détails. Situé dans la table E-mail [sys_email].
    Tableau 2. Paramètres de requête
    Nom Description
    sysparm_fields Liste des champs séparés par des virgules à envoyer dans la réponse.

    Type de données : chaîne
    Tableau 3. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    Aucun

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 4. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 5. En-têtes de réponses
    En-tête Description
    Aucun

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 6. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été correctement traitée.
    401 Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
    403 Indique que l’enregistrement est introuvable ou que l’utilisateur demandeur n’a pas accès à l’enregistrement. Vérifiez que l’utilisateur dispose du rôle et des autorisations d’accès appropriés.
    500 Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

    Paramètres du corps de réponse (JSON ou XML)

    Élément Description
    Bcc Liste des adresses e-mail des destinataires envoyés en copie cachée de l’e-mail. Mappé au champ blind_copied.

    Type de données : tableau
    Cc Liste des adresses e-mail des destinataires copiés pour l’e-mail. Mappe au champ copié.

    Type de données : tableau
    en-têtes Paires nom-valeur des en-têtes associés au message et leurs valeurs.

    Type de données : objet
    html Corps de l’e-mail compatible HTML. Mappe au champ du corps.

    Type de données : chaîne
    id Sys_id de l’enregistrement d’e-mail.

    Type de données : chaîne
    importance Importance de l’e-mail. Mappe au champ d’importance.

    Type de données : chaîne
    État État de traitement de l’e-mail. Indique si les travaux planifiés du système ont traité l’e-mail.
    Les valeurs comprennent :
    • erreur
    • ignoré
    • traité
    • prêt

    Type de données : chaîne
    objet Objet de l’e-mail. Mappe au champ Objet.

    Type de données : chaîne
    Texte Corps de texte uniquement de l’e-mail. Mappe au champ body_text.

    Type de données : chaîne
    à Liste des adresses des destinataires directs de l’e-mail. Mappe au champ des destinataires.

    Type de données : tableau
    type État actuel du message électronique en tant que courrier entrant ou sortant.
    Les valeurs comprennent :
    • reçu
    • reçu ignoré
    • envoi échoué
    • envoi ignoré
    • prêt à envoyer
    • envoyé

    Type de données : chaîne

    Exemple de demande 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

    Crée un enregistrement d’e-mail à l’aide des informations transmises.

    Format d'URL

    URL versionnée : /api/now/{api_version}/email

    Paramètres de demande pris en charge

    Tableau 7. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. Exemple : v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière.

    Type de données : chaîne
    Tableau 8. Paramètres de requête
    Nom Description
    Aucun
    Tableau 9. Paramètres de corps de demande (XML ou JSON)
    Élément Description
    Bcc Liste des adresses e-mail des destinataires envoyés en copie cachée de l’e-mail. Mappé au champ blind_copied.
    Remarque :
    Vous ne pouvez spécifier que 100 adresses maximum dans ce champ.

    Type de données : tableau
    Cc Liste des adresses e-mail des destinataires copiés pour l’e-mail. Mappe au champ copié.
    Remarque :
    Vous ne pouvez spécifier que 100 adresses maximum dans ce champ.

    Type de données : tableau
    en-têtes Paires nom-valeur des en-têtes associés au message et leurs valeurs.

    Type de données : objet
    html Corps de l’e-mail compatible HTML. Mappe au champ du corps.

    Type de données : chaîne
    importance Importance de l’e-mail. Mappe au champ d’importance.

    Type de données : chaîne
    objet Objet de l’e-mail. Mappe au champ Objet.

    Type de données : chaîne
    table_name Nom de la table pour enregistrer l’e-mail. Utilisez ce paramètre pour associer un message électronique à un enregistrement connexe particulier ailleurs dans le système.
    Remarque :
    Ce paramètre nécessite également de spécifier le table_record_id paramètre.

    Type de données : chaîne
    table_record_id Enregistrement lié à la cible auquel l’e-mail s’applique. Utilisez ce paramètre pour associer un message électronique à un enregistrement connexe particulier ailleurs dans le système.
    Remarque :
    Ce paramètre nécessite également de spécifier le table_name paramètre.

    Type de données : chaîne
    Texte Corps de texte uniquement de l’e-mail. Mappe au champ body_text.

    Type de données : chaîne
    à Requis. Liste des adresses e-mail des destinataires directs de l’e-mail. Mappe au champ des destinataires.
    Remarque :
    Vous ne pouvez spécifier que 100 adresses maximum dans ce champ.

    Type de données : tableau

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 10. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Content-Type Format de données du corps de la demande. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 11. En-têtes de réponses
    En-tête Description
    Aucun

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 12. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été correctement traitée.
    400 Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté.
    401 Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
    403 L’utilisateur demandeur n’a pas accès à l’enregistrement. Vérifiez que l’utilisateur dispose du rôle et des autorisations d’accès appropriés.
    500 Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

    Paramètres du corps de réponse (JSON ou XML)

    Élément Description
    href Lien vers l’enregistrement d’e-mail en tant que demande GET d’API d’e-mail.

    Type de données : chaîne
    id Sys_id de l’enregistrement d’e-mail.

    Type de données : chaîne
    Liens Liste des liens vers l’enregistrement d’e-mail.

    Type de données : tableau
    Rel Type de lien répertorié dans le href paramètre.
    Valeurs possibles :
    • self : demande GET de l’API d’e-mail pour l’enregistrement d’e-mail.
    • état : demande GET de l’API d’e-mail pour l’enregistrement d’e-mail affichant uniquement les champs d’ID, de type, d’état et d’erreur.

    Type de données : chaîne

    Exemple de demande 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"
     }
   ]
 }
}