Migração de e-mail para empresas de hospedagem

Como se encaixa no seu negócio

• Mesmo endereço, servidor novo. O caso mais comum: info@customer.com continua igual, só a hospedagem muda. Copiamos agora todo o histórico e, depois da troca do MX, os últimos e-mails, ainda lendo do servidor antigo.
• Você nunca mexe em senhas se usar links de migração: o cliente digita as senhas no migrabox.com, elas são criptografadas e apagadas 14 dias depois da última cópia.
• Uma caixa, um crédito. De qualquer tamanho. Se a primeira cópia não conseguir começar porque uma senha está errada ou um servidor não responde, o crédito volta para o seu saldo.
• As chaves de teste são gratuitas e simulam todos os status e webhooks: você pode construir a integração inteira antes de comprar qualquer coisa.

Preços

Crédito pré-pago, válido por 12 meses a partir do pagamento. Os mesmos valores em euros e em dólares americanos: você escolhe a moeda no checkout. Pacotes diferentes se somam; o crédito é descontado primeiro do pacote que vence antes.

Velocidade padrão: até 20 Mbps por caixa. Uma opção mais rápida pela API está prevista (o campo speed já está reservado).

Comece em 5 minutos

1. 01Crie uma conta de parceiroNome da empresa e país aparecem nos seus recibos. Você entra com um link enviado por e-mail: nenhuma senha para gerenciar.
2. 02Crie uma chave de testeÁrea do parceiro → Chaves de API → modo Teste. Ela começa com mbx_test_ e só é exibida uma vez.
3. 03Chame a APICrie uma migração com o exemplo abaixo. No modo de teste nada é copiado: a migração passa por queued, running e completed em cerca de dez segundos.
4. 04Adicione um webhookÁrea do parceiro → Webhooks. Clique em Enviar evento de teste e confira se o seu endpoint verifica a assinatura.
5. 05Entre em produçãoCompre um pacote de crédito, crie uma chave mbx_live_ e troque pela de teste. Mesmas rotas, mesmos 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"

Autenticação

Toda requisição leva a sua chave no header Authorization: Authorization: Bearer mbx_live_…. Requisições sem uma chave válida recebem 401 UNAUTHORIZED.

As chaves são exibidas uma única vez e guardamos apenas a impressão digital SHA-256 delas. Trocar cria uma chave nova e mantém a antiga funcionando por 24 horas; Revogar desativa a chave na hora.

Uma chave só vê as migrações da própria empresa, no próprio modo: uma chave live nunca vê migrações de teste, e vice-versa. Qualquer outra coisa responde 404 NOT_FOUND.

Use a API apenas a partir dos seus servidores. Nunca coloque uma chave numa página web ou num app móvel.

Modo de teste

As chaves mbx_test_ usam as mesmas rotas das chaves live. Elas nunca se conectam a um servidor de e-mail, nunca guardam senhas e nunca usam crédito. Verificações e migrações são simuladas com uma sequência fixa: 2 segundos na fila, 8 segundos copiando e depois o status final, com todos os webhooks que uma migração real enviaria (somente para endpoints de teste).

Você escolhe o resultado pela senha de origem:

test-auth-failed

A criação falha com 422 SOURCE_AUTH_FAILED (como senha de destino: DEST_AUTH_FAILED).

test-connect-failed

A criação falha com 422 SOURCE_CONNECT_FAILED. Um host terminado em .invalid tem o mesmo efeito.

test-run-fails

A migração começa, depois falha com failure_code: AUTH_SOURCE e envia migration.failed.

test-run-errors

A migração termina como completed_with_errors (algumas mensagens não são copiadas).

Qualquer outra senha: a migração é concluída.

Link de migração ou servidor a servidor

Há duas formas de iniciar uma migração. As duas geram o mesmo objeto de migração, com os mesmos webhooks e a mesma página de status.

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", … }

Mesmo endereço, hospedagem nova

Use same_address: true quando o cliente mantém info@customer.com e o leva para os seus servidores. Origem e destino têm o mesmo endereço de e-mail; o host de destino é o seu novo servidor.

Na criação, guardamos os endereços do servidor antigo que respondeu. Todas as execuções seguintes se conectam a eles (com TLS verificado no nome antigo). Assim, depois que você apontar os registros MX para os seus servidores, POST /migrations/{id}/delta continua lendo a caixa antiga e busca o que chegou lá nesse meio-tempo.

Fluxo recomendado: crie a migração (ou o link) assim que a hospedagem estiver ativa → a cópia roda → troque o MX → chame delta → pronto. O delta é gratuito por 14 dias depois da última execução; mensagens já copiadas são ignoradas, então nada é duplicado.

Webhooks

Adicione endpoints na área do parceiro (somente https, nome DNS público, até 5 por modo). Enviamos via POST um evento JSON para cada endpoint inscrito naquele tipo. Os payloads nunca contêm senhas nem tokens privados.

Responda 2xx em até 10 segundos. Qualquer outra resposta é tentada de novo com intervalos crescentes (30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 6 h, 8 h: cerca de 22 horas no total). A área do parceiro mostra cada entrega e permite reenviá-la.

Os eventos podem chegar mais de uma vez e fora de ordem: use o id para processar cada evento uma única vez e considere o status do objeto como a referência.

Eventos

migration.created

Uma migração foi criada (API, linha de lote ou link de migração).

migration.started

Uma execução começou a copiar (primeira cópia ou delta).

migration.completed

Uma execução terminou: status é completed ou completed_with_errors.

migration.failed

Uma execução falhou: veja failure_code e credit_refunded.

migration.cancelled

Uma execução foi interrompida com /cancel.

link.opened

Seu cliente abriu um link de migração pela primeira vez.

link.submitted

Seu cliente enviou o link de migração: o objeto inclui a nova migração.

credits.low

O crédito live chegou ao seu limite de alerta (área do parceiro → Configurações).

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, …
  } }
}

Verifique a assinatura

Cada entrega traz o header Migrabox-Signature: t=<unix seconds>,v1=<hex>. v1 é o HMAC-SHA256 de t + "." + raw body, usando como chave o segredo de assinatura do endpoint (whsec_…, exibido uma única vez quando você cria o endpoint).

Calcule sobre o corpo bruto (antes de fazer o parse do JSON), compare em tempo constante e recuse timestamps com mais de 5 minutos para bloquear replays. Durante a troca do segredo, o header pode trazer mais de um v1: aceite o evento se qualquer um deles bater.

<?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")

Erros

Os erros são JSON com um code estável (use-o no seu código) e uma message em inglês (para os seus logs). O status HTTP indica a categoria: 4xx, problema na sua requisição; 5xx, problema nosso (tente de novo com a mesma Idempotency-Key).

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

Limites e convenções

• Limites por conta e modo (todas as suas chaves juntas), por endpoint e por minuto: 120 requisições, 60 criações, 30 verificações, 10 lotes. Acima do limite: 429 RATE_LIMITED. /probe e /discover em modo live ficam disponíveis após a primeira compra de crédito (antes: 402 CREDIT_REQUIRED).
• Idempotency-Key em todo POST: envie um valor único (o id do seu pedido ou da caixa). A primeira resposta fica guardada por 24 horas e é repetida para a mesma chave; o header Idempotent-Replayed: true avisa quando isso acontece.
• Paginação: GET /migrations?limit=20 retorna has_more e next_cursor; passe cursor= para a próxima página. Mais recentes primeiro.
• Os nomes de servidor precisam ser nomes DNS: endereços IP e redes privadas são recusados. Os certificados TLS são sempre verificados.
• As datas são ISO 8601 em UTC; o created dos webhooks é em segundos Unix. Podemos adicionar campos novos às nossas respostas a qualquer momento: ignore os que você não conhece.

Exemplos

Exemplos completos e sem dependências. Substitua a chave pela sua.

# 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}

Referência da API

URL base https://migrabox.com/api/v1. Os schemas completos estão no documento OpenAPI.

Histórico de alterações

• 2026-11-12v1: migrações, lotes, links de migração com o seu logo, delta, cancelamento, relatório, discover, probe, webhooks assinados, modo de teste.