10000.000
CCS M21
YD
中 华 人 民 共 和 国 通 信 行 业 标 准
YD/T 4422—2023
基于表述性状态转移(REST)技术的业务能力开放应用程序接口 (API)邮件业务
RESTful based service capability open API——Email
2023-07-28发布 2023-11-01实施
中华人民共和国工业和信息化部 发 布
YD/T 4422—2023
目 次
前言……………………………………………………………………………………………………………………………………………………………………………………………………… . II
1 范围……………………………………………………………………………………………………………………………………………………… 1
2 规范性引用文件……………………………………………………………………………………………………………………… 1
3 术语、定义和缩略语…………………………………………………………………………………………………………………… 1
3.1 术语和定义…………………………………………………………………………………………………………………………………… 1
3.2 缩略语…………………………………………………………………………………………………………………………………………………… 2
4 邮件业务概述………………………………………………………………………………………………………………………………………… 2
5 邮件业务API定义………………………………………………………………………………………………………………………………………… 3
5.1 概述…………………………………………………………………………………………………………………………………………………………… 3
5.2 资源概述……………………………………………………………………………………………………………………………………………………………………………… 3
5.3 数据类型………………………………………………………………………………………………………………………………………………… 7
6 资源详细定义…………………………………………………………………………………………………………………………………………………………………………………13
6.1 通用要求…………………………………………………………………………………………………………………………………………………………………………………………13
6.2 用户接口……………………………………………………………………………………………………………………………………………………………………………………………13
6.3 标签接口…………………………………………………………………………………………………………………………………………………………………………………………27
6.4 草稿接口…………………………………………………………………………………………………………………………………………………………………………………………34
6.5 邮件夹接口…………………………………………………………………………………………………………………………………………………………………………44
6.6 附件接口…………………………………………………………………………………………………………………………………………………………………………………………52
6.7 电子邮件接口………………………………………………………………………………………………………………………………………………………………………………57
7 安全要求………………………………………………………………………………………………………………………………………………………………………………………………………81
7.1 认证和授权……………………………………………………………………………………………………………………………………………………………………………………81
7.2 API访问权限和频率控制……………………………………………………………………………………………………………………………………………………82
附录A（规范性）响应码要求……………………………………………………………………………………………………………………………………………………83
1
YD/T 4422—2023
前 言
本文件按照GB/T1.1—2020《标准化工作导则 第1部分：标准化文件的结构和起草规则》的规定起草。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。
本文件由中国通信标准化协会提出和归口。
本文件起草单位：西安交通大学、中国电信集团有限公司。
本文件主要起草人：曲桦、赵季红、李金艳、吴彤、杨峰义、张彦鹏、边江、刘伟、张斌。
Ⅱ
YD/T 4422—2023
基于表述性状态转移 (REST)的业务能力
开放应用程序接口 (API)邮件业务
1 范围
本文件规定了基于表述性状态转移(REST)技术实现邮件业务的开放应用程序接口 (API)，包括接口的资源定义、资源操作、数据结构和安全要求等。
本文件适用于提供邮件业务能力开放的应用程序接口 (API)的研发、测试。
2 规范性引用文件
下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。
YD/T2144—2010 基于简单邮件传输协议(SMTP)的互联网中文电子邮件地址技术要求
YD/T2423—2012 基于表述性状态转移(REST)技术的电信业务能力开放平台技术要求
IETF RFC2616传输控制协议(Hypertext Transfer Protocol HTTP/1.1)
IETF RFC3986 统一资源标识符(URI):通用语法（Uniform Resource Identifier(URI): Generic Syntax）
IETF RFC4627 JavaScript对象标记(json) 的application/ json媒体类型[The application/ json Media Type for JavaScript Object Notation (JSON)]
3 术语、定义和缩略语
3.1 术语和定义
下列术语和定义适用于本文件。
3.1.1
表述性状态转移 representational state transfer
一种针对网络应用的设计和开发方式，指的是一组架构约束条件和原则，可以降低开发的复杂性，提高系统的可伸缩性。
[来源：YD/T2423—2012]
1
YD/T 4422—2023
3.1.2
电子邮件 email
在计算机网络上，用户终端之间往来的信函。
[来源：YD/T 2144--2010]
3.1.3
黑名单 blackname
记录发送垃圾邮件的服务器的IP或者主机信息的名单。
[来源：YD/T 1311—2004]
3.2 缩略语
下列缩略语适用于本标准。
API 应用程序编程接口 Application Programming Interface
Autho4A PI 网络应用程序接口授权框架 Authorization Framework for Network APIs
HTML 超文本标记语言 Hypertext Markup Language
HTTP 超文本传输协议 Hyper Text Transfer Protocol
IP 因特网协议 Internet Protocol
JSON JavaScript对象表示法 JavaScript Object Notation
MIME 多功能网络邮件扩展 Multipurpose Internet Mail Extensions
OMA 开放移动联盟 Open Mobile Alliance
REST 表述性状态转移 Representational State Transfer
SMTP 简单邮件传输协议 Simple Mail Transfer Protocol
URI 统一资源标识 Uniform Resource Identifier
URL 统一资源定位符 Uniform Resource Locator
XML 扩展标记语言 eXtensible Markup Language
XSD XML模式定义 XML Schema Definition
4 邮件业务概述
电子邮件(Email)业务是指两个用户终端通过计算机网络交换电子邮件的一种服务。该业务为一对多服务，即每个邮件发送方可对应一个或多个邮件接收用户。
邮件业务具有一下业务特征：
———支持获取用户信息、更新用户信息、获取通讯录、添加通讯录、移出通讯录、获取黑名单、添加黑名单、移出黑名单；
——支持创建标签、获取标签、获取标签列表、删除标签、更新标签；
———支持创建草稿、获取草稿、获取草稿列表、删除草稿、更新草稿；
———支持创建邮件夹、获取邮件夹、获取邮件夹列表、删除邮件夹、更新邮件夹；
2
YD/T 4422—2023
——支持获取邮件附件、获取邮件附件列表、删除邮件附件；
——支持创建邮件、发送邮件、获取邮件、获取邮件列表、删除邮件、批量删除邮件、更新邮件、修改邮件标签、批量修改邮件标签、移动邮件、批量移动邮件；
———本标准以邮件基本业务为主，并选取邮件业务中其他常见和重要功能，编写邮件业务能力开放接口。随着邮件业务发展，所包含的业务功能可适时扩充。
5 邮件业务API定义
5.1 概述
本章介绍了邮件业务 API 的设计，它详细的介绍了所有资源的定义，所有数据结构的定义，所有指定资源的详细操作定义。
5.2 资源概述
本节简要概括了关于邮件业务的REST风格API中所用到的所有资源。
本标准中URL变量“apiVersion”的取值为“v1”,表明API对应于本标准,URL变量“apiVersion”的语义定义见（OMA OMA-TS-REST NetAPI Common-V1 0.
图1可视化地展示了邮件业务API中定义的资源树结构图。资源树中那些与本标准中定义的HTTP方法关联的节点用固体盒子（实体源）描述。
YD/T 4422—2023
//{serverRoot}/ email/'epiVersion]/[userld]
user
contacts
addContacts
removeContacts
blackList
addBlackList
removeBlackList
labels
{labelld}
drafts
{draftld}
folders
[folderId]
emails
[cmailId]
attachments
[attachment]d]
modifyEmail
moveEmail
sendEmail
batchDeleteEmails
batchModifyEmails
batchMoveEmails
图1 邮件业务的资源结构
下面的表格给出了本标准中定义的资源的概述，其数据类型表示和允许的HTTP方法。
表1对邮件基础业务进行了具体的描述，包括创建邮件、发送邮件、获取邮件、获取邮件列表、删除邮件、批量删除邮件、更新邮件、修改邮件标签、批量修改邮件标签、移动邮件、批量移动邮件等功能，并对其资源的详细说明、数据结构以及允许的HTTP方法做了概述。
表1 邮件基础业务
资源 URL BaseURL:http://{serverRoot}/{apiVersion} 数据结构 HTTP方法
GET PUT POST DELETE
创建邮件 / emails Email 否 否 返回创建成功的邮件信息 否
发送邮件 / emails/sendEmail Email 否 否 返回接受邮件发送请求消息 否
获取邮件 / emails/{cmailId} Email 返回单个邮件否 否 否
4
YD/T4422—2023
表1 邮件基础业务（续）
资源 URL BaseURL:http://{serverRoot}/{apiVersion} 数据结构 HTTP方法
GET PUT POST DELETE
获取邮件列表 / emails Emails 返回邮件列表否 否 否
删除邮件 / emails/{emailId} 否 否 否 返回成功删除的消息
批量删除邮件 / emails/batchDeleteEmails Emailds 否 否 否 返回成功删除的消息
更新邮件 / emails/{emailId} Email 否 返回单个邮件 否 否
修改邮件标签 / emails/{emailId}/modifyEmail LabelIds 否 否 返回单个邮件 否
批量修改邮件标签 emails/batchModityEmails EmailsLabelIds 否 否 返回修改成功的消息 否
移动邮件 / emails/{emailld}/moveEmail Email 否 否 返回单个邮件 否
批量移动邮件 emails/batchMoveEmails EmailIdsEmails 否 否 返回邮件列表 否
表2对邮件用户相关业务进行了具体的描述，包括获取用户信息、更新用户信息、获取通讯录、添加通讯录、移出通讯录、获取黑名单、添加黑名单、移出黑名单等功能，并对其资源的详细说明、数据结构以及允许的HTTP方法做了概述。
表2 邮件业务用户
资源 URL BaseURL:http://{serverRoot}/{apiVersion} 数据结构 HTTP方法
GET PUT POST DELETE
获取用户信息 / user EmailAccount 返回用户信息 否 否 否
更新用户信息 / user EmailAccount 否 返回用户信息否 否
获取通讯录 / user/ contacts Contacts 返回联系人列表 否 否 否
添加通讯录 / user/ contacts/addContacts Contacts 否 否 返回联系人列表 否
移出通讯录 / user/ contacts/removeContacts 否 否 返回联系人列表 否
获取黑名单 /user/blackList BlackList 返回非名单 否 否 否
添加黑名单 / user/blackList/addBlackList BlackList 否 否 返回非名单 否
5
YD/T 4422—2023
表2 邮件业务用户（续）
资源 URL BaseURL:http://{serverRoot}/{api Version} 数据结构 HTTP方法
GET PUT POST DELETE
移出黑名单 / user/blackList/removeBlackList BlackList 否 否 返回非名单 否
表3对邮件标签进行了具体的描述，包括创建标签、获取标签、获取标签列表、删除标签、更新标签等功能，并对其资源的详细说明、数据结构以及允许的HTTP方法做了概述。
表3 邮件标签
资源 URL BaseURL:http://{serverRoot}/{apiVersion} 数据结构 HTTP方法
GET PUT POST DELETE
创建标签 / labels Label 否 否 返回创建成功的消息 否
获取标签 / labels/{labeIId} Label 返回单个标签 否 否 否
获取标签列表 / labels Labels 返回标签列表 否 否 否
删除标签 / labels/{labelId} 否 否 否 返回删除成功的消息
更新标签 / labels/{labelId} Label 否 返回单个标签 否 否
表4对邮件草稿进行了具体的描述，包括创建草稿、获取草稿、获取草稿列表、删除草稿、更新草稿等功能，并对其资源的详细说明、数据结构以及允许的HTTP方法做了概述。
表4 邮件草稿
资源 URL BaseURL:http://{serverRoot}/{apiVersion} 数据结构 HTTP方法
GET PUT POST DELETE
创建草稿 / drafts Draft 否 否 返回创建成功的消息 否
获取草稿 / drafts/{draftId} Draft 返回单个草稿否 否 否
获取草稿列表 / drafts Drafts 返回草稿列表否 否 否
删除草稿 / drafts/{draftId} 否 否 否 返回成功删除的消息
更新草稿 / drafts/{draftId} Draft 否 返回单个草稿 否 否
表5对邮件业务的邮件夹进行了具体的描述，包括创建邮件夹、获取邮件夹、获取邮件夹列表、删除邮件夹、更新邮件夹等功能，并对其资源的详细说明、数据结构和允许的HTTP方法做了概述。
6
YD/T 4422—2023
表5 邮件业务邮件夹
资源 URL BaseURL:http://{serverRoot}/{apiVersion} 数据结构 HTTP方法
GET PUT POST DELETE
创建邮件夹 / folders Folder 否 否 返回创建成功的消息 否
获取邮件夹 / folders/{folderId} Folder 返回单个邮件夹否 否 否
获取邮件夹列表 / folders Folders 返回邮件夹列表否 否 否
删除邮件夹 / folders/{folderId} 否 否 否 返回成功删除的消息
更新邮件夹 folders/{folderId} Folder 否 返回邮件夹信息 否 否
表6对邮件附件进行了具体的描述，包括创建邮件附件、获取邮件附件、获取邮件附件列表、删除邮件附件、更新邮件附件等功能，并对其资源的详细说明、数据结构和允许的HTTP方法做了概述。
表6 邮件附件
资源 URL BaseURL:http://{serverRoot}/{apiVersion} 数据结构 HTTP方法
GET PUT POST DELETE
获取邮件附件 / attachments/{attachmentId} Attachment 返回单个邮件附件 否 否 否
获取邮件附件列表 / attachments Attachments 返回邮件附件列表 否 否 否
删除邮件附件 / attachments/{attachmentId} 否 否 否 返回成功删除的消息
5.3 数据类型
5.3.1 XML命名空间
邮件业务RESTful API数据类型XML命名空间是：
urn: oma: xml: rest: netapi: email:1
本标准中以“xsd”为命名前缀的数据类型引用了W3CXML Schemal, W3CXML Schema2中定义的XML数据类型。“common”命名空间前缀引用了OMA OMA-TS-REST NetAPI Common中定义的数据类型.命名前缀的使用，例如，‘xsd’，并没有语义上的重要性。
5.3.2 数据结构
5.3.2.1 概述
本节对邮件业务RESTful网络API中使用的数据结构进行了定义。
7
YD/T 4422—2023
5.3.2.2 类型：Email
Emial数据结构的定义见表7.
表7 Emial数据结构
元素 类型 必选/可选 描述
emailld xsd: string 必选 邮件唯一且不可变标识符
parentFolderId xsd: string 必选 邮件的父邮件夹的唯一标识符
from EmailAccount[0.. unbounded] 必选 发件人集合
to EmailAccount[0.. unbounded] 必选 收件人集合
subject xsd: string 必选 邮件主题
date xsd:dateTime 必选 邮件生成或更新的时间
size xsd:positiveInteger 可选 邮件大小，以字节为单位
importance Important 可选 邮件的重要性
labels Label[0.. unbounded] 可选 邮件标签
bodyPreview xsd: string 可选 邮件正文中的前255个字符作为邮件摘要
body xsd: string 必选 邮件正文
attachment Attachment 可选 邮件附件
一个具有Emial数据类型的email根元素允许出现在通知请求和/或响应的消息体中。
5.3.2.3 类型：Emails
Emials数据结构的定义见表8.
表8 Emials数据结构
元素 类型 必选/可选 描述
emails Email[0.. unbounded] 必选 邮件集合
emailCount xsd: integer 必选 邮件集合大小
5.3.2.4 类型：Emaillds
EmialIds数据结构的定义见表9.
表9 Emiallds数据结构
元素 类型 必选/可选 描述
ids xsd: string[0.. unbounded] 必选 邮件唯一标识符集合
emailIdCount xsd: integer 必选 邮件唯一标识符集合大小
8
YD/T4422—2023
一个具有Attachments数据类型的attachments根元素允许出现在通知请求的消息体中。
5.3.2.5 类型：EmaillAccount
EmialAccount数据结构的定义见表10.
表10 EmialAccount数据结构
元素 类型 必选/可选 描述
accountAddress xsd: string 必选 由RFC822指定格式的邮件用户邮件地址，如, accountName@ example.com
accountName xsd: string 必选 邮件用户昵称（例如，张三）
一个具有EmialAccount数据类型的emialAccount根元素允许出现在通知响应的消息体中。
5.3.2.6 类型：Contacts
Contacts数据结构的定义见表11.
表11 Contacts数据结构
元素 类型 必选/可选 描述
accounts EmailAccount[0.. unbounded] 必选 邮件用户集合
accountTotal xsd: integer 必选 通讯录长度
一个具有Contacts数据类型的contacts根元素允许出现在通知响应的消息体中。
5.3.2.7 类型：BlackList
BlackList数据结构的定义见表12.
表12 BlackList数据结构
元素 类型 必选/可选 描述
accounts EmailAccount[0.. unbounded] 必选 属于黑名单的邮件用户集合
accountTotal xsd: integer 必选 黑名单长度
一个具有BlackList数据类型的blackList根元素允许出现在通知响应的消息体中。
5.3.2.8 类型：Label
Label数据结构的定义见表13.
表13 Label数据结构
元素 类型 必选/可选 描述
labelId xsd: string 必选 标签唯一标识符
9
YD/T 4422—2023
表13 Label数据结构（续）
元素 类型 必选/可选 描述
labelName xsd: string 必选 标签显示名称，如，已读
type Type 必选 标签的所有者类型。用户标签由用户创建，用户可以修改和删除。系统标签是系统内部创建的，不能添加、修改和删除
一个具有Label数据类型的label根元素允许出现在通知响应的消息体中。
5.3.2.9 类型：Labels
Labels数据结构的定义见表14.
表14 Labels数据结构
元素 类型 必选/可选 描述
labels Label[0. unbounded] 必选 标签集合
labelCount xsd: integer 必选 标签集合大小
一个具有Labels数据类型的labels根元素允许出现在通知响应的消息体中。
5.3.2.10 类型：Labellds
LabelIds数据结构的定义见表15.
表15 Labellds数据结构
元素 类型 必选/可选 描述
ids xsd: string[0.. unbounded] 必选 标签唯一标识符集合
labelIdCount xsd: integer 必选 标签唯一标识符集合大小
5.3.2.11 类型：Draft
Draft数据结构的定义见表16.
表16 Draft数据结构
元素 类型 必选/可选 描述
draftId xsd: string 必选 草稿唯一标识符
email Email 必选 草稿的邮件内容
一个具有Draft数据类型的draft根元素允许出现在通知响应的消息体中。
5.3.2.12 型：Drafts
Drafts数据结构的定义见表17.
10
YD/T 4422—2023
表17 Drafts数据结构
元素 类型 必选/可选 描述
drafts Draft[0.. unbounded] 必选 草稿集合
draftCount xsd: integer 必选 草稿集合大小
一个具有Drafts数据类型的drafts根元素允许出现在通知响应的消息体中。
5.3.2.13 类型：Attachment
Attachment数据结构的定义见表18.
表18 Attachment数据结构
元素 类型 必选/可选 描述
attId xsd: string 必选 附件唯一标识符
attName xsd: string 必选 附件的文件名
type xsd: string 可选 MIME 类型，用来表示附件类型，在IETF RFC 6838中进行了定义和标准化
size xsd:positiveInteger 可选 附件大小，以字节为单位
data xsd: string 必选 用URL和文件名安全字母(有时称为“web-safe”或”base64url”)编码的填充的、base64编码的字节串。由RFC4648定义的
一个具有Attachment数据类型的attachment根元素允许出现在通知响应的消息体中。
5.3.2.14 类型：Attachments
Attachments数据结构的定义见表19.
表19 Attachments数据结构
元素 类型 必选/可选 描述
atts Attachment[0.. unbounded] 必选 附件集合
attCount xsd: integer 必选 附件集合大小
一个具有Attachments数据类型的attachments根元素允许出现在通知响应的消息体中。
5.3.2.15 类型：Folder
Folder数据结构的定义见表20.
11
YD/T 4422—2023
表20 Folder数据结构
元素 类型 必选/可选 描述
folderId xsd: string 必选 邮件夹唯一标识符
emailIds xsd: string[0.. unbounded] 必选 邮件唯一标识符集合
folderName xsd: string 必选 邮件夹名称
totalItemCount xsd: integer 可选 邮件夹内邮件总数
readCount xsd: integer 可选 邮件夹内已读邮件数
unreadCount xsd: integer 可选 邮件夹内未读邮件数
type Type 必选 邮件夹的所有者类型。用户邮件夹由用户创建，用户可以修改和删除。系统邮件夹是系统内部创建的，不能添加、修改和删除
一个具有Folder数据类型的folder根元素允许出现在通知响应的消息体中。
5.3.2.16 类型：Folders
Folders数据结构的定义见表21.
表21 Folders数据结构
元素 类型 必选/可选 描述
folders Folder[0.. unbounded] 必选 邮件夹集合
folderCount xsd: integer 必选 邮件夹集合大小
一个具有Folders数据类型的folders根元素允许出现在通知响应的消息体中。
5.3.2.17 类型：Type
Type数据结构的定义见表22.
表22 Type数据结构
枚举值 描述
SYSTEM 系统类型
USER 用户自定义类型
5.3.2.18 MIME组合消息的表示
在邮件业务API中，附件的上传与获取操作可以在HTTP请求中包含文件内容，此类具有多个实体的消息体的MIME采用“multipart/form-data”格式，其中，第一个实体将包含数据根元素，第二个实体包括多媒体内容,“multipart/ form-data”格式的消息体结构的详细定义见OMA OMA-TS-REST NetAPI Common-V1 0.
12
YD/T 4422—2023
6 资源详细定义
6.1 通用要求
下列规定对本标准定义的资源都适用，而和资源的表示格式无关(即XML、JSON、application/x-www-form-urlencoded):
———遵循IETF RFC3986规定, URL变量（即URL中花括号“{}”中的参数）中的保留字符应是采用百分号编码（例如“%3B”编码表示“：”），该要求对请求行中的请求URL和消息体中的资源表示(例如“link”元素中的“resourceURL”) 都适用。
———如果一个anyURL类型的用户标识是MSISDN形式，该用户标识应为IETF RFC3966定义的全球号码(例如.tel:+19585550100)，除数字和开始字符“+”外，其他字符应避免使用，该要求对URL变量和HTTP消息体的中用户标识参数都适用。
———如果一个anyIURL类型的用户标识是SIP URL形式，该用户标识应遵循IETF RFC3621.
———如果一个anyIURL类型的用户标识是ACR形式，该用户标识应遵循IETF ACR draft, 即在ACR前应包含一个协议前缀“acr:”.”auth”是一个保留字符，不能被用在最终用户标识中，详见A.3.
——当请求和响应消息有消息体时，服务器应支持使用JSON和XML编码的消息体。服务器应根据内容类型协商(见OMA OMA-TS-REST NetAPI Common-V1 0)的结果在响应消息中返回JSON或XML编码的消息体；在发送给客户端的通知消息中，服务器应根据客户端订阅请求中指定的格式采用JSON或XML格式对消息体进行编码。
——JSON的格式描述见IETF RFC4627, JSON表示的生成和处理应遵循OMA OMA-TS-REST NetAPI Common-V1 0中规定的HTTP请求/响应中JSON编码规则。
6.2 用户接口
6.2.1 获取用户信息的资源
6.2.1.1 概述
获取用户信息的资源是：
http://{serverRoot}/ email/{apiVersion}/{userId}/ user
该资源表示获取邮件用户的基本信息。
6.2.1.2 请求URL变量
请求URL变量描述见表23.
表23 请求URL变量
名称 说明
serverRoot
服务器URL: 主机名称+端口+基础路径。端口和基础路径为可选。例如, http:// example.com/
exampleAPI
13
YD/T 4422—2023
表23 请求URL变量（续）
名称 说明
apiVersion 客户希望使用的API版本，其取值见第5.2节的定义
userId 邮件业务用户使用的唯一地址，由RFC822指定格式的邮件地址。例如, accountName@ example.com
URL变量的保留字符见第6.1节的定义。
6.2.1.3 响应码和错误处理
HTTP响应码见OMA OMA-TS-REST NetAPI Common-V1 0的定义及附录A所列举部分。
6.2.1.4 GET
该操作被用作获取用户信息。
示例1：获取用户信息
请求
GET /exampleAPI/ email/v1/ accountl@example.com/userHTTP/1.1
Accept: application/ json
Host:example.com
响应
返回的资源数据是EmailAccount类型的数据，即邮件用户信息。
HTTP/1.1 200 OK
Date: Mon,05 April 2021 10:30:05 GMT
Content-Type: application/ json
Content-Length: nnnn
{
"emailAccount": {
"accountAddress": "accountl@example.com",
"accountName":"张三“
}
}
6.2.1.5 PUT
该资源不允许使用本方法，返回的HTTP错误状态是405。遵循IETF RFC2616第14.7节，服务器在响应时还应包括“Allow: GET, POST”字段。
6.2.1.6 POST
该资源不允许使用本方法，返回的HTTP错误状态是405。遵循IETF RFC2616第14.7节，服务器在响应时还应包括“Allow: GET, POST”字段。
14
YD/T 4422—2023
6.2.1.7 DELETE
该资源不允许使用本方法，返回的HTTP错误状态是405。遵循IETF RFC2616第14.7节，服务器在响应时还应包括“Allow: GET, POST”字段。
6.2.2 更新用户信息的资源
6.2.2.1 概述
更新用户信息的资源是：
http://{serverRoot}/ email/{apiVersion}/{userId}/ user
该资源表示更新邮件用户的基本信息。
6.2.2.2 请求URL变量
请求URL变量描述见表24.
表24 请求URL变量
名称 说明
serverRoot
服务器URL：主机名称+端口+基础路径。端口和基础路径为可选。例如，
http:// example.com/exampleAPI
apiVersion 客户希望使用的API版本，其取值见第5.2节的定义
userId
邮件业务用户使用的唯一地址，由RFC822指定格式的邮件地址。例如，
accountName@ example.com
URL变量的保留字符见第6.1节的定义。
6.2.2.3 响应码和错误处理
HTTP响应码见OMA OMA-TS-REST NetAPI Common-V1 0的定义及附录A所列举部分。
6.2.2.4 GET
该资源不允许使用本方法，返回的HTTP错误状态是405。遵循IETF RFC2616第14.7节，服务器在响应时还应包括“Allow: GET, POST”字段。
6.2.2.5 PUT
该操作被用作更新用户信息。
示例1：更新用户信息
请求
请求URL参数见表25.
15
YD/T 4422—2023
表25 更新用户信息请求URL参数
元素 类型 必选/可选 描述
accountName xsd: string 必选 邮件用户昵称（例如，张三）
PUT /exampleAPI/ email/v1/account1@example.com/userHTTP/1.1
Accept: application/ json
Host:example.com
{
"accountName":"李四“
}
响应
返回的资源数据是EmailAccount类型的数据，即邮件用户信息。
HTTP/1.1 200 OK
Date: Mon,05 April 2021 10:30:05 GMT
Content-Type: application/ json
Content-Length: nnnn
{
"emailAccount": {
"accountAddress":"accountl@example. com",
"accountName":"李四“
}
}
6.2.2.6 POST
该资源不允许使用本方法，返回的HTTP错误状态是405。遵循IETF RFC2616第14.7节，服务器在响应时还应包括“Allow: GET, POST”字段。
6.2.2.7 DELETE
该资源不允许使用本方法，返回的HTTP错误状态是405。遵循IETF RFC2616第14.7节，服务器在响应时还应包括“Allow: GET, POST”字段。
6.2.3 获取通讯录
6.2.3.1 概述
获取用户通讯录的资源是：
http://{serverRoot}/ email/{apiVersion}/{userId}/ user/ contacts
该资源表示获取用户通讯录的基本信息。
16
YD/T 4422—2023
6.2.3.2 请求URL变量
请求URL变量描述见表26.
表26 请求URL变量
名称 说明
serverRoot
服务器URL：主机名称+端口+基础路径。端口和基础路径为可选。例如，
http:// example.com/exampleAPI
apiVersion 客户希望使用的API版本，其取值见第5.2节的定义
userId
邮件业务用户使用的唯一地址，由RFC822指定格式的邮件地址。例如，
accountName@ example.com
URL变量的保留字符见第6.1节的定义。
6.2.3.3 响应码和错误处理
HTTP响应码见OMA OMA-TS-REST NetAPI Common-V1 0的定义及附录A所列举部分。
6.2.3.4 GET
该操作被用作获取用户通讯录。
示例1：获取用户通讯录
请求
GET /exampleAPI/ email/v1/ accountl@example.com/user/contactsHTTP/1.1
Accept: application/ json
Host:example.com
{