이메일 API

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 06월 16일
  • 소요 시간: 11분

    • 이메일 API는 REST를 사용하여 이메일 메시지를 주고받을 수 있는 엔드포인트를 제공합니다.

    사용자에게 이메일을 보내려면 email_api_send 역할이 있어야 합니다.

    주:
    이메일 [sys_email] 테이블에 대한 읽기/쓰기 권한이 없는 경우 오류가 발생할 수 있습니다.

    이메일 - GET /now/email/{id}

    지정된 이메일 기록에 대한 이메일 상세 정보를 반환합니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/email/{id}

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오.

    데이터 유형: 문자열
    ID 상세 정보를 반환할 이메일의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 이메일 [sys_email]
    표 2. 쿼리 매개변수
    이름 설명
    sysparm_fields 응답에서 반환할 필드의 쉼표로 구분된 목록입니다.

    데이터 유형: 문자열
    표 3. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    안 함

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 고유한 방식으로 이 작업에 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하십시오.

    표 4. 요청 헤더
    머리글 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 5. 응답 헤더
    머리글 설명
    안 함

    상태 코드

    이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

    표 6. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    401 권한이 해제되었습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 기록을 찾을 수 없거나 요청하는 사용자가 기록에 액세스할 수 없음을 나타냅니다. 사용자에게 적절한 역할과 접근 권한이 있는지 확인하십시오.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON 또는 XML)

    요소 설명
    숨은 참조 이메일 메시지의 숨은 참조 수신자의 이메일 주소 목록입니다. blind_copied 필드에 매핑합니다.

    데이터 유형: 배열
    cc 이메일 메시지의 복사된 수신자의 이메일 주소 목록입니다. 복사된 필드에 매핑합니다.

    데이터 유형: 배열
    헤더 메시지 및 해당 값과 연결된 헤더의 이름-값 쌍입니다.

    데이터 유형: 객체
    HTML 이메일 메시지의 HTML 지원 본문입니다. 본문 필드에 매핑합니다.

    데이터 유형: 문자열
    ID 이메일 기록의 Sys_id입니다.

    데이터 유형: 문자열
    중요도 이메일 메시지의 중요도입니다. 중요도 필드에 매핑합니다.

    데이터 유형: 문자열
    상태 이메일 메시지의 처리 상태입니다. 시스템 예약된 작업이 이메일 메시지를 처리했는지 여부를 나타냅니다.
    가능한 항목은 다음과 같습니다.
    • 오류
    • 무시됨
    • 처리됨
    • 준비

    데이터 유형: 문자열
    주제 이메일 메시지의 제목입니다. 제목 필드에 매핑합니다.

    데이터 유형: 문자열
    텍스트 이메일 메시지의 텍스트 전용 본문입니다. body_text 필드에 매핑합니다.

    데이터 유형: 문자열
    대상 이메일 메시지의 직접 수신자의 이메일 주소 목록입니다. 수신자 필드에 매핑합니다.

    데이터 유형: 배열
    유형 수신 메일 또는 발신 메일로 이메일 메시지의 현재 상태입니다.
    가능한 값:
    • 수신됨
    • 수신-무시됨
    • 전송 실패
    • 보내기 - 무시됨
    • 전송-준비
    • 보냄

    데이터 유형: 문자열

    샘플 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" : ""
  }
}

    이메일 - POST /now/email

    전달된 정보를 사용하여 이메일 기록을 작성합니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/email

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 7. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오.

    데이터 유형: 문자열
    표 8. 쿼리 매개변수
    이름 설명
    안 함
    표 9. 요청 본문 매개변수(XML 또는 JSON)
    요소 설명
    숨은 참조 이메일 메시지의 숨은 참조 수신자의 이메일 주소 목록입니다. blind_copied 필드에 매핑합니다.
    주:
    이 필드에는 주소를 100개까지만 지정할 수 있습니다.

    데이터 유형: 배열
    cc 이메일 메시지의 복사된 수신자의 이메일 주소 목록입니다. 복사된 필드에 매핑합니다.
    주:
    이 필드에는 주소를 100개까지만 지정할 수 있습니다.

    데이터 유형: 배열
    헤더 메시지 및 해당 값과 연결된 헤더의 이름-값 쌍입니다.

    데이터 유형: 객체
    HTML 이메일 메시지의 HTML 지원 본문입니다. 본문 필드에 매핑합니다.

    데이터 유형: 문자열
    중요도 이메일 메시지의 중요도입니다. 중요도 필드에 매핑합니다.

    데이터 유형: 문자열
    주제 이메일 메시지의 제목입니다. 제목 필드에 매핑합니다.

    데이터 유형: 문자열
    table_name 이메일을 저장할 테이블의 이름입니다. 이 매개변수를 사용하여 이메일 메시지를 시스템의 다른 곳에 있는 특정 관련 기록에 연결합니다.
    주:
    이 매개변수도 매개변수를 지정해야 합니다.table_record_id

    데이터 유형: 문자열
    table_record_id 이메일이 적용되는 대상 관련 기록입니다. 이 매개변수를 사용하여 이메일 메시지를 시스템의 다른 곳에 있는 특정 관련 기록에 연결합니다.
    주:
    이 매개변수도 매개변수를 지정해야 합니다.table_name

    데이터 유형: 문자열
    텍스트 이메일 메시지의 텍스트 전용 본문입니다. body_text 필드에 매핑합니다.

    데이터 유형: 문자열
    대상 필수 이메일 메시지의 직접 수신자의 이메일 주소 목록입니다. 수신자 필드에 매핑합니다.
    주:
    이 필드에는 주소를 100개까지만 지정할 수 있습니다.

    데이터 유형: 배열

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 고유한 방식으로 이 작업에 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하십시오.

    표 10. 요청 헤더
    머리글 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    콘텐츠-형식 요청 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 11. 응답 헤더
    머리글 설명
    안 함

    상태 코드

    이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

    표 12. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    401 권한이 해제되었습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 요청 사용자는 기록에 접근할 수 있는 권한이 없습니다. 사용자에게 적절한 역할과 접근 권한이 있는지 확인합니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON 또는 XML)

    요소 설명
    href 이메일 기록에 이메일 API GET 요청으로 연결합니다.

    데이터 유형: 문자열
    ID 이메일 기록의 Sys_id입니다.

    데이터 유형: 문자열
    링크 이메일 기록으로 연결되는 링크 목록입니다.

    데이터 유형: 배열
    관계 매개변수에 나열된 링크의 유형입니다.href
    가능한 값:
    • self: 이메일 기록에 대한 이메일 API GET 요청입니다.
    • status: ID, 유형, 상태 및 오류 필드만 표시하는 이메일 기록에 대한 이메일 API GET 요청입니다.

    데이터 유형: 문자열

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