Λήψη email στην εφαρμογή σας

Τι χρειάζεστε

• Ένα domain καταχωρισμένο στη NameOcean: η προώθηση και το mail σε webhook είναι δωρεάν για αυτά.
• Ένα HTTPS endpoint σε δημόσια διεύθυνση που απαντά εντός 20 δευτερολέπτων.
• Το CLI nameocean ή ένα κλειδί API με email:write.

1. Ενεργοποιήστε την προώθηση για το domain

$ nameocean email forwards on example.com

Αυτό κατευθύνει την εγγραφή MX του domain στους διακομιστές προώθησης email της NameOcean. Αν το domain έχει ήδη εγγραφές MX, για γραμματοκιβώτια σε άλλον πάροχο, η εντολή σταματά και τις εμφανίζει: όλα τα μηνύματα του domain θα μεταφερθούν εδώ. Προσθέστε το --replace-mx μόνο αν αυτό θέλετε.

2. Ζητήστε mail σε webhook

Η αποστολή μηνυμάτων σε URL ενεργοποιείται ανά λογαριασμό μετά από σύντομο έλεγχο, ώστε να αποκλείονται τα spam relays. Στη σελίδα του domain, στην ενότητα Πίνακας ελέγχου → Προώθηση email, υποβάλετε αίτημα με μια σύντομη περιγραφή της χρήσης. Μέχρι τότε το API απαντά 403 not_approved.

3. Στείλτε μια διεύθυνση στο endpoint σας

$ nameocean email inbound add example.com support https://app.example.com/hooks/mail

$ curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com/webhooks \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" -H "Content-Type: application/json" \
    -d '{"localpart": "support", "url": "https://app.example.com/hooks/mail"}'

Η απάντηση περιέχει το μυστικό υπογραφής (whsec_…)· φυλάξτε το στις ρυθμίσεις της εφαρμογής σας. Με localpart * αποστέλλονται όλες οι διευθύνσεις του domain που δεν έχουν δικό τους alias. Ένα domain μπορεί να έχει έως τρία τέτοια webhooks.

4. Λάβετέ το

Επαληθεύστε την υπογραφή στο ακατέργαστο σώμα και έπειτα διαβάστε το JSON. Ένας μικρός δέκτης σε Flask:

import base64, hashlib, hmac, json, os, time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["NAMEOCEAN_WEBHOOK_SECRET"]  # whsec_...


def verified(header, body, tolerance=300):
    fields = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    ts = int(fields.get("t", "0"))
    if abs(time.time() - ts) > tolerance:
        return False
    expected = hmac.new(SECRET.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, fields.get("v1", ""))


@app.post("/hooks/mail")
def mail():
    body = request.get_data()
    if not verified(request.headers.get("X-NameOcean-Signature", ""), body):
        abort(401)
    mail = json.loads(body)
    print(mail["envelope"]["from"], "→", mail["envelope"]["to"], mail["subject"])
    for a in mail["attachments"]:
        data = base64.b64decode(a["content_base64"])
        print("  attachment", a["filename"], a["content_type"], len(data), "bytes")
    return "", 204  # any 2xx: delivered

Τι λαμβάνετε

X-NameOcean-Event: email.received
X-NameOcean-Delivery: 6f1c2a4e-8b3d-4f5a-9c7e-1d2b3a4c5e6f
X-NameOcean-Signature: t=1794300000,v1=5f2b…

{
  "id": "6f1c2a4e-8b3d-4f5a-9c7e-1d2b3a4c5e6f",
  "event": "email.received",
  "received_at": "2026-11-11T09:30:12+00:00",
  "envelope": {"from": "alice@example.org", "to": "support@example.com"},
  "from": "Alice <alice@example.org>",
  "to": "support@example.com",
  "cc": null,
  "reply_to": null,
  "subject": "Order 1042",
  "date": "Wed, 11 Nov 2026 09:30:05 +0000",
  "message_id": "<…@example.org>",
  "in_reply_to": null,
  "references": null,
  "text": "Hi…",
  "html": "<p>Hi…</p>",
  "headers": [["From", "Alice <alice@example.org>"], …],
  "attachments": [{"filename": "invoice.pdf", "content_type": "application/pdf", "content_id": null,
                   "size": 48211, "content_base64": "JVBERi0…"}],
  "spam_score": 0.4,
  "size": 66120
}

Το id παραμένει ίδιο όταν ένα μήνυμα αποστέλλεται ξανά, οπότε χρησιμοποιήστε το για να παραλείπετε τα διπλότυπα. Τα in_reply_to και references δείχνουν σε ποιο από τα δικά σας μηνύματα απάντησε κάποιος.

Όταν το endpoint σας δεν είναι διαθέσιμο

• Μια απάντηση 2xx σημαίνει ότι παραδόθηκε. Σε 408, 429, 5xx, λήξη χρόνου (20 δευτερόλεπτα) ή αποτυχία σύνδεσης, γίνονται νέες προσπάθειες για 6 ώρες.
• Κάθε άλλο 4xx είναι οριστικό: το μήνυμα δεν αποστέλλεται ξανά αυτόματα.
• Τα μηνύματα που δεν μπόρεσαν να αποσταλούν διατηρούνται για 30 ημέρες. Βρείτε τα με nameocean email forwards log example.com (ή GET /email/forwarding/example.com/messages) και αποδεσμεύστε τα: αποστέλλονται άλλη μία φορά, με το ίδιο id.
• Έως 500 μηνύματα ημερησίως ανά domain αποστέλλονται σε webhooks· όσα τα υπερβαίνουν διατηρούνται με τον ίδιο τρόπο.