Odbieranie e-maili w aplikacji

Czego potrzebujesz

• Domena zarejestrowana w NameOcean: przekierowanie poczty i poczta do webhooka są dla nich bezpłatne.
• Endpoint HTTPS pod publicznym adresem, który odpowiada w ciągu 20 sekund.
• CLI nameocean lub klucz API z uprawnieniem email:write.

1. Włącz przekierowanie poczty dla domeny

$ nameocean email forwards on example.com

Spowoduje to skierowanie rekordu MX domeny na serwery przekierowania poczty NameOcean. Jeśli domena ma już rekordy MX, np. dla skrzynek u innego dostawcy, polecenie zatrzyma się i je wyświetli: cała poczta do domeny trafiałaby wtedy tutaj. Dodaj --replace-mx tylko wtedy, gdy właśnie tego Państwo chcą.

2. Poproś o pocztę do webhooka

Wysyłanie poczty na adres URL jest włączane dla każdego konta po krótkiej weryfikacji, aby nie dopuścić do przekaźników spamu. Na stronie domeny w Panel → Przekierowanie poczty poproś o tę funkcję, podając krótko, do czego będzie używana. Do tego czasu API zwraca 403 not_approved.

3. Skieruj adres do swojego endpointu

$ 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"}'

Odpowiedź zawiera sekret do podpisywania (whsec_…); zapisz go w ustawieniach aplikacji. localpart * przekazuje każdy adres w domenie, który nie ma własnego aliasu. Domena może mieć maksymalnie trzy takie webhooki.

4. Odbierz ją

Zweryfikuj podpis na podstawie surowej treści żądania, a następnie odczytaj JSON. Prosty odbiornik we Flasku:

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

Co przychodzi

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 pozostaje takie samo, gdy wiadomość zostanie wysłana ponownie, więc używaj go do pomijania duplikatów. in_reply_to i references wskazują, na którą z Twoich wiadomości ktoś odpowiedział.

Gdy endpoint nie działa

• Odpowiedź 2xx oznacza dostarczenie. Przy kodzie 408, 429, 5xx, przekroczeniu limitu czasu (20 sekund) lub braku połączenia próby są ponawiane przez 6 godzin.
• Każdy inny kod 4xx jest ostateczny: wiadomość nie zostanie automatycznie wysłana ponownie.
• Wiadomości, których nie udało się dostarczyć, są przechowywane przez 30 dni. Znajdziesz je poleceniem nameocean email forwards log example.com (lub GET /email/forwarding/example.com/messages) i możesz je zwolnić: zostaną wysłane jeszcze raz, z tym samym id.
• Do 500 wiadomości dziennie na domenę trafia do webhooków; poczta ponad ten limit jest wstrzymywana w ten sam sposób.