Email-API

  • Freigeben Version: Yokohama
  • Aktualisiert 9. Januar 2026
  • 5 Minuten Lesedauer

    • Die E-Mail- API stellt Endpunkte bereit, 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:
    Wenn Sie keinen Lese-/Schreibzugriff auf die E-Mail-Tabelle [sys_email] haben, erhalten Sie möglicherweise Fehler.

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

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

    URL-Format

    URL mit Versionsnummer: /api/now/{api_version}/email/{id}

    Hinweis:
    Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

    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.

    Datentyp: Zeichenfolge

    Tabelle: E-Mail [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-Antwortcodes der 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.

    Parameter des Antworttexts (JSON oder XML)

    Element Beschreibung
    bcc Liste der E-Mail-Adressen der Blindkopie-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 Header, die der Nachricht zugeordnet sind, und ihre 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
    state Verarbeitungsstatus der E-Mail-Nachricht. Gibt an, ob die E-Mail-Nachricht von den geplanten Systemaufgaben verarbeitet wurde.
    Möglich sind:
    • Fehler
    • ignored
    • processed
    • Bereit

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

    Datentyp: Zeichenfolge
    text Nur-Text-Textkörper 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
    Typ Aktueller Status der E-Mail-Nachricht als eingehende oder ausgehende E-Mail.
    Mögliche Werte:
    • empfangen
    • 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 anhand der übergebenen Informationen.

    URL-Format

    URL mit Versionsnummer: /api/now/{api_version}/email

    Hinweis:
    Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

    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 Blindkopie-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 Header, die der Nachricht zugeordnet sind, und ihre 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:
    Dieser Parameter erfordert auch die Angabe des Parameters table_record_id.

    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:
    Dieser Parameter erfordert auch die Angabe des Parameters table_name.

    Datentyp: Zeichenfolge
    text Nur-Text-Textkörper 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-Antwortcodes der 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 Anwender 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.

    Parameter des Antworttexts (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"
     }
   ]
 }
}