Email-API

  • Freigeben Version: Washingtondc
  • Aktualisiert 10. Januar 2026
  • 5 Minuten Lesedauer

    • Die Email -API bietet Endpunkte, mit denen Sie E-Mail-Nachrichten mit REST empfangen und senden können.

    Benutzer müssen über die Rolle „email_api_send“ verfügen, um eine E-Mail senden zu können.

    Hinweis:
    Sie erhalten möglicherweise Fehler, wenn Sie keinen Lese-/Schreibzugriff auf die E-Mail-Tabelle [sys_email] haben.

    Email – GET /now/email/{id}

    Gibt die E-Mail-Details für den angegebenen E-Mail-Datensatz zurück.

    URL-Format

    Versionierte URL: /api/now/{api_version}/email/{id}

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden.

    Datentyp: Zeichenfolge
    id Sys_id der E-Mail, für die Details zurückgegeben werden sollen. Befindet sich in der E-Mail-Tabelle [sys_email].
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    sysparm_fields Kommagetrennte Liste mit Feldern, die in der Antwort zurückgegeben werden sollen.

    Datentyp: Zeichenfolge
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    Keine

    Kopfzeilen

    Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST-API verwendet werden, finden Sie unter Unterstützte REST-API-Header.

    Tabelle : 4. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Tabelle : 5. Antwortkopfzeilen
    Kopfzeile Beschreibung
    Keine

    Statuscodes

    Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST-API verwendet werden, finden Sie unter HTTP-Antwortcodesder REST-API.

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    403 Zeigt an, dass der Datensatz nicht gefunden wurde oder der anfordernde Benutzer keinen Zugriff auf den Datensatz hat. Stellen Sie sicher, dass der Benutzer über die richtigen Rollen und Zugriffsberechtigungen verfügt.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Antworttextparameter (JSON oder XML)

    Element Beschreibung
    bcc Liste der E-Mail-Adressen der auf BCC gesetzten Empfänger der E-Mail-Nachricht. Ist dem Feld „blind_copied“ zugeordnet.

    Datentyp: Array
    cc Liste der E-Mail-Adressen der kopierten Empfänger für die E-Mail-Nachricht. Ist dem Feld „copied“ zugeordnet.

    Datentyp: Array
    headers Name-Wert-Paare der der Nachricht zugeordneten Header und deren Werte.

    Datentyp: Objekt
    html HTML-fähiger Textkörper der E-Mail-Nachricht. Ist dem Feld „body“ zugeordnet.

    Datentyp: Zeichenfolge
    id Sys_id des E-Mail-Datensatzes.

    Datentyp: Zeichenfolge
    importance Wichtigkeit der E-Mail-Nachricht. Ist dem Feld „importance“ zugeordnet.

    Datentyp: Zeichenfolge
    Status Verarbeitungsstatus der E-Mail-Nachricht. Gibt an, ob die geplanten Aufgaben des Systems die E-Mail-Nachricht verarbeitet haben.
    Werte:
    • error
    • ignored
    • processed
    • Bereit

    Datentyp: Zeichenfolge
    Betreff Betreff der E-Mail-Nachricht. Ist dem Feld „subject“ zugeordnet.

    Datentyp: Zeichenfolge
    HTML Nur-Text-Text der E-Mail-Nachricht. Ist dem Feld „boy_text“ zugeordnet.

    Datentyp: Zeichenfolge
    bis Liste der E-Mail-Adressen der direkten Empfänger der E-Mail-Nachricht. Ist dem Feld „recipients“ zugeordnet.

    Datentyp: Array
    type Aktueller Status der E-Mail-Nachricht als eingehende oder ausgehende E-Mail.
    Werte:
    • received
    • erhalten (ignoriert)
    • senden (fehlgeschlagen)
    • senden (ignoriert)
    • send-ready
    • gesendet

    Datentyp: Zeichenfolge

    Beispiel für eine cURL-Anforderung

    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

    Erstellt einen E-Mail-Datensatz mit den übergebenen Informationen.

    URL-Format

    Versionierte URL: /api/now/{api_version}/email

    Unterstützte Anforderungsparameter

    Tabelle : 7. Pfadparameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden.

    Datentyp: Zeichenfolge
    Tabelle : 8. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 9. Anforderungstextparameter (XML oder JSON)
    Element Beschreibung
    bcc Liste der E-Mail-Adressen der auf BCC gesetzten Empfänger der E-Mail-Nachricht. Ist dem Feld „blind_copied“ zugeordnet.
    Hinweis:
    Sie können in diesem Feld nur bis zu 100 Adressen angeben.

    Datentyp: Array
    cc Liste der E-Mail-Adressen der kopierten Empfänger für die E-Mail-Nachricht. Ist dem Feld „copied“ zugeordnet.
    Hinweis:
    Sie können in diesem Feld nur bis zu 100 Adressen angeben.

    Datentyp: Array
    headers Name-Wert-Paare der der Nachricht zugeordneten Header und deren Werte.

    Datentyp: Objekt
    html HTML-fähiger Textkörper der E-Mail-Nachricht. Ist dem Feld „body“ zugeordnet.

    Datentyp: Zeichenfolge
    importance Wichtigkeit der E-Mail-Nachricht. Ist dem Feld „importance“ zugeordnet.

    Datentyp: Zeichenfolge
    Betreff Betreff der E-Mail-Nachricht. Ist dem Feld „subject“ zugeordnet.

    Datentyp: Zeichenfolge
    table_name Name der Tabelle zum Speichern der E-Mail. Verwenden Sie diesen Parameter, um eine E-Mail-Nachricht einem bestimmten zugehörigen Datensatz an anderer Stelle im System zuzuordnen.
    Hinweis:
    Für diesen Parameter muss auch der Parameter table_record_id angegeben werden.

    Datentyp: Zeichenfolge
    table_record_id Zielbezogener Datensatz, für den die E-Mail gilt. Verwenden Sie diesen Parameter, um eine E-Mail-Nachricht einem bestimmten zugehörigen Datensatz an anderer Stelle im System zuzuordnen.
    Hinweis:
    Für diesen Parameter muss auch der Parameter table_name angegeben werden.

    Datentyp: Zeichenfolge
    HTML Nur-Text-Text der E-Mail-Nachricht. Ist dem Feld „boy_text“ zugeordnet.

    Datentyp: Zeichenfolge
    bis Erforderlich. Liste der E-Mail-Adressen der direkten Empfänger für die E-Mail-Nachricht. Ist dem Feld „recipients“ zugeordnet.
    Hinweis:
    Sie können in diesem Feld nur bis zu 100 Adressen angeben.

    Datentyp: Array

    Header

    Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST-API verwendet werden, finden Sie unter Unterstützte REST-API-Header.

    Tabelle : 10. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Content-Type Datenformat des Anforderungstexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Tabelle : 11. Antwortkopfzeilen
    Kopfzeile Beschreibung
    Keine

    Statuscodes

    Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST-API verwendet werden, finden Sie unter HTTP-Antwortcodesder REST-API.

    Tabelle : 12. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    403 Der anfordernde Benutzer hat keinen Zugriff auf den Datensatz. Stellen Sie sicher, dass der Benutzer über die richtigen Rollen- und Zugriffsberechtigungen verfügt.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Antworttextparameter (JSON oder XML)

    Element Beschreibung
    href Link zum E-Mail-Datensatz als E-Mail-API-GET-Anforderung.

    Datentyp: Zeichenfolge
    id Sys_id des E-Mail-Datensatzes.

    Datentyp: Zeichenfolge
    Links Liste der Links zum E-Mail-Datensatz.

    Datentyp: Array
    rel Typ des Links, der im Parameter href aufgeführt ist.
    Mögliche Werte:
    • self: GET-Anforderung der Email-API für den E-Mail-Datensatz.
    • status: GET-Anforderung der Email-API für den E-Mail-Datensatz, der nur die Felder „id“, „type“, „state“ und „error“ anzeigt.

    Datentyp: Zeichenfolge

    Beispiel für eine cURL-Anforderung

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