संपर्क
`contacts->list`, `get`, `create`, `save`, `update`, `setAudiences`, `delete`, `deleteMany`, `listPeople`, `setPhoto`, `removePhoto`, `block`, `unblock`, `listThreads` और `activity`।
हर मेथड
$page = $client->contacts->list(limit: 100);$contact = $client->contacts->get('[email protected]'); $saved = $client->contacts->create([ 'email' => '[email protected]', 'name' => 'Grace Hopper', 'notes' => 'Met at the compiler workshop',]); $client->contacts->update('[email protected]', ['notes' => null]);$client->contacts->setAudiences('[email protected]', ['audienceIds' => ['aud_4c1b8e2a7d9f05c36b4e8a71']]);$client->contacts->delete('[email protected]'); echo count($page), ' ', $page->hasMore ? 'more to come' : 'that is all', PHP_EOL;echo $contact['source'], ' ', $contact['lastSeenAt'] ?? 'never mailed', ' ', $saved['source'], PHP_EOL;list सबसे हाल में दिखे संपर्क पहले लौटाता है, और जिन संपर्कों को कभी मेल नहीं भेजा गया उन्हें आख़िर में। source तब auto होता है जब पंक्ति इसलिए लिखी गई कि किसी सदस्य ने ऐप के composer से उस पते पर संदेश भेजा, जो किसी के उसे सहेजने से बिल्कुल अलग दावा है। किसी पते से आने वाला मेल कुछ नहीं लिखता, और इस API से किया गया send भी नहीं।
पता-पुस्तिका किसी एक व्यक्ति की नहीं, वर्कस्पेस की होती है, इसलिए किसी भी सदस्य द्वारा सहेजा गया संपर्क हर सदस्य और हर कुंजी को दिखता है। create source को manual लिखता है और संपर्क को लिखते समय ही डिफ़ॉल्ट ऑडियंस में डाल देता है। उसी कॉल में अपनी सूचियों से जोड़ने के लिए उनके नाम audienceIds में दें, जिसके लिए audiences:write भी चाहिए, या संपर्क को बाद में audiences->addContact से जोड़ें, जिसे “ऑडियंस” पेज कवर करता है। setAudiences एक कॉल में ठीक-ठीक बताता है कि संपर्क किन सूचियों में है।
पते lowercase में सहेजे जाते हैं और क्लाइंट आपके पास किए गए पते को encode करता है, इसलिए [email protected] सही पंक्ति तक पहुँचता है। ख़ाली पता कुछ भी भेजे जाने से पहले InvalidArgumentException throw करता है। पता ही पहचान है, इसलिए update उसे नहीं बदल सकता: किसी संपर्क को बदलना एक delete और एक create है।
पैरामीटर: contacts->list
limitint- हर पेज पर कितने संपर्क लौटाने हैं: 1 से 200 तक की पूर्ण संख्या, डिफ़ॉल्ट 50। सीमा से बाहर का मान छोटा करने के बजाय 422 होता है। आर्ग्युमेंट का टाइप `int` है, इसलिए query string से पढ़े गए मान को पहले `(int)` से cast करें।
cursorstring- पिछले पेज का `nextCursor`। इसे कभी ख़ुद न बनाएँ: ऐसा cursor जो किसी ऐसे संपर्क का नाम ले जो अब मौजूद नहीं है, 400 `invalid_cursor` है, जो `InvalidRequestException` के रूप में throw होता है, और इसका मतलब है कि आपकी paging स्थिति पुरानी हो गई है और चलना बिना cursor के फिर से शुरू होना चाहिए।
sourcestring- जानबूझकर सहेजे गए संपर्कों के लिए `manual`, ऐप के composer द्वारा दर्ज संपर्कों के लिए `auto`। पूरी पुस्तिका के लिए इसे छोड़ दें।
qstring- नाम और पते में खोजता है, 200 अक्षरों तक। अगर पहले पेज पर कुछ भी ठीक-ठीक मेल न खाए, तो उसकी जगह मिलती-जुलती वर्तनियाँ लौटती हैं, और आगे के पेज उसी तरह मिलान करते रहते हैं।
जवाब: एक संपर्क
contacts->list एक OpenEmail\Result\Page लौटाता है, इसलिए पंक्तियाँ $page->items पर होती हैं और जब तक $page->hasMore true है, चलना $page->nextCursor का पीछा करता है। listAll हर पंक्ति को एक array के रूप में लौटाता है, और iterate एक Generator लौटाता है जो उन्हें एक-एक करके yield करता है। get, create, update, save और setAudiences में से हर एक, एक संपर्क को camelCase कुंजियों वाले array के रूप में लौटाता है, वही पंक्ति और साथ में audiences। पता-पुस्तिका की कोई सीमा नहीं है, इसीलिए यह route 200 पर चुपचाप रुक जाने वाला array लौटाने के बजाय पेज करता है।
objectstring- हमेशा स्ट्रिंग `contact`, list की पंक्तियों पर भी और `get` पर भी।
emailstring- पता, लिखते समय छोटे अक्षरों में बदला हुआ, ताकि `[email protected]` और `[email protected]` एक ही contact हों; और यही वह कुंजी है जो हर contacts method लेता है, क्योंकि कोई contact id उजागर नहीं की जाती। पंक्तियाँ उस सदस्य या कुंजी की नहीं होतीं जिसने उन्हें लिखा, बल्कि workspace की होती हैं, इसलिए workspace के हर सदस्य और हर कुंजी के लिए एक ही पता-पुस्तिका है।
namestring or null- display name, या null जब उस पते के लिए कभी कोई नाम दर्ज न हुआ हो। अपने आप होने वाला write नाम तभी रखता है जब हेडर ने पते के अलावा कुछ दिया हो, और वह उपयोगकर्ता द्वारा टाइप किए गए नाम को कभी नहीं बदल सकता।
sourcestring- `auto` का मतलब है कि पंक्ति इसलिए लिखी गई क्योंकि उपयोगकर्ता ने उस पते पर मेल भेजी। `manual` का मतलब है कि किसी ने इसे हाथ से दर्ज किया, जो एक बिल्कुल अलग दावा है, और upsert कभी `manual` को वापस `auto` नहीं बनाता। किसी पते से आने वाली मेल जानबूझकर कोई पंक्ति नहीं लिखती, इसलिए जिसने आपको सिर्फ़ लिखा ही है वह यहाँ नहीं है। मान को खुली स्ट्रिंग मानें, क्योंकि यह column मुक्त text है जिसका डिफ़ॉल्ट `manual` है।
notesstring or null- इस व्यक्ति के बारे में किसी द्वारा लिखा गया मुक्त text, ऐप में या `update` के ज़रिए, कभी अपने आप बनाया नहीं जाता। जब किसी ने कुछ नहीं लिखा हो तो यह null है, और `update` पर `'notes' => null` इसे हटा देता है।
lastSeenAtstring or null- एक ISO 8601 UTC स्ट्रिंग, जो हर बार आगे बढ़ती है जब कोई सदस्य ऐप के composer से उस पते पर भेजता है, न कि जब उस पते से मेल आती है, जो कुछ नहीं लिखती। `create` से सहेजे गए उस संपर्क पर यह null है जिसे कभी मेल नहीं भेजी गई, और ऐसे संपर्क इस route द्वारा लौटाए जाने वाले घटते `lastSeenAt` क्रम में सबसे आख़िर में आते हैं।
audiencesarray- सिर्फ़ `get`, `create`, `update`, `save` और `setAudiences` पर, सूची की पंक्तियों पर कभी नहीं। हर ऑडियंस जिसमें संपर्क है, डिफ़ॉल्ट वाली समेत, `id`, `name` और `builtin` वाले array के रूप में। जिस ऑडियंस में हर संपर्क होता है उस पर `builtin` का मान `default` होता है और किसी द्वारा बनाई गई ऑडियंस पर null, इसलिए नाम के बजाय इस पर branch करें, जिसे कोई भी बदल सकता है।
photoUrlstring or null- संपर्क की फ़ोटो कहाँ से दी जाती है, या null जब संपर्क की कोई फ़ोटो नहीं है। `setPhoto` इसे लगाता है और हर अपलोड को नया URL मिलता है।
किसी संपर्क की ऑडियंस सेट करना
setAudiences($email, ['audienceIds' => [...]]) एक रिक्वेस्ट में ठीक-ठीक बताता है कि एक संपर्क किन ऑडियंस में है। संपर्क सूची में दी गई हर उस ऑडियंस में जुड़ता है जिसमें वह अभी नहीं है और बाकी सभी से हट जाता है, और कॉल बदलाव के बाद का संपर्क उसके audiences के साथ लौटाती है। इसे audiences:write चाहिए, क्योंकि यह संपर्क के बजाय सदस्यताएँ लिखता है, और इसे दोहराने से कुछ नहीं बदलता, इसलिए क्लाइंट नेटवर्क विफलता के बाद इसे retry करता है।
डिफ़ॉल्ट ऑडियंस हमेशा बनी रहती है, इसलिए 'audienceIds' => [] संपर्क को सिर्फ़ डिफ़ॉल्ट ऑडियंस में छोड़ता है। यह अधिकतम 100 id लेता है। ऐसी id जो इस वर्कस्पेस की किसी ऑडियंस का नाम न ले, 404 audience_not_found है और कुछ नहीं बदलता, और जो पता संपर्क नहीं है वह 404 contact_not_found है। दोनों NotFoundException throw करते हैं।
संपर्क पेज के सभी लोग
listPeople उन लोगों को सूचीबद्ध करता है जिन्हें ऐप का “संपर्क” पेज दिखाता है: सहेजे गए संपर्क और मेल में दिखा हर पता, हर एक saved, threads और lastAt के साथ। list सिर्फ़ सहेजे गए संपर्क हैं। यह एक OpenEmail\Result\PeoplePage लौटाता है, जो items, hasMore और nextCursor में seen जोड़ता है। मेल में दिखे पते तभी आते हैं जब कुंजी के पास threads:read भी हो, और $page->seen बताता है कि आए या नहीं। sort: recent, name या threads है, और OpenEmail\Constants\PeopleSorts उनके नाम बताता है। q: नाम, पते और नोट्स में खोजता है, और blocked: true उन लोगों को रखता है जिन्हें वर्कस्पेस की blocklist रोकती है, पूरे डोमेन वाले नियमों समेत। blockedBy हर पंक्ति पर नियम का नाम बताता है।
use OpenEmail\Constants\PeopleSorts; $page = $client->contacts->listPeople(sort: PeopleSorts::THREADS, limit: 50); foreach ($page as $person) { if (!$person['saved'] && $person['threads'] > 5) { $client->contacts->save($person['email']); }} $blocked = $client->contacts->listAllPeople(blocked: true);echo $page->seen ? 'saved and seen' : 'saved only', ', ', count($blocked), ' blocked', PHP_EOL;listAllPeople हर पेज को एक array के रूप में लौटाता है, और iteratePeople एक Generator लौटाता है जो हर व्यक्ति को yield करता है। कोई भी seen नहीं बताता, इसलिए उसे जानने के लिए listPeople से एक पेज पढ़ें। cursor अपारदर्शी है, इसलिए nextCursor को ठीक वैसे ही cursor: के रूप में वापस भेजें जैसा वह आया, उन्हीं sort:, q: और blocked: के साथ।
सहेजना, हटाना और फ़ोटो
name और notes के वैकल्पिक array के साथ save($email) “संपर्कों में जोड़ें” और “संपर्कों में रखें” है: यह ऐसा पता सहेजता है जो अभी संपर्क नहीं है, send से दर्ज हुए संपर्क को हाथ से सहेजे गए संपर्क के रूप में रखता है, और हटाए गए संपर्क को वापस लाता है। delete “हटाएँ” है: यह सहेजे गए संपर्क को हटाता है और पते को छिपा देता है, ताकि composer उसे फिर से दर्ज न करे, और यह ऐसा पता भी लेता है जो सिर्फ़ मेल में देखा गया हो। यह जो array लौटाता है उसमें wasSaved बताता है कि मामला कौन-सा था। deleteMany एक कॉल में अधिकतम 200 हटाता है।
$client->contacts->save('[email protected]', ['name' => 'Grace Hopper']); $contact = $client->contacts->setPhoto('[email protected]', file_get_contents('photo.jpg'), contentType: 'image/jpeg');echo $contact['photoUrl'], PHP_EOL; $client->contacts->setPhoto('[email protected]', new \SplFileInfo('avatar.png')); $client->contacts->removePhoto('[email protected]');$client->contacts->deleteMany(['[email protected]', '[email protected]']);setPhoto image के बाइट्स वैसे ही भेजता है जैसे वे हैं: 5 MB तक का PNG, JPEG, WebP या GIF, जो 512 पिक्सेल के वर्ग में फ़िट किया जाता है। बाइट्स एक स्ट्रिंग, fopen का stream resource, SplFileInfo, या PSR-7 stream या अपलोड की गई फ़ाइल होते हैं। contentType: पास करें, या ऐसे बाइट्स जिनका अपना टाइप हो: अपने media type के साथ PSR-7 की अपलोड की गई फ़ाइल या Symfony या Laravel का upload, या ऐसी फ़ाइल या stream जिसका नाम .png, .jpg, .jpeg, .webp या .gif पर ख़त्म हो। टाइप के बिना बाइट्स application/octet-stream के रूप में जाते हैं, जिसे सर्वर 422 invalid_image के साथ अस्वीकार करता है। OpenEmail\Constants\ContactPhotoTypes चारों टाइप के नाम देता है। पता पहले से एक सहेजा गया संपर्क होना चाहिए।
ब्लॉक करना
block($email) पते को वर्कस्पेस की ब्लॉक सूची में डालता है ताकि उससे आने वाला मेल अस्वीकार हो, कोई भी प्लस टैग हटाकर, और unblock($email) उसे ब्लॉक करने वाला हर नियम हटाता है। दोनों को settings:write चाहिए, क्योंकि वे संपर्क नहीं बल्कि ब्लॉक सूची बदलते हैं, और किसी के लिए पते का संपर्क होना ज़रूरी नहीं।
जब unblock पूरे डोमेन वाला नियम हटाता है, तो removed उसे list का मान blockedDomains रखकर सूचीबद्ध करता है, और उस डोमेन के सभी लोग उसके साथ unblock हो जाते हैं। OpenEmail\Constants\ContactBlockLists दोनों सूचियों के नाम बताता है।
बातचीत और गतिविधि
listThreads($email) उन थ्रेड को पेज करता है जिनमें उस पते ने लिखा या जिनमें उसे लिखा गया, हर फ़ोल्डर में, और listAllThreads तथा iterateThreads उन पर चलते हैं। activity($email) किसी संपर्क के “गतिविधि” टैब के पीछे के आँकड़े लौटाता है: हर बकेट में प्राप्त और भेजे गए, आपके जवाब का इंतज़ार कर रहे थ्रेड, और दोनों दिशाओं में जवाब के समय की माध्यिका। दोनों को threads:read चाहिए।
$threads = $client->contacts->listThreads('[email protected]', q: 'invoice'); $activity = $client->contacts->activity( '[email protected]', minutes: 30 * 24 * 60, grain: 'day', offsetMinutes: intdiv((int) date('Z'), 60),); echo count($threads), ' threads, ', $activity['totals']['waiting'], ' waiting on you', PHP_EOL;activity named आर्ग्युमेंट लेता है। minutes: अवधि तय करता है, जो छोड़ने पर 90 दिन होती है। grain: bucket की चौड़ाई तय करता है: minute, hour या day। offsetMinutes: तय करता है कि दिन UTC से कितने मिनट पूर्व में बँटते हैं, और intdiv((int) date('Z'), 60) उस zone का offset है जिस पर PHP सेट है।