दस्तावेज़

Mailera API

REST से Microsoft मेलबॉक्स (Outlook, Hotmail, Microsoft 365) का पूरा प्रबंधन करें: मेलबॉक्स जोड़ें, जाँचें कि वे सक्रिय हैं, ईमेल पढ़ें, OTP कोड पाएँ, ईमेल भेजें, जंक ईमेल से बाहर ले जाएँ और webhook प्राप्त करें।

परिचय

हर एंडपॉइंट एक ही बेस URL के अंतर्गत है और JSON स्वीकार करता है व लौटाता है।

1खाता और अपना वर्कस्पेस बनाएँ (मुफ़्त)।
2सेटिंग्स → API key खोलें, एक API key बनाएँ और उसके स्कोप चुनें।
3हर अनुरोध में X-API-Key हेडर के ज़रिए API key भेजें।

सफल जवाबों में data फ़ील्ड होता है; त्रुटियों में error फ़ील्ड होता है, जिसमें code और message होते हैं।

मुफ़्त वर्कस्पेस बनाएँ

बेस URL

https://mailera.app/api/public/v1# 200{ "data": [ ... ], "next_cursor": "..." }# 4xx / 5xx{ "error": { "code": "not_found", "message": "..." } }

प्रमाणीकरण

अपनी API key को X-API-Key हेडर में भेजें। API key की शुरुआत mh_live_ से होती है और यह बनाते समय केवल एक बार दिखाई जाती है; खो जाने पर नई API key बनाएँ और पुरानी रद्द करें।

उसी API key वाले Bearer token के साथ Authorization हेडर भी स्वीकार किया जाता है।

API key को अनुमत IP की सूची तक सीमित किया जा सकता है; अन्य IP से अनुरोध करने पर 403 मिलता है।

cURL

curl https://mailera.app/api/public/v1/mailboxes \  -H "X-API-Key: mh_live_..."

API key के स्कोप

हर API key के एक या अधिक स्कोप होते हैं। ऐसे एंडपॉइंट को कॉल करने पर जिसका स्कोप API key के पास नहीं है, 403 forbidden मिलता है।

स्कोप	अनुमतियाँ
`read`	मेलबॉक्स, ईमेल, OTP कोड और इनबॉक्स/जंक ईमेल में स्थिति पढ़ना
`move`	ईमेल को जंक ईमेल से बाहर और फ़ोल्डरों के बीच ले जाना
`import`	मेलबॉक्स जोड़ना
`sync`	तुरंत सिंक का अनुरोध करना
`send`	ईमेल भेजना, जवाब देना और फ़ॉरवर्ड करना
`manage`	मेलबॉक्स रोकना, फिर चालू करना और मिटाना
`webhooks`	webhook का प्रबंधन करना

त्रुटियाँ

त्रुटियों में हमेशा एक स्थिर code और अंग्रेज़ी में message होता है। त्रुटियों को code के आधार पर संभालें, कभी भी message के टेक्स्ट के आधार पर नहीं।

HTTP	कोड	अर्थ
401	`unauthorized`	API key मौजूद नहीं है, अमान्य है, उसकी समय-सीमा समाप्त हो गई है या उसे रद्द कर दिया गया है
403	`forbidden`	API key के पास ज़रूरी स्कोप नहीं है या IP उसकी अनुमत सूची में नहीं है
404	`not_found`	मेलबॉक्स या संदेश मौजूद नहीं है या API key के वर्कस्पेस का नहीं है
409	`mailbox_unavailable`	मेलबॉक्स को फिर से कनेक्ट करना ज़रूरी है, वह रुका हुआ है या केवल IMAP पर है (अभी समर्थित नहीं)
422	`validation_error`	अनुरोध का डेटा गलत फ़ॉर्मैट में है
429	`rate_limited`	इस API key के लिए प्रति मिनट 300 से अधिक अनुरोध — Retry-After हेडर के अनुसार प्रतीक्षा करें
503	`upstream_error`	Microsoft में त्रुटि है या वह अनुरोधों की दर सीमित कर रहा है — बाद में फिर कोशिश करें
500	`internal_error`	सिस्टम त्रुटि

सीमाएँ और पेजिनेशन

हर API key के लिए प्रति मिनट 300 अनुरोधों की अनुमति है। सीमा पार करने पर Retry-After हेडर के साथ 429 मिलता है।

सूचियाँ next_cursor लौटाती हैं; अगला पेज पाने के लिए इसे cursor पैरामीटर में वापस भेजें। जब और डेटा नहीं होता, तो next_cursor का मान null होता है।

limit पैरामीटर हर पेज पर आइटम की संख्या तय करता है।

cURL

curl "https://mailera.app/api/public/v1/mailboxes?limit=50&cursor=NEXT_CURSOR" \  -H "X-API-Key: mh_live_..."

मेलबॉक्स

मेलबॉक्स जोड़ें, जाँचें, सिंक करें, रोकें और मिटाएँ।

GET/mailboxes
मेलबॉक्स की सूची पाएँ
स्कोप:
read
क्वेरी:
status, q, cursor, limit
POST/mailboxes/import
एक साथ कई मेलबॉक्स इम्पोर्ट करें (email:password:refresh_token:client_id, या | से अलग किए हुए)
स्कोप:
import
बॉडी:
lines, text, group_id, duplicate_mode
GET/mailboxes/import
इम्पोर्ट की प्रगति और हर पंक्ति के परिणाम
स्कोप:
import
क्वेरी:
job_id
GET/mailboxes/{id}
मेलबॉक्स का विवरण और फ़ोल्डर के काउंटर
स्कोप:
read
PATCH/mailboxes/{id}
मेलबॉक्स रोकें या फिर चालू करें
स्कोप:
manage
बॉडी:
action (ज़रूरी)
DELETE/mailboxes/{id}
मेलबॉक्स मिटाएँ
स्कोप:
manage
GET/mailboxes/{id}/status
सीधे Microsoft से जाँचें कि मेलबॉक्स अभी भी काम कर रहा है
स्कोप:
read
POST/mailboxes/{id}/sync
अभी सिंक करें
स्कोप:
sync
बॉडी:
wait

मेलबॉक्स इम्पोर्ट करें और प्रगति जाँचें

curl -X POST https://mailera.app/api/public/v1/mailboxes/import \  -H "X-API-Key: mh_live_xxx" -H "content-type: application/json" \  -d '{"lines":["user@hotmail.com:pass:M.C5_refresh...:9e5f94bc-..."]}'# → { "data": { "job_id": "..." } }curl "https://mailera.app/api/public/v1/mailboxes/import?job_id=JOB_ID" -H "X-API-Key: mh_live_xxx"

संदेश

ईमेल पढ़ें, खोजें, OTP कोड पाएँ और ईमेल भेजें।

GET/mailboxes/{id}/messages
फ़ोल्डर में संदेशों की सूची पाएँ
स्कोप:
read
क्वेरी:
folder, unread, cursor, limit
GET/mailboxes/{id}/messages/{msgId}
एक संदेश उसकी सामग्री सहित पाएँ
स्कोप:
read
GET/mailboxes/{id}/otp
नवीनतम OTP कोड पाएँ
स्कोप:
read
क्वेरी:
from, subject, since_minutes
POST/mailboxes/{id}/send
भेजें, जवाब दें या फ़ॉरवर्ड करें
स्कोप:
send
बॉडी:
to, cc, bcc, subject, html, text, importance, reply_to_message_id, mode, attachments
GET/messages/search
सभी मेलबॉक्स में ईमेल खोजें
स्कोप:
read
क्वेरी:
q, folder, limit

ईमेल भेजें

curl -X POST https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/send \  -H "X-API-Key: mh_live_xxx" -H "content-type: application/json" \  -d '{"to":["customer@example.com"],"subject":"Hello","text":"Message body"}'

जंक ईमेल

इनबॉक्स/जंक ईमेल में स्थिति जाँचें और ईमेल को जंक ईमेल से बाहर ले जाएँ।

POST/mailboxes/{id}/messages/{msgId}/move
संदेश दूसरे फ़ोल्डर में ले जाएँ (जैसे जंक ईमेल से इनबॉक्स में)
स्कोप:
move
बॉडी:
destination (ज़रूरी)
POST/mailboxes/{id}/unspam
सभी ईमेल या किसी एक प्रेषक के ईमेल जंक ईमेल से बाहर ले जाएँ
स्कोप:
move
बॉडी:
filter
GET/mailboxes/{id}/placement
ईमेल इनबॉक्स में पहुँचा या जंक ईमेल में
स्कोप:
read
क्वेरी:
from, subject, since_minutes

इनबॉक्स या जंक ईमेल? फिर जंक ईमेल से बाहर ले जाएँ

curl "https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/placement?from=me@example.com" -H "X-API-Key: mh_live_xxx"curl -X POST https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/unspam -H "X-API-Key: mh_live_xxx" \  -H "content-type: application/json" -d '{"filter":{"type":"sender","value":"me@example.com"}}'

webhook

इवेंट प्राप्त करने वाले URL रजिस्टर करें।

हर इवेंट पर Mailera आपके URL पर JSON POST भेजता है। अगर आपका एंडपॉइंट त्रुटि लौटाता है या जवाब नहीं देता, तो Mailera बढ़ते अंतराल पर फिर कोशिश करता है।

इवेंट	कब
`message.received`	इनबॉक्स में नया ईमेल आया
`message.junk`	जंक ईमेल में नया ईमेल पहुँचा
`mailbox.disconnected`	मेलबॉक्स का कनेक्शन टूट गया (token रद्द हुआ, पासवर्ड बदला…)

सत्यापन के लिए, टाइमस्टैम्प, एक बिंदु और बॉडी को जोड़कर बनी स्ट्रिंग का webhook सीक्रेट से HMAC-SHA256 निकालें, फिर उसकी तुलना हस्ताक्षर हेडर से करें।

भेजे गए हेडर: X-MailHub-Event X-MailHub-Delivery X-MailHub-Timestamp X-MailHub-Signature

GET/webhooks
webhook की सूची पाएँ
स्कोप:
webhooks
POST/webhooks
webhook बनाएँ (हस्ताक्षर का सीक्रेट केवल एक बार लौटाया जाता है)
स्कोप:
webhooks
बॉडी:
url (ज़रूरी), events, group_id
PATCH/webhooks/{id}
webhook चालू/बंद करें या उसके इवेंट या URL बदलें
स्कोप:
webhooks
DELETE/webhooks/{id}
webhook मिटाएँ
स्कोप:
webhooks

webhook हस्ताक्षर सत्यापित करें (Node.js)

import crypto from "node:crypto";// X-MailHub-Signature: sha256=<hex>   X-MailHub-Timestamp: <unix seconds>const expected = "sha256=" + crypto.createHmac("sha256", SECRET)  .update(timestamp + "." + rawBody).digest("hex");const ok = expected.length === signature.length &&  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

उदाहरण

MAILBOX_ID और API key की जगह अपने मान डालें।

मेलबॉक्स इम्पोर्ट करें और प्रगति जाँचें

curl -X POST https://mailera.app/api/public/v1/mailboxes/import \  -H "X-API-Key: mh_live_xxx" -H "content-type: application/json" \  -d '{"lines":["user@hotmail.com:pass:M.C5_refresh...:9e5f94bc-..."]}'# → { "data": { "job_id": "..." } }curl "https://mailera.app/api/public/v1/mailboxes/import?job_id=JOB_ID" -H "X-API-Key: mh_live_xxx"

जाँचें कि मेलबॉक्स सक्रिय है

curl https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/status -H "X-API-Key: mh_live_xxx"

नवीनतम OTP कोड पाएँ (पिछले 15 मिनट का)

curl "https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/otp?from=noreply@service.com&since_minutes=15" \  -H "X-API-Key: mh_live_xxx"# → { "data": { "code": "482913", "folder": "inbox", ... } }  or  { "data": { "code": null } }

ईमेल भेजें

curl -X POST https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/send \  -H "X-API-Key: mh_live_xxx" -H "content-type: application/json" \  -d '{"to":["customer@example.com"],"subject":"Hello","text":"Message body"}'

इनबॉक्स या जंक ईमेल? फिर जंक ईमेल से बाहर ले जाएँ

curl "https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/placement?from=me@example.com" -H "X-API-Key: mh_live_xxx"curl -X POST https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/unspam -H "X-API-Key: mh_live_xxx" \  -H "content-type: application/json" -d '{"filter":{"type":"sender","value":"me@example.com"}}'

JavaScript (सर्वर-साइड)

const res = await fetch("https://mailera.app/api/public/v1/mailboxes?limit=50", {  headers: { "X-API-Key": process.env.MAILERA_API_KEY },});const { data, next_cursor } = await res.json();

Python

import os, requestsr = requests.get(    "https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/messages",    params={"folder": "inbox", "limit": 20},    headers={"X-API-Key": os.environ["MAILERA_API_KEY"]},)print(r.json()["data"])

webhook हस्ताक्षर सत्यापित करें (Node.js)

import crypto from "node:crypto";// X-MailHub-Signature: sha256=<hex>   X-MailHub-Timestamp: <unix seconds>const expected = "sha256=" + crypto.createHmac("sha256", SECRET)  .update(timestamp + "." + rawBody).digest("hex");const ok = expected.length === signature.length &&  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

OpenAPI 3.1 — openapi.json AI एजेंट के लिए गाइड — llms.txt