Gmail API में users.messages.insert के साथ Date हेडर सुरक्षित रखने का सही तरीका

Gmail API से माइग्रेशन में Date हेडर बचाने का तरीका: users.messages.insert पर internalDateSource को पैरामीटर में पास करें, body में नहीं। व्यवहारिक सुझाव समेत।

Gmail में संदेश माइग्रेट करते समय, एक आम आवश्यकता होती है कि मूल Date हेडर सुरक्षित रहे, ताकि थ्रेड और आर्काइव वास्तविक क्रम दिखाएँ। यदि आप users.messages.insert पर निर्भर करते हैं और देखते हैं कि Gmail आपका Date मौजूदा टाइमस्टैम्प से बदल देता है, तो समस्या ज़्यादातर आपके MIME या Base64 में नहीं होती—मुद्दा यह होता है कि आपने internalDateSource कहाँ दिया है।

समस्या का सार

उद्देश्य है कि Gmail API के जरिए कच्चे RFC 5322 संदेश डाले जाएँ और Date हेडर यथावत रहे। अक्सर लोग internalDateSource को raw के साथ JSON body में रखने का प्रयास करते हैं। ऐसा करते ही Gmail इच्छित स्रोत को नज़रअंदाज़ कर देता है और Date हेडर के मान की जगह संदेश पर इंसर्ट करने का समय लगा देता है।

समस्या पैदा करने वाला पुनरुत्पादित होने योग्य उदाहरण

from googleapiclient.discovery import build
import base64
# Gmail API क्लाइंट प्रारंभ करें
gmail_svc = build('gmail', 'v1', credentials=creds_in)
# कस्टम Date हेडर वाला रॉ ईमेल
msg_src = """\
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
to: recipient@gmail.com
from: sender@gmail.com
subject: Test Email
Date: Tue, 13 Aug 2024 14:00:00 +0000
This is a test email.
"""
# ईमेल को एन्कोड करें
msg_b64 = base64.urlsafe_b64encode(msg_src.encode('utf-8')).decode('utf-8')
# गलत: internalDateSource को body के अंदर रखना
payload = {
    'raw': msg_b64,
    'internalDateSource': 'dateHeader',
    'deleted': True
}
api_result = gmail_svc.users().messages().insert(userId='me', body=payload).execute()
print(api_result)

Date हेडर रॉ संदेश में ठीक से सेट होने और deleted दिए जाने के बावजूद, डाला गया संदेश वर्तमान समय-चिह्न के साथ आता है। संदेश की internal date के लिए Gmail Date हेडर नहीं, बल्कि इंसर्शन समय इस्तेमाल करता है।

ऐसा क्यों होता है

internalDateSource फ़्लैग एक मेथड पैरामीटर है, संदेश की body का हिस्सा नहीं। इसे body के भीतर डालेंगे तो API चुपचाप उसे नज़रअंदाज़ कर देती है। मेथड सिग्नेचर स्पष्ट करता है कि यह पैरामीटर कहाँ होना चाहिए:

insert(userId, body=None, deleted=None, internalDateSource=None, media_body=None, media_mime_type=None, x__xgafv=None)

गलत स्थान पर internalDateSource देने से Gmail आंतरिक टाइमस्टैम्प सेट करते वक़्त Date हेडर का उपयोग नहीं कर पाता।

समाधान और सुधार किया गया उदाहरण

internalDateSource को insert कॉल के टॉप-लेवल आर्गुमेंट्स में ले जाएँ। इतना करना ही पर्याप्त है कि Gmail Date हेडर का सम्मान करे; यह deleted के बिना भी काम करता है।

from googleapiclient.discovery import build
import base64
# Gmail API क्लाइंट प्रारंभ करें
gmail_svc = build('gmail', 'v1', credentials=creds_in)
msg_src = """\
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
to: recipient@gmail.com
from: sender@gmail.com
subject: Test Email
Date: Tue, 13 Aug 2024 14:00:00 +0000
This is a test email.
"""
msg_b64 = base64.urlsafe_b64encode(msg_src.encode('utf-8')).decode('utf-8')
payload = {
    'raw': msg_b64,
    # 'labelIds': ['INBOX'],  # वैकल्पिक: INBOX में रखें
}
api_result = gmail_svc.users().messages().insert(
    userId='me',
    body=payload,
    internalDateSource='dateHeader',
    # deleted=True,
).execute()
print(api_result)

इस बदलाव के साथ, Gmail Date हेडर का मान अपनाता है। परीक्षणों में संदेश निर्दिष्ट Date के अनुसार सॉर्ट हुए, और यह मान रॉ हेडरों में तथा संदेश स्रोत दृश्य में "Created at" के रूप में दिखाई दिया। स्थानीय टाइमज़ोन सेटिंग्स आपके सामने दिखने वाले समय को प्रभावित कर सकती हैं।

यह बारीकी क्यों महत्वपूर्ण है

ईमेल माइग्रेशन या आर्काइव आयात में कालक्रम बेहद अहम है। इंसर्शन समय का उपयोग करने से थ्रेड और लेबल्स का ऐतिहासिक क्रम बिगड़ जाता है, जबकि Date हेडर का पालन करने से मूल टाइमलाइन सुरक्षित रहती है। internalDateSource को सही स्थान पर देना सुनिश्चित करता है कि API अपेक्षित ढंग से व्यवहार करे और अतिरिक्त हेडर जैसे नाज़ुक वर्कअराउंड की ज़रूरत न पड़े।

एक अतिरिक्त अवलोकन

कभी-कभी API प्रतिक्रिया में केवल id आता है, जबकि अन्य बार labelIds और threadId भी मिल सकते हैं। यह बदलाव इस बात को प्रभावित नहीं करता कि Date हेडर सुरक्षित रहता है या नहीं।

मुख्य बातें

यदि inserts के दौरान Gmail आपका Date हेडर अनदेखा करता दिखे, तो सबसे पहले पैरामीटर की प्लेसमेंट जाँचें। internalDateSource फ्लैग insert मेथड के पैरामीटर्स में होना चाहिए, न कि संदेश की body में। इसे स्थानांतरित करते ही Gmail सीधे Date हेडर पर भरोसा कर पाता है, और इस व्यवहार के लिए deleted जरूरी नहीं है।