用户: sendMail

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

使用 JSON 或 MIME 格式发送请求正文中指定的邮件。

使用 JSON 格式时,可以包含附件,并使用提及在新邮件中调用其他用户。

使用 MIME 格式时:

  • 提供适用的 Internet 邮件头 和 MIME 内容,所有内容在请求正文中都通过 base64 格式进行编码。
  • 向 MIME 内容添加任何附件和 S/MIME 属性。

此方法将邮件保存在“已发送邮件”文件夹中。

或者,创建草稿邮件稍后发送。

要了解有关邮件递送给收件人之前后端涉及的步骤的更多信息,请参阅 此处。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) Mail.Send 不可用。
委派(个人 Microsoft 帐户) Mail.Send 不可用。
应用程序 Mail.Send 不可用。

HTTP 请求

POST /me/sendMail
POST /users/{id | userPrincipalName}/sendMail

请求标头

名称 类型 说明
Authorization string 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type string 实体正文中的数据性质。 必填。
对 JSON 对象使用 application/json,对 MIME 内容使用 text/plain。

请求正文

使用 JSON 格式时,提供具有以下参数的 JSON 对象。

参数 类型 说明
邮件 邮件 要发送的邮件。 必需。
SaveToSentItems Boolean 指示是否将邮件保存在“已发送邮件”文件夹中。 仅当参数为 false 时指定;默认值为 true。 可选。

要使用提及在新消息中调用其他用户,请执行以下操作:

  • 在请求正文中包括所需的 toRecipients 属性、 提及属性 和任何可写消息属性。
  • 对于提及属性中的每个提及,必须指定提及的属性。

当指定 MIME 格式的正文时,请在请求正文中提供 MIME 内容为 base64 编码的字符串。 请勿包含参数。

响应

如果成功,此方法返回 202 Accepted 响应代码。 它不会返回响应正文中的任何内容。

注意: 202 Accepted 响应代码表示请求已被接受;但并不表示请求处理已完成。 邮件的传递受 Exchange Online 限制和限制的约束。

如果请求正文包含格式不正确的 MIME 内容,此方法将返回 400 Bad request 并显示以下错误消息:“MIME 内容的 base64 字符串无效。”

示例

示例 1:使用 JSON 格式发送新电子邮件

请求

POST https://graph.microsoft.com/beta/me/sendMail
Content-type: application/json

{
  "message": {
    "subject": "Meet for lunch?",
    "body": {
      "contentType": "Text",
      "content": "The new cafeteria is open."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "samanthab@contoso.com"
        }
      }
    ],
    "ccRecipients": [
      {
        "emailAddress": {
          "address": "danas@contoso.com"
        }
      }
    ]
  },
  "saveToSentItems": "false"
}

响应

HTTP/1.1 202 Accepted

示例 2:发送包含 @ 提及的消息

此示例显示登录用户给 Samantha Booth 的消息。 该消息还提及了另一位用户达纳·斯沃普 (Dana Swope)。

请求

POST https://graph.microsoft.com/beta/me/sendMail
Content-type: application/json

{
  "message": {
    "subject": "Project kickoff",
    "toRecipients": [
      {
        "emailAddress": {
          "name": "Samantha Booth",
          "address": "samanthab@contoso.com"
        }
      }
    ],
    "mentions": [
      {
        "mentioned": {
          "name": "Dana Swope",
          "address": "danas@contoso.com"
        }
      }
    ]
  }
}

响应

HTTP/1.1 202 Accepted

示例 3:发送包含自定义 Internet 邮件头的邮件

请求

POST https://graph.microsoft.com/beta/me/sendMail
Content-type: application/json

{
  "message": {
    "subject": "9/9/2018: concert",
    "body": {
      "contentType": "HTML",
      "content": "The group represents Nevada."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "AlexW@contoso.com"
        }
      }
    ],
    "internetMessageHeaders": [
      {
        "name": "x-custom-header-group-name",
        "value": "Nevada"
      },
      {
        "name": "x-custom-header-group-id",
        "value": "NV001"
      }
    ]
  }
}

响应

HTTP/1.1 202 Accepted

示例 4:发送包含文件附件的邮件

请求

POST https://graph.microsoft.com/beta/me/sendMail
Content-type: application/json

{
  "message": {
    "subject": "Meet for lunch?",
    "body": {
      "contentType": "Text",
      "content": "The new cafeteria is open."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "meganb@contoso.com"
        }
      }
    ],
    "attachments": [
      {
        "@odata.type": "#microsoft.graph.fileAttachment",
        "name": "attachment.txt",
        "contentType": "text/plain",
        "contentBytes": "SGVsbG8gV29ybGQh"
      }
    ]
  }
}

响应

HTTP/1.1 202 Accepted

示例 5:使用 MIME 格式发送新邮件

请求

POST https://graph.microsoft.com/beta/me/sendMail
Content-type: text/plain

RnJvbTogQWRlbGUgVmFuY2UgPEFkZWxlVkBjb250b3NvLmNvbT4KVG86IEFsZXggV2lsYmVyIDxB
bGV4V0Bjb250b3NvLmNvbT4KU3ViamVjdDpUZXN0IE1lc3NhZ2UKQ29udGVudC1UeXBlOiBtdWx0
aXBhcnQvbWl4ZWQ7Cglib3VuZGFyeT0iXzAwNF9UWVpQUjA0TUI2OTgxNzNGRDAwMjE1MkQ1QURC
OEZCNDdDOEJDQVRZWlBSMDRNQjY5ODFhcGNwXyIKTUlNRS1WZXJzaW9uOiAxLjAKCi0tXzAwNF9U
WVpQUjA0TUI2OTgxNzNGRDAwMjE1MkQ1QURCOEZCNDdDOEJDQVRZWlBSMDRNQjY5ODFhcGNwXwpD
b250ZW50LVR5cGU6IG11bHRpcGFydC9hbHRlcm5hdGl2ZTsKCWJvdW5kYXJ5PSJfMDAwX1RZWlBS
MDRNQjY5ODE3M0ZEMDAyMTUyRDVBREI4RkI0N0M4QkNBVFlaUFIwNE1CNjk4MWFwY3BfIgoKLS1f
MDAwX1RZWlBSMDRNQjY5ODE3M0ZEMDAyMTUyRDVBREI4RkI0N0M4QkNBVFlaUFIwNE1CNjk4MWFw
Y3BfCkNvbnRlbnQtVHlwZTogdGV4dC9wbGFpbjsgY2hhcnNldD0iaXNvLTg4NTktMSIKQ29udGVu
dC1UcmFuc2Zlci1FbmNvZGluZzogcXVvdGVkLXByaW50YWJsZQoKdGVzdCB0ZXh0IGJvZHkKCgot
LV8wMDBfVFlaUFIwNE1CNjk4MTczRkQwMDIxNTJENUFEQjhGQjQ3QzhCQ0FUWVpQUjA0TUI2OTgx
YXBjcF8KQ29udGVudC1UeXBlOiB0ZXh0L2h0bWw7IGNoYXJzZXQ9Imlzby04ODU5LTEiCkNvbnRl
bnQtVHJhbnNmZXItRW5jb2Rpbmc6IHF1b3RlZC1wcmludGFibGUKCjxodG1sPgo8aGVhZD4KPC9o
ZWFkPgo8Ym9keT4KdGVzdCBodG1sIGJvZHkKPC9ib2R5Pgo8L2h0bWw+CgotLV8wMDBfVFlaUFIw
NE1CNjk4MTczRkQwMDIxNTJENUFEQjhGQjQ3QzhCQ0FUWVpQUjA0TUI2OTgxYXBjcF8tLQoKLS1f
MDA0X1RZWlBSMDRNQjY5ODE3M0ZEMDAyMTUyRDVBREI4RkI0N0M4QkNBVFlaUFIwNE1CNjk4MWFw
Y3BfCkNvbnRlbnQtVHlwZTogdGV4dC9wbGFpbjsKQ29udGVudC1EaXNwb3NpdGlvbjogYXR0YWNo
bWVudDsKICAgICAgICBmaWxlbmFtZT0idGVzdC50eHQiCgp0aGlzIGlzIHRoZSBhdHRhY2htZW50
IHRleHQKCi0tXzAwNF9UWVpQUjA0TUI2OTgxNzNGRDAwMjE1MkQ1QURCOEZCNDdDOEJDQVRZWlBS
MDRNQjY5ODFhcGNwXy0t

响应

以下示例显示了相应的响应。

HTTP/1.1 202 Accepted

如果请求正文包含错误的 MIME 内容,此方法返回以下错误消息。

HTTP/1.1 400 Bad Request
Content-type: application/json

{
  "error": {
    "code": "ErrorMimeContentInvalidBase64String",
    "message": "Invalid base64 string for MIME content."
  }
}

示例 6:发送带有后续标志的新邮件

请求

POST https://graph.microsoft.com/beta/me/sendMail
Content-type: application/json

{
  "subject": "Please respond by Friday",
  "toRecipients": [
    {
      "emailAddress": {
        "address": "meganb@contoso.com"
      }
    }
  ],
  "flag": {
    "flagStatus": "flagged",
    "startDateTime": {
      "dateTime": "2023-08-30T12:13:00",
      "timeZone": "Eastern Standard Time"
    },
    "dueDateTime": {
      "dateTime": "2023-09-01T17:00:00",
      "timeZone": "Eastern Standard Time"
    }
  }
}

响应

HTTP/1.1 202 Accepted