E-Mail-Umzüge für Hosting-Anbieter

So passt es in Ihr Geschäft

• Gleiche Adresse, neuer Server. Der häufigste Fall: info@customer.com bleibt, nur das Hosting wechselt. Wir kopieren jetzt den gesamten Bestand und nach der MX-Umstellung die letzten E-Mails, weiterhin vom alten Server.
• Sie fassen nie Passwörter an, wenn Sie Umzugslinks nutzen: Der Kunde gibt sie auf migrabox.com ein, sie werden verschlüsselt gespeichert und 14 Tage nach der letzten Kopie gelöscht.
• Ein Postfach, eine Einheit Guthaben. Unabhängig von der Größe. Kann die erste Kopie nicht starten, weil ein Passwort falsch ist oder ein Server nicht antwortet, wird die Einheit Ihrem Guthaben wieder gutgeschrieben.
• Testschlüssel sind kostenlos und simulieren jeden Status und jeden Webhook. So bauen Sie die komplette Integration, bevor Sie etwas kaufen.

Preise

Prepaid-Guthaben, gültig 12 Monate ab Zahlung. Gleiche Beträge in Euro und US-Dollar: Die Währung wählen Sie beim Bezahlen. Mehrere Pakete werden addiert; abgebucht wird zuerst vom Paket, das am frühesten abläuft.

Standardgeschwindigkeit: bis zu 20 Mbit/s pro Postfach. Eine schnellere Variante über die API ist geplant (das Feld speed ist bereits reserviert).

Schnellstart in 5 Minuten

1. 01Partnerkonto anlegenFirmenname, Land und USt-IdNr. erscheinen auf Ihren Belegen. Sie melden sich über einen Link per E-Mail an: Es gibt kein Passwort zu verwalten.
2. 02Testschlüssel erstellenPartnerbereich → API-Schlüssel → Modus Test. Er beginnt mit mbx_test_ und wird nur einmal angezeigt.
3. 03API aufrufenLegen Sie mit dem Beispiel unten einen Umzug an. Im Testmodus wird nichts kopiert: Der Umzug durchläuft queued, running und completed in etwa zehn Sekunden.
4. 04Webhook hinzufügenPartnerbereich → Webhooks. Klicken Sie auf Testereignis senden und prüfen Sie, ob Ihr Endpoint die Signatur verifiziert.
5. 05Live gehenKaufen Sie ein Guthabenpaket, erstellen Sie einen mbx_live_-Schlüssel und tauschen Sie ihn aus. Gleiche Routen, gleiche Payloads.

# 1. Your test key (partner area → API keys). Test mode never copies anything.
export MIGRABOX_KEY=mbx_test_...

# 2. Check the key and your credit
curl https://migrabox.com/api/v1/account -H "Authorization: Bearer $MIGRABOX_KEY"

# 3. Create a migration (server to server)
curl https://migrabox.com/api/v1/migrations \
  -H "Authorization: Bearer $MIGRABOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-mailbox-1" \
  -d '{
    "source":      { "email": "info@customer.com", "host": "imap.oldhost.com", "password": "old-secret" },
    "destination": { "email": "info@customer.com", "host": "imap.yourhosting.com", "password": "new-secret" },
    "same_address": true,
    "external_id": "order-1001"
  }'

# 4. Follow it (or wait for the migration.completed webhook)
curl https://migrabox.com/api/v1/migrations/MIGRATION_ID -H "Authorization: Bearer $MIGRABOX_KEY"

Authentifizierung

Jede Anfrage enthält Ihren Schlüssel im Header Authorization: Authorization: Bearer mbx_live_…. Anfragen ohne gültigen Schlüssel erhalten 401 UNAUTHORIZED.

Schlüssel werden nur einmal angezeigt; wir speichern nur einen SHA-256-Fingerabdruck. Erneuern erstellt einen neuen Schlüssel und lässt den alten noch 24 Stunden funktionieren; Widerrufen sperrt ihn sofort.

Ein Schlüssel sieht nur die Umzüge der eigenen Firma im eigenen Modus: Ein Live-Schlüssel sieht nie Testumzüge und umgekehrt. Alles andere beantworten wir mit 404 NOT_FOUND.

Rufen Sie die API nur von Ihren Servern auf. Legen Sie einen Schlüssel nie in eine Webseite oder eine mobile App.

Testmodus

mbx_test_-Schlüssel nutzen dieselben Routen wie Live-Schlüssel. Sie verbinden sich nie mit einem Mailserver, speichern nie Passwörter und verbrauchen nie Guthaben. Prüfungen und Umzüge werden mit festem Ablauf simuliert: 2 Sekunden in der Warteschlange, 8 Sekunden Kopieren, dann der Endstatus, mit allen Webhooks, die ein echter Umzug senden würde (nur an Test-Endpoints).

Das Ergebnis steuern Sie über das Quellpasswort:

test-auth-failed

Das Anlegen scheitert mit 422 SOURCE_AUTH_FAILED (als Zielpasswort: DEST_AUTH_FAILED).

test-connect-failed

Das Anlegen scheitert mit 422 SOURCE_CONNECT_FAILED. Ein Host, der auf .invalid endet, bewirkt dasselbe.

test-run-fails

Der Umzug startet, scheitert dann mit failure_code: AUTH_SOURCE und sendet migration.failed.

test-run-errors

Der Umzug endet als completed_with_errors (einige Nachrichten nicht kopiert).

Jedes andere Passwort: Der Umzug wird abgeschlossen.

Umzugslink oder Server zu Server

Es gibt zwei Wege, einen Umzug zu starten. Beide führen zum selben Umzugsobjekt, zu denselben Webhooks und zur selben Statusseite.

curl https://migrabox.com/api/v1/migration-links \
  -H "Authorization: Bearer $MIGRABOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-7731" \
  -d '{
    "locale": "en",
    "external_id": "service-7731",
    "same_address": true,
    "source_email": "info@customer.com",
    "destination": { "host": "imap.yourhosting.com", "port": 993, "security": "ssl" }
  }'
# → { "id": "…", "url": "https://migrabox.com/en/email-move/#…", "status": "open", … }

Gleiche Adresse, neues Hosting

Setzen Sie same_address: true, wenn der Kunde info@customer.com behält und auf Ihre Server umzieht. Quelle und Ziel haben dieselbe E-Mail-Adresse; der Zielhost ist Ihr neuer Server.

Beim Anlegen speichern wir die Adressen des alten Servers, der geantwortet hat. Jeder weitere Lauf verbindet sich mit ihnen (TLS wird gegen den alten Namen geprüft). Nachdem Sie die MX-Einträge auf Ihre Server umgestellt haben, liest POST /migrations/{id}/delta also weiterhin das alte Postfach und holt, was dort inzwischen angekommen ist.

Empfohlener Ablauf: Umzug (oder Umzugslink) anlegen, sobald das Hosting aktiv ist → Kopie läuft → MX umstellen → delta aufrufen → fertig. Delta ist innerhalb von 14 Tagen nach dem letzten Lauf kostenlos; bereits kopierte Nachrichten werden übersprungen, es entstehen keine Duplikate.

Webhooks

Legen Sie Endpoints im Partnerbereich an (nur https, öffentlicher DNS-Name, bis zu 5 pro Modus). Wir senden per POST ein JSON-Ereignis an jeden Endpoint, der den jeweiligen Typ abonniert hat. Payloads enthalten nie Passwörter oder private Tokens.

Antworten Sie innerhalb von 10 Sekunden mit 2xx. Alles andere wird mit wachsenden Abständen erneut zugestellt (30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 6 h, 8 h: insgesamt etwa 22 Stunden). Der Partnerbereich zeigt jede Zustellung und erlaubt eine erneute Zustellung.

Ereignisse können mehrfach und in anderer Reihenfolge ankommen: Verarbeiten Sie jedes Ereignis anhand von id nur einmal, und verlassen Sie sich auf den status des Objekts.

Ereignisse

migration.created

Ein Umzug wurde angelegt (API, Batch-Zeile oder Umzugslink).

migration.started

Ein Lauf hat mit dem Kopieren begonnen (erste Kopie oder Delta).

migration.completed

Ein Lauf ist beendet: status ist completed oder completed_with_errors.

migration.failed

Ein Lauf ist fehlgeschlagen: siehe failure_code und credit_refunded.

migration.cancelled

Ein Lauf wurde mit /cancel gestoppt.

link.opened

Ihr Kunde hat einen Umzugslink zum ersten Mal geöffnet.

link.submitted

Ihr Kunde hat den Umzugslink abgeschickt: Das Objekt enthält den neuen Umzug.

credits.low

Das Live-Guthaben hat Ihre Warnschwelle erreicht (Partnerbereich → Einstellungen).

POST /your/webhook HTTP/1.1
Content-Type: application/json
Migrabox-Signature: t=1794470900,v1=5f2b…c9
Migrabox-Event-Id: evt_7Qm1…

{
  "id": "evt_7Qm1…",
  "object": "event",
  "api_version": "2026-11-12",
  "type": "migration.completed",
  "created": 1794470900,
  "livemode": true,
  "data": { "object": {
    "id": "92430b5b-…", "object": "migration", "status": "completed", "external_id": "order-1001",
    "source": { "email": "info@customer.com", "host": "imap.oldhost.com" },
    "destination": { "email": "info@customer.com", "host": "imap.yourhosting.com" },
    "progress": { "run": "full", "messages_total": 18234, "messages_done": 18234, "percent": 100, … },
    "credit_refunded": false, "can_delta": true, …
  } }
}

Signatur prüfen

Jede Zustellung trägt den Header Migrabox-Signature: t=<unix seconds>,v1=<hex>. v1 ist der HMAC-SHA256 von t + "." + raw body, mit dem Signing Secret des Endpoints als Schlüssel (whsec_…, wird beim Anlegen des Endpoints einmal angezeigt).

Berechnen Sie ihn über den unveränderten Body (vor dem JSON-Parsing), vergleichen Sie in konstanter Zeit und lehnen Sie Zeitstempel ab, die älter als 5 Minuten sind, um Replays zu verhindern. Während einer Secret-Rotation kann der Header mehrere v1 enthalten: Akzeptieren Sie das Ereignis, wenn einer davon passt.

<?php
// Verify Migrabox-Signature on the RAW body, before json_decode.
$secret = getenv('MIGRABOX_WEBHOOK_SECRET'); // whsec_...
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_MIGRABOX_SIGNATURE'] ?? '';
$parts = [];
foreach (explode(',', $header) as $p) { [$k, $v] = array_pad(explode('=', $p, 2), 2, ''); $parts[$k][] = $v; }
$t = (int) ($parts['t'][0] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
$valid = abs(time() - $t) <= 300 && array_filter($parts['v1'] ?? [], fn($s) => hash_equals($expected, $s));
if (!$valid) { http_response_code(400); exit; }

$event = json_decode($body, true);
// Deliveries can repeat: use $event['id'] to process each event once.
if ($event['type'] === 'migration.completed') {
    $migration = $event['data']['object']; // ['id'], ['external_id'], ['status'], ['progress'] ...
}
http_response_code(200); // answer within 10 seconds, do slow work afterwards

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the request body exactly as received (Buffer or string), before JSON.parse.
export function verifyMigrabox(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = header.split(',').map((p) => p.split('='));
  const t = Number(parts.find(([k]) => k === 't')?.[1]);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = Buffer.from(createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'));
  return parts.filter(([k]) => k === 'v1').some(([, v]) => {
    const got = Buffer.from(v ?? '');
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

import hashlib, hmac, time

def verify_migrabox(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = [p.split("=", 1) for p in header.split(",") if "=" in p]
    t = next((v for k, v in parts if k == "t"), "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, v) for k, v in parts if k == "v1")

Fehler

Fehler sind JSON mit einem stabilen code (für Ihren Code) und einer englischen message (für Ihre Logs). Der HTTP-Status zeigt die Kategorie: 4xx betrifft Ihre Anfrage, 5xx liegt bei uns (erneut versuchen mit demselben Idempotency-Key).

HTTP/1.1 422 Unprocessable Entity
{ "error": { "code": "SOURCE_AUTH_FAILED", "message": "Cannot sign in to the source mailbox" } }

Limits und Konventionen

• Rate Limits pro Konto und Modus (alle Ihre Schlüssel zusammen), pro Endpoint und Minute: 120 Anfragen, 60 Anlagen, 30 Prüfungen, 10 Batches. Darüber: 429 RATE_LIMITED. /probe und /discover im Live-Modus stehen nach dem ersten Guthabenkauf zur Verfügung (vorher: 402 CREDIT_REQUIRED).
• Idempotency-Key bei jedem POST: Senden Sie einen eindeutigen Wert (Ihre Bestell- oder Postfach-ID). Die erste Antwort wird 24 Stunden gespeichert und für denselben Key erneut ausgeliefert; der Header Idempotent-Replayed: true zeigt das an.
• Paginierung: GET /migrations?limit=20 liefert has_more und next_cursor; übergeben Sie cursor= für die nächste Seite. Neueste zuerst.
• Servernamen müssen DNS-Namen sein: IP-Adressen und private Netze werden abgelehnt. TLS-Zertifikate werden immer geprüft.
• Datumsangaben sind ISO 8601 in UTC; created in Webhooks sind Unix-Sekunden. Unsere Antworten können jederzeit neue Felder bekommen: Ignorieren Sie unbekannte Felder.

Beispiele

Vollständige Beispiele ohne Abhängigkeiten. Ersetzen Sie den Schlüssel durch Ihren eigenen.

# 1. Your test key (partner area → API keys). Test mode never copies anything.
export MIGRABOX_KEY=mbx_test_...

# 2. Check the key and your credit
curl https://migrabox.com/api/v1/account -H "Authorization: Bearer $MIGRABOX_KEY"

# 3. Create a migration (server to server)
curl https://migrabox.com/api/v1/migrations \
  -H "Authorization: Bearer $MIGRABOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-mailbox-1" \
  -d '{
    "source":      { "email": "info@customer.com", "host": "imap.oldhost.com", "password": "old-secret" },
    "destination": { "email": "info@customer.com", "host": "imap.yourhosting.com", "password": "new-secret" },
    "same_address": true,
    "external_id": "order-1001"
  }'

# 4. Follow it (or wait for the migration.completed webhook)
curl https://migrabox.com/api/v1/migrations/MIGRATION_ID -H "Authorization: Bearer $MIGRABOX_KEY"

<?php
// Works on any PHP 7.4+ with the curl extension (WHMCS, cPanel, Plesk). No dependencies.
function migrabox(string $method, string $path, ?array $body = null, ?string $idempotencyKey = null): array {
    $ch = curl_init('https://migrabox.com/api/v1' . $path);
    $headers = ['Authorization: Bearer ' . getenv('MIGRABOX_KEY'), 'Accept: application/json'];
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    if ($idempotencyKey !== null) $headers[] = 'Idempotency-Key: ' . $idempotencyKey;
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60,
    ]);
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    $json = json_decode((string) $raw, true) ?? [];
    if ($status >= 400) throw new RuntimeException(($json['error']['code'] ?? 'HTTP_' . $status) . ': ' . ($json['error']['message'] ?? ''));
    return $json;
}

// Hosted link: your customer types the passwords on our page, you never handle them.
$link = migrabox('POST', '/migration-links', [
    'locale' => 'en',
    'external_id' => 'service-' . $serviceId,
    'same_address' => true,
    'source_email' => $customerEmail,
    'destination' => ['host' => 'imap.yourhosting.com', 'port' => 993, 'security' => 'ssl'],
], 'link-service-' . $serviceId);

echo $link['url']; // send it in your welcome email

// Node 18+ (built-in fetch). No dependencies.
const BASE = 'https://migrabox.com/api/v1';
async function migrabox(method, path, body, idempotencyKey) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.MIGRABOX_KEY}`,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) throw Object.assign(new Error(json.error.message), { code: json.error.code, status: res.status });
  return json;
}

const migration = await migrabox('POST', '/migrations', {
  source: { email: 'info@customer.com', host: 'imap.oldhost.com', password: oldPassword },
  destination: { email: 'info@customer.com', host: 'imap.yourhosting.com', password: newPassword },
  same_address: true,
  external_id: 'order-1001',
}, 'order-1001-mailbox-1');
console.log(migration.id, migration.status); // "queued"

# Python 3.8+, standard library only.
import json, os, urllib.request, urllib.error

BASE = "https://migrabox.com/api/v1"

def migrabox(method, path, body=None, idempotency_key=None):
    headers = {"Authorization": f"Bearer {os.environ['MIGRABOX_KEY']}"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    req = urllib.request.Request(BASE + path, data=data, headers=headers, method=method)
    try:
        with urllib.request.urlopen(req, timeout=60) as r:
            return json.load(r)
    except urllib.error.HTTPError as e:
        err = json.load(e)["error"]
        raise RuntimeError(f"{err['code']}: {err['message']}") from None

batch = migrabox("POST", "/migrations/batch", {"migrations": [
    {"source": {"email": m["email"], "host": "imap.oldhost.com", "password": m["old"]},
     "destination": {"email": m["email"], "host": "imap.yourhosting.com", "password": m["new"]},
     "same_address": True, "external_id": m["id"]}
    for m in mailboxes
]}, idempotency_key="import-2026-11-12")
print(batch["id"], batch["status"])  # "processing": then GET /migrations/batch/{id}

API-Referenz

Basis-URL https://migrabox.com/api/v1. Die vollständigen Schemas stehen im OpenAPI-Dokument.

Änderungsprotokoll

• 2026-11-12v1: Umzüge, Batch, Umzugslinks mit Ihrem Logo, Delta, Abbruch, Bericht, discover, probe, signierte Webhooks, Testmodus.