Test routes with a loopback mailbox

Use a loopback mailbox when you want to test the onboarding route and endpoint flow before connecting a production mailbox.

A loopback mailbox is a temporary MailWebhook-hosted inbound alias created during onboarding. It can receive the onboarding test email, match the generated route rule, run the default map.generic_json pipeline, and deliver the resulting webhook request to the selected endpoint.

Table of contents

  1. Prerequisites
  2. Loopback-specific fields
  3. Testing steps
    1. 1. Start with the loopback mailbox
    2. 2. Choose the endpoint destination
    3. 3. Send the onboarding test email
    4. 4. Inspect preview events
    5. 5. Replace loopback before production
  4. Setup checks
  5. Verify payload and delivery
  6. Loopback behavior
  7. Route and payload behavior
  8. Common errors
    1. Loopback alias is not active
    2. Test email requires a saved endpoint
    3. Saved route state is stale
    4. Please wait before sending another onboarding test email
    5. No preview event appears
    6. Delivery fails
  9. Related docs

Prerequisites

You need:

  • A signed-in MailWebhook account and project.
  • Access to the onboarding flow.
  • A destination choice for the endpoint step:
    • Test loopback for a built-in test destination.
    • Configure for your own public webhook URL.
    • Slack or Telegram when you want the onboarding flow to create a chat destination route.

If you use Configure, your endpoint must be reachable from MailWebhook and must return a 2xx response after it accepts the request.

Loopback-specific fields

Loopback setup has fewer manual mailbox fields than production mailbox setup because MailWebhook creates the test mailbox address automatically.

FieldUse
Mailbox addressGenerated automatically during onboarding and added to the mailbox selector.
Endpoint providerSelects the destination used by the generated onboarding route. Options include Test loopback, Configure, Slack, and Telegram.
Endpoint URLRequired only for Configure. Test loopback uses the configured MailWebhook test receiver.

The loopback mailbox address cannot be used as a long-term production source. It is created for onboarding and temporary route tests.

Testing steps

Open Onboarding. If the modal is closed, click Setup Wizard.

1. Start with the loopback mailbox

When onboarding opens, MailWebhook starts or refreshes a temporary loopback alias and adds it to the mailbox selector.

The generated address is ready to receive test email immediately. It uses the configured loopback domain. The default deployment domain is loopback.mailwebhook.com.

2. Choose the endpoint destination

In 2. Endpoint, choose the destination you want to test:

DestinationWhat MailWebhook saves
Test loopbackAn endpoint that points to the configured MailWebhook test receiver.
ConfigureAn endpoint that points to your public webhook URL.
SlackA route pipeline that sends matching mail to the selected Slack channel.
TelegramA route pipeline that sends matching mail to the selected Telegram chat.

For the HTTP options, MailWebhook provisions a route and endpoint pair. The route rule targets the selected mailbox address with to_emails, the endpoint timeout is 10 seconds, and the default pipeline is:

{
  "steps": [
    {
      "name": "map.generic_json",
      "args": {}
    }
  ]
}

When Test loopback is selected and a loopback mailbox is active, the UI can save the endpoint step automatically. If you change the mailbox or endpoint provider, save the endpoint step again before sending a test email.

3. Send the onboarding test email

In 3. Send Email, click Send Test Email when the button is available.

MailWebhook sends a deterministic onboarding email to the selected mailbox address. For a default HTTP route, the subject is:

MailWebhook onboarding test email (http)

The message body includes the project id, route id, endpoint id, provider, recipient, send timestamp, and generated Message-ID so you can trace the message through preview events and delivery attempts.

Test sends have a 15 second cooldown. If you click again too soon, MailWebhook returns a retry-after value.

4. Inspect preview events

Use Webhook Preview to inspect the request and response generated by the saved route.

Check:

  • The event appears after the endpoint step is saved.
  • The route id and endpoint id match the saved onboarding pair.
  • The request body is the route pipeline output.
  • For map.generic_json, the payload contains schema, event, message, body, and meta.
  • Delivery succeeds only when the destination returns a 2xx response.

Preview polling starts from the timestamp recorded when the endpoint step was saved. If you save the endpoint step again, the preview timeline starts from the new save anchor.

5. Replace loopback before production

Loopback is for onboarding and tests only. To go live, replace the loopback mailbox with a production source such as Gmail, Microsoft 365, IMAP, or a hosted mailbox.

If the endpoint is still Test loopback, replace it with a real destination before treating the route as production. Onboarding can finalize only after the loopback mailbox has been replaced. If you keep a real mailbox but defer the endpoint, the product prompts you to add a real endpoint later.

Setup checks

After the loopback setup is saved, check:

  • The mailbox selector shows the generated loopback address.
  • The endpoint step is saved for the current mailbox and endpoint provider.
  • For HTTP destinations, the route rule targets the loopback address with to_emails.
  • For HTTP destinations, the default pipeline is map.generic_json.
  • Webhook Preview shows events created after the latest endpoint save anchor.
  • Delivery succeeds only when the selected destination returns a 2xx response.

Loopback proves that MailWebhook can create a route, run the mapper, and deliver the request to the selected destination. It does not prove that Gmail, Microsoft 365, IMAP, or a hosted mailbox has been connected correctly.

Verify payload and delivery

Send the onboarding test email, then open Webhook Preview or Events.

For an HTTP destination, verify:

  • The event route id and endpoint id match the saved onboarding pair.
  • The request body is the route pipeline output.
  • For map.generic_json, the body contains schema, event, message, body, and meta.
  • The delivery attempt shows a 2xx response for success.
  • Failed attempts show the response status or timeout details that need to be fixed before replay.

For chat destinations, verify the message arrives in the selected Slack channel or Telegram chat.

Loopback behavior

BehaviorCurrent product behavior
Address creationMailWebhook creates the alias automatically during onboarding.
Address formatA generated localpart at the configured loopback domain. The default domain is loopback.mailwebhook.com.
ExpirationThe active alias expires 60 minutes after start or refresh.
Message capThe default alias cap is 25 messages.
Mailbox typeThe mailbox type is loopback.
Inbound pathLoopback mail is accepted through MailWebhook’s hosted inbound path.
Normal mailbox listsLoopback mailboxes stay out of normal mailbox lists.
Normal mailbox limitsLoopback mailboxes do not count against normal mailbox limits.

Starting onboarding reuses an active loopback alias when one exists. Otherwise, MailWebhook creates a new alias for the project. Closing the onboarding loopback session disables active loopback aliases.

Route and payload behavior

For HTTP destinations, the saved onboarding route uses this rule shape:

{
  "to_emails": ["test-address@loopback.mailwebhook.com"]
}

Replace the address with the generated loopback address shown in the UI.

The default HTTP pipeline uses map.generic_json. Because loopback mail enters through the hosted inbound path, Generic JSON payloads use meta.source set to hosted even though the onboarding mailbox type is loopback.

Example payload shape:

{
  "schema": {
    "name": "mailwebhook.generic",
    "version": "1"
  },
  "event": {
    "id": "6ff49aa1-7050-4ad1-95d9-2711f2ca7e88",
    "project_id": "dca29061-c4a7-4687-a8dd-24d2f26548c7",
    "route_id": "2f3713bf-88cc-46c6-aaa3-ea9d6e9d20f3",
    "created_at": "2026-06-28T12:00:02Z"
  },
  "message": {
    "message_id": "<onboarding-test-...@mailwebhook.local>",
    "message_id_type": "original",
    "subject": "MailWebhook onboarding test email (http)",
    "date": "2026-06-28T12:00:00Z",
    "from": [{ "email": "sender@example.com" }],
    "to": [{ "email": "test-address@loopback.mailwebhook.com" }]
  },
  "envelope": {
    "mail_from": "sender@example.com",
    "rcpt_to": ["test-address@loopback.mailwebhook.com"]
  },
  "body": {
    "text": "MailWebhook onboarding test email\nProject ID: ...",
    "attachments": []
  },
  "meta": {
    "source": "hosted",
    "raw_size_bytes": 2048,
    "received_at": "2026-06-28T12:00:00Z"
  }
}

The exact payload depends on the selected destination and route pipeline. See Webhook payload reference for mapper choices and Generic JSON for the full default payload contract.

Common errors

Loopback alias is not active

The active alias expired or the onboarding loopback session was closed. Reopen onboarding to start or refresh the loopback alias, then save the endpoint step again.

Test email requires a saved endpoint

The test-send action requires a saved onboarding route and endpoint pair. Save the endpoint step before sending the test email.

Saved route state is stale

The saved route or endpoint was removed or changed after onboarding saved the pair. Save the endpoint step again so onboarding records the current route and endpoint ids.

Please wait before sending another onboarding test email

Onboarding test sends have a 15 second cooldown. Wait for the retry-after period and send again.

No preview event appears

Check these items:

  • The endpoint step was saved after the current mailbox and endpoint selection.
  • The selected mailbox address is the loopback address you sent to.
  • The loopback alias has not expired.
  • The route is enabled.
  • The route rule includes the loopback address in to_emails.
  • The endpoint destination accepts POST requests and returns a 2xx response for success.

Delivery fails

Open the preview response or the event delivery attempt. Failed attempts usually mean the endpoint rejected the request, timed out, or returned a non-2xx status. Fix the endpoint and replay where appropriate.