Gmail API - 如何查看电子邮件打开日期？

Question

我需要使用 Google API 来检索电子邮件第一次被标记为视图的时间（特别是打开电子邮件时）。

我使用 GET https://gmail.googleapis.com/gmail/v1/users/{userId}/messages/{id} 仅请求元数据来获取消息，但响应如下所示：

{
  "id": "17a05bd8db1609b9",
  "threadId": "17a05bd8db1609b9",
  "labelIds": [
    "CATEGORY_PROMOTIONS",
    "UNREAD",
    "INBOX"
  ],
  "payload": {
    "partId": "",
    "headers": [
      {
        "name": "Delivered-To",
        "value": "{EMAIL ADDRESS}"
      },
      {
        "name": "Received",
        "value": "by 2002:a55:c51e:0:b029:e9:12c1:65a9 with SMTP id b30csp1876084egk;        Sun, 13 Jun 2021 07:19:06 -0700 (PDT)"
      },
      {
        "name": "X-Google-Smtp-Source",
        "value": "ABdhPJzPcWJR1zsvAH654luf+agnL6i6CGj8S/jO1MDZVz3yPHcqE7y37chZ7euL02n40t6idUB/"
      },
      {
        "name": "X-Received",
        "value": "by 2002:a9d:62ce:: with SMTP id z14mr10328566otk.255.1623593946243;        Sun, 13 Jun 2021 07:19:06 -0700 (PDT)"
      },
      {
        "name": "ARC-Seal",
        "value": "i=1; a=rsa-sha256; t=1623593946; cv=none;        d=google.com; s=arc-20160816;        b=L8L+Vz979TjsIDtXAyhnPBQUmW8Njjz+DiyScOHFvyHbmOC9sIyaH5AFOafzFou45N         nTtpzyq9pSlZ8VWd6N9N+NYcdldf67A7/FarG9iIs6EvddVYcpbEqdTPOyMt6/mluVQO         utRoX3ma1TFAIyXoQLvxfPZ5QZLZNQFpPwYWGIkB+/8r45OKkqhuWtX8d93InKgpoVIf         NQjaI4Tnr2AJWWJjiALL8bLoCe1QvA3mV+I1sTbGRPZAIPcKfm+nB3smYgkH7f9C+1+8         iXR/45AWh+9Sxd1IFrHHokfTEOQvHEWDXm8BBagCFaRFJv45V+FIyWGJKKpL4UCI0oab         7ZRg=="
      },
      {
        "name": "ARC-Message-Signature",
        "value": "i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816;        h=list-unsubscribe-post:list-unsubscribe:mime-version:subject         :message-id:to:reply-to:from:date:dkim-signature:dkim-signature;        bh=3CtcdJdIFbH5c/+55q2hcIqL8foXcatroOK85FVqTxk=;        b=0/F/Qn1AmdXlp7t9Or1qvUB+6xmvr2Ewxm33BtMBo956QCvgQQ5qilxt3ZI1Kqx+YB         zuQZLKRcG7T1kRqvsq3ERdrAqAr6P8+I6j9yWw6XaI7uuU8crVbnEjbkUAheFjmNeXOP         ZcuwtlUPlgDiyOmE6ND2HWLrpUcCKxx/TY17fYkR/H08yr44BqtTXSJVUG12n5Sjb8iA         nnFyJHYBRg2Elw7vMnUl+wiO0k1EH9C7ltwTJCjVsDPe0LcvcjtDcr0R4i24sYbNTDgN         fyOsKMfJnPAE/oLk6iZhd0NvWVkUUvop6b8kdZtLfVH1jLMIYPBOlNjeSct+yfmtrHWt         Vrwg=="
      },
      {
        "name": "ARC-Authentication-Results",
        "value": "i=1; mx.google.com;       dkim=pass header.i=@emails.waves-audio.com header.s=gears header.b=AAcEguTx;       dkim=pass header.i=@d.messagegears.io header.s=gears header.b=jvFNHriZ;       spf=pass (google.com: domain of 346064636000c23595702-b21164-83d6be2bdc4542f7a574924245020c5e@emails.waves-audio.com designates 135.84.217.27 as permitted sender) smtp.mailfrom=346064636000c23595702-b21164-83d6be2bdc4542f7a574924245020c5e@emails.waves-audio.com"
      },
      {
        "name": "Return-Path",
        "value": "\u003c346064636000c23595702-b21164-83d6be2bdc4542f7a574924245020c5e@emails.waves-audio.com\u003e"
      },
      {
        "name": "Received",
        "value": "from mta0201-27.emails.waves-audio.com (mta0201-27.emails.waves-audio.com. [135.84.217.27])        by mx.google.com with ESMTPS id t22si9652818otl.163.2021.06.13.07.19.06        for \u003c{EMAIL ADDRESS}\u003e        (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);        Sun, 13 Jun 2021 07:19:06 -0700 (PDT)"
      },
      {
        "name": "Received-SPF",
        "value": "pass (google.com: domain of 346064636000c23595702-b21164-83d6be2bdc4542f7a574924245020c5e@emails.waves-audio.com designates 135.84.217.27 as permitted sender) client-ip=135.84.217.27;"
      },
      {
        "name": "Authentication-Results",
        "value": "mx.google.com;       dkim=pass header.i=@emails.waves-audio.com header.s=gears header.b=AAcEguTx;       dkim=pass header.i=@d.messagegears.io header.s=gears header.b=jvFNHriZ;       spf=pass (google.com: domain of 346064636000c23595702-b21164-83d6be2bdc4542f7a574924245020c5e@emails.waves-audio.com designates 135.84.217.27 as permitted sender) smtp.mailfrom=346064636000c23595702-b21164-83d6be2bdc4542f7a574924245020c5e@emails.waves-audio.com"
      },
      {
        "name": "DKIM-Signature",
        "value": "v=1; a=rsa-sha256; c=relaxed/relaxed; s=gears; d=emails.waves-audio.com; h=Date:From:Reply-To:To:Message-ID:Subject:MIME-Version:Content-Type: List-Unsubscribe:List-Unsubscribe-Post; i=news@emails.waves-audio.com; bh=3CtcdJdIFbH5c/+55q2hcIqL8foXcatroOK85FVqTxk=; b=AAcEguTxQVhKb8tKVqR1lfLjeU7RxkHAe91vfNVg5UdOTOvGfi+oPi4wnn3dR/XUuFYxu47u9Cfo   g+jeKSONECg68D/xEtQCnf0MfO71lKSLXDghlYhhaAh5Jjd2IH88b+2hM5fBFN7Fz7lDUp1+Bw/0   U9IH4Ei+w7E8RXs/D6E="
      },
      {
        "name": "DKIM-Signature",
        "value": "v=1; a=rsa-sha256; c=relaxed/relaxed; s=gears; d=d.messagegears.io; h=Date:From:Reply-To:To:Message-ID:Subject:MIME-Version:Content-Type: List-Unsubscribe:List-Unsubscribe-Post; bh=3CtcdJdIFbH5c/+55q2hcIqL8foXcatroOK85FVqTxk=; b=jvFNHriZksLExFsp7Br0sf598nLFywhbNS7N+70VY0zeKKLxvm0G4EKNUJ3Fe+3a5oWYWa7HBcJS   vq8hAERdI6vQjNNZHYJifHodm4+B04CXCDev9Il3Sx3qB+CYDYymKyeiEycsHWejCdJilo8HN+GE   Cxv+AtCFwq2s68gY/r0="
      },
      {
        "name": "Date",
        "value": "Sun, 13 Jun 2021 10:04:23 -0400 (EDT)"
      },
      {
        "name": "From",
        "value": "Waves Audio \u003cnews@emails.waves-audio.com\u003e"
      },
      {
        "name": "Reply-To",
        "value": "Waves Audio \u003cnews@emails.waves-audio.com\u003e"
      },
      {
        "name": "To",
        "value": "{EMAIL ADDRESS}"
      },
      {
        "name": "Message-ID",
        "value": "\u003c618286522.102678350.1623593063602.JavaMail.cloud@mta0201.messagegears.net\u003e"
      },
      {
        "name": "Subject",
        "value": "ENDS TODAY ⏰ ALL Compressors $29.99"
      },
      {
        "name": "MIME-Version",
        "value": "1.0"
      },
      {
        "name": "Content-Type",
        "value": "multipart/mixed; boundary=\"----=_Part_102678347_1640882403.1623593063602\""
      },
      {
        "name": "X-Original-To",
        "value": "{EMAIL ADDRESS}"
      },
      {
        "name": "List-Unsubscribe",
        "value": "\u003chttp://track.waves-audio.com/list-unsub/uc/2/1cla%3ANDYwNjQ2MzY%3AMDItYjIxMTY0LTgzZDZiZTJiZGM0NTQyZjdhNTc0OTI0MjQ1MDIwYzVl%3AYXJzZXJlZ0BnbWFpbC5jb20%3AMTY1NjkwNQ%3An%3An%3A_8LcuFe86CJ4F5wm08TiWA\u003e, \u003cmailto:unsub-346064636000c23595702-b21164-83d6be2bdc4542f7a574924245020c5e@emails.waves-audio.com\u003e"
      },
      {
        "name": "List-Unsubscribe-Post",
        "value": "List-Unsubscribe=One-Click"
      }
    ]
  },
  "sizeEstimate": 51137,
  "historyId": "6952408",
  "internalDate": "1623593063000"
}

这并没有显示任何像 First opens 这样的字段，也没有任何类似的内容。

我正在考虑的另一种方法是检查邮件标签的历史记录，如果我能够检索添加 UNREAD labelId 的日期，我将能够确定查看电子邮件的时间。

Answer 1

问题：

在 Gmail API 中，没有直接方法可以检索特定邮件的阅读日期。

在 Gmail 本身中，有 requesting a read receipt 选项，但这不会自动应用于所有电子邮件，也不适用于 API（考虑为此提交 feature request in Issue Tracker）。

使用users.history，您可以跟踪标签更改（例如UNREAD），但相关的History 资源不包含这些标签更改发生日期的信息，因此它对您的情况也无用（除此之外，历史记录会在很短的时间后过期，通常是一周或更长时间 - 请参阅 Limitations)。

解决方法：

考虑到所有这些，我认为目前最好的方法是开发一个Workspace Gmail add-on。有了这个，您可以添加一个contextual trigger，它会在每次打开消息时触发一个函数（只要正在使用该插件）。

然后可以使用触发的函数来存储当前日期以及messageId（例如，使用PropertiesService。这样，您可以跟踪每条消息的打开日期。在这种情况下， messageId（或threadId，就此而言），可以在您的函数中检索到Gmail event object。

更具体地说，您的上下文函数可能是以下几行：

function onGmailContextual(e) {
  const messageId = e.gmail.messageId;
  const userProps = PropertiesService.getUserProperties();
  let dateRead;
  const messageProp = userProps.getProperty(messageId);
  if (messageProp) { // If it exists, the message was read before
    dateRead = new Date(JSON.parse(messageProp)); // Retrieve previously store read date
  } else { // If it doesn't exist, the message was not read before (at least while the add-on was open)
    dateRead = new Date(); // Get current date
    userProps.setProperty(messageId, JSON.stringify(dateRead.getTime())); // Store current date as reading date for this message
  }
  // ...
}

请注意，这仅适用于打开插件时打开的消息，因此您不能使用它来检索旧消息的阅读日期。

延伸阅读：

• Extending Gmail with Google Workspace add-ons
• Build contextual message interfaces
• Install an unpublished add-on