संपर्क
`contacts.list`, `get`, `create`, `save`, `update`, `set_audiences`, `delete`, `delete_many`, `list_people`, `set_photo`, `remove_photo`, `block`, `unblock`, `list_threads` और `activity`।
हर मेथड
from openemail import openemail page = openemail.contacts.list(limit=100)contact = openemail.contacts.get('[email protected]') saved = openemail.contacts.create({ 'email': '[email protected]', 'name': 'Grace Hopper', 'notes': 'Met at the compiler workshop',}) openemail.contacts.update(saved['email'], {'notes': None})openemail.contacts.set_audiences(saved['email'], { 'audienceIds': ['aud_4c1b8e2a7d9f05c36b4e8a71'],})openemail.contacts.delete(saved['email']) print(len(page['items']), page['hasMore'], contact['source'], contact['lastSeenAt'])सबसे हाल में देखे गए पहले, और जिन contacts को कभी मेल नहीं भेजा गया वे सबसे अंत में। source तब auto होता है जब पंक्ति इसलिए लिखी गई कि किसी सदस्य ने ऐप composer से उस पते पर संदेश भेजा, जो किसी के उसे सहेजने से भौतिक रूप से अलग दावा है। किसी पते से मेल आने पर कुछ नहीं लिखा जाता, और इस API से भेजने पर भी नहीं।
पता-पुस्तिका किसी एक व्यक्ति की नहीं, workspace की होती है, इसलिए किसी भी सदस्य द्वारा सहेजा गया contact हर सदस्य और हर कुंजी को दिखता है। create source को manual लिखता है और contact को लिखते समय ही डिफ़ॉल्ट audience में डाल देता है। अपनी सूचियों के नाम audienceIds में दें ताकि वे उसी कॉल में जुड़ जाएँ (इसके लिए audiences:write भी चाहिए), या contact को बाद में openemail.audiences.add_contact से जोड़ें। set_audiences एक ही कॉल में ठीक-ठीक बताता है कि contact किन सूचियों में है।
पते छोटे अक्षरों में संग्रहित होते हैं और आपके दिए पते को क्लाइंट encode करता है, इसलिए [email protected] सही पंक्ति तक पहुँचता है। पता ही पहचान है, इसलिए update उसे बदल नहीं सकता: contact को हटाना है तो delete और create करना होगा।
पैरामीटर: contacts.list
limitint- प्रति पेज कितने contacts लौटाने हैं: 1 से 200 के बीच एक integer, डिफ़ॉल्ट 50। इसे coerce किया जाता है, इसलिए query string से आया `'100'` चलेगा, और सीमा के बाहर का मान clamp होने के बजाय 422 देता है।
cursorstr- पिछले पेज का `nextCursor`। इसे कभी ख़ुद न बनाएँ: ऐसे contact का नाम लेने वाला cursor जो अब मौजूद नहीं है, 400 `invalid_cursor` देता है, जिसका मतलब है कि आपकी paging स्थिति बासी है और walk को बिना cursor के फिर से शुरू करना चाहिए।
sourceContactSource- `'manual'` उन contacts के लिए जिन्हें किसी ने जानबूझकर सहेजा, `'auto'` उनके लिए जिन्हें ऐप composer ने दर्ज किया। पूरी पुस्तिका के लिए इसे छोड़ दें।
qstr- नाम और पते में खोजता है, 200 अक्षरों तक। अगर पहले पेज पर कुछ भी ठीक-ठीक मेल न खाए, तो उसकी जगह मिलती-जुलती वर्तनियाँ लौटती हैं, और आगे के पेज उसी तरह मिलान करते रहते हैं।
प्रतिक्रिया: ContactResource
contacts.list एक Page[ContactResource] लौटाता है, इसलिए पंक्तियाँ page['items'] पर होती हैं और आगे बढ़ना page['nextCursor'] का अनुसरण करता है जब तक page['hasMore'] True है, जो list_all और iterate आपके लिए करते हैं। get, create, save, update, set_audiences, set_photo और remove_photo में से हर एक एक ContactDetailResource लौटाता है, यानी वही पंक्ति और साथ में audiences। पता-पुस्तिका की कोई सीमा नहीं है, इसीलिए यह route पेजों में बाँटकर लौटाता है, न कि ऐसी सूची जो चुपचाप 200 पर रुक जाए।
objectLiteral['contact']- हमेशा स्ट्रिंग `contact`, list की पंक्तियों पर भी और `get` पर भी।
emailstr- पता, लिखते समय छोटे अक्षरों में बदला हुआ, ताकि `[email protected]` और `[email protected]` एक ही contact हों; और यही वह कुंजी है जो हर contacts method लेता है, क्योंकि कोई contact id उजागर नहीं की जाती। पंक्तियाँ उस सदस्य या कुंजी की नहीं होतीं जिसने उन्हें लिखा, बल्कि workspace की होती हैं, इसलिए workspace के हर सदस्य और हर कुंजी के लिए एक ही पता-पुस्तिका है।
namestr | None- जब उस पते के लिए कभी कोई नाम दर्ज ही नहीं हुआ तो `None`। स्वचालित रूप से लिखी गई पंक्ति में नाम तभी आता है जब header ने पते के अलावा कुछ दिया हो, और वह उपयोगकर्ता के टाइप किए नाम को कभी नहीं मिटा सकता।
sourceContactSource | str- `auto` का अर्थ है कि पंक्ति इसलिए लिखी गई कि उपयोगकर्ता ने उस पते पर मेल भेजा; `manual` का अर्थ है कि किसी ने उसे हाथ से दर्ज किया (भौतिक रूप से अलग दावा), और कोई upsert `manual` को वापस `auto` पर नहीं गिराता। किसी पते से मेल आने पर जानबूझकर कोई पंक्ति नहीं लिखी जाती, इसलिए जिसने सिर्फ़ आपको लिखा है वह यहाँ नहीं होगा; union खुला रहता है क्योंकि column मुक्त पाठ है जिसका डिफ़ॉल्ट `manual` है।
notesstr | None- इस व्यक्ति के बारे में किसी ने ऐप में या `update` के ज़रिए जो लिखा, वह मुक्त पाठ; कभी उत्पन्न नहीं किया जाता। जब किसी ने कुछ नहीं लिखा तो `None`, और `update` पर स्पष्ट `None` इसे साफ़ कर देता है।
lastSeenAtstr | None- ISO-8601 UTC, हर बार तब बढ़ाया जाता है जब कोई सदस्य ऐप composer से उस पते पर भेजता है, उससे मेल आने पर नहीं, जिससे कुछ भी नहीं लिखा जाता। `create` से सहेजे गए ऐसे संपर्क पर `None` जिसे कभी मेल नहीं भेजा गया, और यह route जो अवरोही `lastSeenAt` क्रम लौटाता है उसमें वे सबसे अंत में आते हैं।
audienceslist[ContactAudienceResource]- केवल `get`, `create`, `save`, `update`, `set_audiences`, `set_photo` और `remove_photo` पर, list की पंक्तियों पर कभी नहीं। हर वह ऑडियंस जिसमें संपर्क है, `id`, `name` और `builtin` वाले dict के रूप में, डिफ़ॉल्ट ऑडियंस भी शामिल। जिस ऑडियंस में हर संपर्क होता है उस पर `builtin` `default` होता है और किसी की बनाई ऑडियंस पर `None`, इसलिए शाखा नाम पर नहीं बल्कि इस पर बनाएँ, क्योंकि नाम कोई भी बदल सकता है।
photoUrlstr | None- संपर्क की फ़ोटो कहाँ से दी जाती है, या `None` जब संपर्क की कोई फ़ोटो नहीं है। `set_photo` इसे लगाता है और हर अपलोड को नया URL मिलता है।
contact की audiences तय करना
set_audiences(email, {'audienceIds': [...]}) एक ही अनुरोध में ठीक-ठीक बताता है कि एक संपर्क किन ऑडियंस में है। संपर्क बताई गई हर उस ऑडियंस में जुड़ता है जिसमें वह अभी नहीं है और बाक़ी सबसे निकल जाता है, और कॉल बदलाव के बाद का ContactDetailResource लौटाती है। इसे audiences:write चाहिए, क्योंकि यह संपर्क नहीं बल्कि सदस्यताएँ लिखता है, और इसे दोहराने से कुछ नहीं बदलता।
डिफ़ॉल्ट audience हमेशा बनी रहती है, इसलिए {'audienceIds': []} contact को सिर्फ़ डिफ़ॉल्ट audience में छोड़ता है। यह 100 तक ID लेता है। जो ID इस वर्कस्पेस की किसी audience की ओर इशारा नहीं करती वह 404 audience_not_found देती है और कुछ नहीं बदलता, और जो पता contact नहीं है वह 404 contact_not_found देता है।
संपर्क पेज के सभी लोग
list_people उन लोगों को सूचीबद्ध करता है जिन्हें ऐप का संपर्क पेज दिखाता है: सहेजे गए संपर्क और मेल में दिखा हर पता, हर एक saved, threads और lastAt के साथ। list केवल सहेजे गए संपर्क हैं। मेल में दिखे पते तभी आते हैं जब कुंजी के पास threads:read भी हो, और page['seen'] बताता है कि वे आए या नहीं। sort recent, name या threads है, q नाम, पते और नोट्स में खोजता है, और blocked=True केवल उन लोगों को रखता है जिन्हें वर्कस्पेस की ब्लॉक सूची ब्लॉक करती है, पूरे डोमेन के नियमों सहित। blockedBy हर पंक्ति पर नियम बताता है।
from openemail import openemail page = openemail.contacts.list_people(sort='threads', limit=50) for person in page['items']: if not person['saved'] and (person['threads'] or 0) > 5: openemail.contacts.save(person['email']) blocked = openemail.contacts.list_all_people(blocked=True)list_all_people और iterate_people हर पेज पढ़ते हैं। कर्सर अपारदर्शी है, इसलिए nextCursor को जैसा आया वैसा ही, उन्हीं sort, q और blocked के साथ वापस भेजें।
सहेजना, हटाना और फ़ोटो
save(email, {'name': ..., 'notes': ...}) संपर्कों में जोड़ें और संपर्कों में रखें है: जो पता अभी संपर्क नहीं है उसे सहेजता है, किसी सेंड से दर्ज पते को हाथ से सहेजा गया मानकर रखता है, और हटाए गए पते को वापस लाता है। delete मिटाएँ है: यह सहेजे गए संपर्क को हटाता है और पता छिपाता है, ताकि कंपोज़र उसे फिर से दर्ज न करे, और यह केवल मेल में दिखा पता भी लेता है। wasSaved बताता है कि कौन-सा था। delete_many एक ही कॉल में अधिकतम 200 हटाता है।
from pathlib import Path from openemail import openemail openemail.contacts.save('[email protected]', {'name': 'Grace Hopper'}) photo = Path('grace.jpg').read_bytes()contact = openemail.contacts.set_photo('[email protected]', photo, content_type='image/jpeg') openemail.contacts.remove_photo('[email protected]')openemail.contacts.delete_many(['[email protected]', '[email protected]'])set_photo इमेज के बाइट जैसे हैं वैसे भेजता है: PNG, JPEG, WebP या GIF, अधिकतम 5 MB, 512 पिक्सेल के वर्ग में फ़िट। content_type= दें, क्योंकि bytes का अपना कोई प्रकार नहीं होता: इसके बिना अपलोड application/octet-stream के रूप में जाता है, जो 422 invalid_image के साथ अस्वीकार हो जाता है। पता पहले सहेजा गया संपर्क होना चाहिए।
ब्लॉक करना
block(email) पते को वर्कस्पेस की ब्लॉक सूची में डालता है ताकि उससे आने वाला मेल अस्वीकार हो, कोई भी प्लस टैग हटाकर, और unblock(email) उसे ब्लॉक करने वाला हर नियम हटाता है। दोनों को settings:write चाहिए, क्योंकि वे संपर्क नहीं बल्कि ब्लॉक सूची बदलते हैं, और किसी के लिए पते का संपर्क होना ज़रूरी नहीं।
जब unblock पूरे डोमेन का नियम हटाता है, तो removed उसे list को blockedDomains पर रखकर सूचीबद्ध करता है, और उस डोमेन पर हर कोई उसके साथ अनब्लॉक हो जाता है।
बातचीत और गतिविधि
list_threads(email) उन थ्रेड को पेज-दर-पेज पढ़ता है जो पते ने लिखे या जिनमें उसे लिखा गया, हर फ़ोल्डर में, और list_all_threads और iterate_threads उन्हें पूरा पढ़ते हैं। activity(email) किसी संपर्क के गतिविधि टैब के पीछे के आँकड़े लौटाता है: हर अंतराल में मिले और भेजे गए, आपके जवाब का इंतज़ार कर रहे थ्रेड, और दोनों दिशाओं में जवाब का माध्यिका समय। दोनों को threads:read चाहिए।
import time from openemail import openemail threads = openemail.contacts.list_threads('[email protected]', q='invoice') activity = openemail.contacts.activity( '[email protected]', minutes=30 * 24 * 60, grain='day', offset_minutes=time.localtime().tm_gmtoff // 60,) print(len(threads['items']), activity['totals']['waiting'])संदर्भ
contacts.list()पूरा रेफ़रेंसcontacts.list_all()पूरा रेफ़रेंसcontacts.iterate()पूरा रेफ़रेंसcontacts.get()पूरा रेफ़रेंसcontacts.create()पूरा रेफ़रेंसcontacts.save()पूरा रेफ़रेंसcontacts.update()पूरा रेफ़रेंसcontacts.set_audiences()पूरा रेफ़रेंसcontacts.delete()पूरा रेफ़रेंसcontacts.delete_many()पूरा रेफ़रेंसcontacts.list_people()पूरा रेफ़रेंसcontacts.list_all_people()पूरा रेफ़रेंसcontacts.iterate_people()पूरा रेफ़रेंसcontacts.set_photo()पूरा रेफ़रेंसcontacts.remove_photo()पूरा रेफ़रेंसcontacts.block()पूरा रेफ़रेंसcontacts.unblock()पूरा रेफ़रेंसcontacts.list_threads()पूरा रेफ़रेंसcontacts.list_all_threads()पूरा रेफ़रेंसcontacts.iterate_threads()पूरा रेफ़रेंसcontacts.activity()पूरा रेफ़रेंस