> ## Documentation Index > Fetch the complete documentation index at: https://docs.mailchannels.com/llms.txt > Use this file to discover all available pages before exploring further. # Test and roll out an Outbound Filtering migration > Build a representative test environment, check common migration failures, and move customer email to MailChannels in phases with clear rollback criteria. Use a dedicated test environment to verify your customer sending paths, then move production traffic in small groups. Start with domains you control, follow with a representative customer pilot, and expand when delivery and operational checks pass. A successful SMTP connection is only the first check. Your tests should also establish that messages authenticate correctly, remain attributable to the right sender, reach recipients, and produce useful evidence when delivery fails. ## Build a representative test environment Match the parts of your customer setup that affect mail delivery. Keep an inventory of differences between the test environment and production so you can cover them during the pilot. | Area | What to mirror | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Mail servers | MTA and control panel versions, MailChannels plugin or manual configuration, routing rules, queue settings, and per-customer sending limits. | | Sending sources | Authenticated SMTP, webmail, website forms, PHP or local mail submission, scheduled jobs, and any other path your customers use. | | Sender identity | The mapping from each authenticated user or local application to its sender ID, including how you distinguish identical usernames on different servers. | | DNS and authentication | Provider-managed and customer-managed DNS, sending subdomains, strict SPF policies, indirect SPF includes, DKIM signing, and DMARC policies. | | Network | DNS resolution, firewall rules, outbound SMTP ports, NAT, and TLS settings. Repeat connectivity checks from each production network before its migration. | | Message types | Representative transactional messages, plain text and HTML, attachments, non-ASCII content, forwarding, and delivery failure notifications. | ### Use real mail with a low cost of failure Test with real email messages from a domain you control, using a workload where a delayed or missing message has little impact. Good starting points include routine cron reports from a server you operate or noncritical internal notifications from a company subdomain. Choose recipients on your team who can tolerate failures, so real customers are not affected. Include controlled mailboxes at the recipient providers your customers commonly use. Avoid repeatedly sending messages with a simple subject or body such as "Testing 1 2 3". Sending many messages like this is likely to trigger spam classification and blocking. Use the workload's normal subjects, useful message content, and natural sending cadence. Do not clone a live outgoing queue or enable copied scheduled jobs that still address real customers. ### Arrange a test account For larger customers that need a test account during onboarding, MailChannels provisions a special **Outbound Filtering sub-account**. This feature is specific to Outbound Filtering and is separate from the Email API sub-account feature. MailChannels provides these test accounts free of charge to qualifying customers above a certain scale. Contact [MailChannels support](https://support.mailchannels.com/hc/en-us/requests/new) with your expected sending volume and migration plan to confirm eligibility and arrange provisioning. Use the test credentials and account identifiers supplied by MailChannels. Keep distinct test sender identities; creating a separate SMTP password alone does not provide account or reputation isolation. Test-account messages are still subject to normal filtering. Agree on expected volume and any load or abuse-simulation testing with support before running those tests. Configure the test MTA using the relevant [mail server setup guide](/outbound/configure-mail-server). Send through the same client-to-MTA path your customers use. This exercises local routing, signing, and sender identification as well as the connection to MailChannels. ## Prepare DNS and a delivery baseline Run the [customer SPF audit](/outbound/migration-center/prepare-customer-dns) before selecting a pilot group. Resolve required changes and manual-review items for each group before moving its traffic. If a customer defers an optional SPF update, verify that their authentication plan still meets their DMARC requirements. Configure [Domain Lockdown™](/outbound/domain-lockdown) for the account and sender identities used in each environment. A record that authorizes your production account can reject a separate test account. Use the intended values on your test domains, then verify production values during the pilot. Capture a baseline from your current delivery route over a period that includes normal busy hours and scheduled sending. Record: * Submission volume and delivery outcomes by customer group and recipient provider. * Queue depth, oldest queued message, and typical delivery delay. * Temporary deferrals, permanent rejections, and authentication failures. * Sender attribution, abuse reports, and delivery-related support tickets. Define acceptable deviations and who can pause the rollout before you start. Use rates as well as counts, and compare similar traffic periods. A test domain with little sending history cannot reproduce every production reputation or recipient-filtering decision. ## Configure SRS for forwarded mail Customers may host `www.example.com` with you while forwarding mail addressed to `info@example.com` to `customer@gmail.com`. Configure **Sender Rewriting Scheme (SRS)** on the forwarding MTA before relaying this traffic through MailChannels. This applies to every hosting setup that forwards mail, whether or not you use cPanel. SRS rewrites the SMTP envelope sender (`MAIL FROM`) to an address under a domain your forwarding service controls. SPF checks that domain against the sending IP. Without SRS, forwarding normally retains the original sender's envelope domain, which may not authorize MailChannels. The final recipient's domain does not determine which SPF record is checked. For example, suppose `alice@gmail.com` sends to the hosted address `info@example.com`, which forwards to `customer@gmail.com`: | Forwarding stage | Envelope sender (`MAIL FROM`) | Recipient (`RCPT TO`) | | ------------------------ | ----------------------------- | --------------------- | | Original message arrives | `alice@gmail.com` | `info@example.com` | | Forwarded without SRS | `alice@gmail.com` | `customer@gmail.com` | | Forwarded with SRS | `SRS0=...@example.com` | `customer@gmail.com` | The SRS address above is illustrative; your MTA generates the encoded local part. Without rewriting, SPF checks `gmail.com`, which does not authorize MailChannels to send its mail. With SRS, SPF checks `example.com`, which you can authorize with `include:relay.mailchannels.net`. Your setup can use a dedicated forwarding subdomain instead; publish and audit SPF at that exact name. For cPanel, follow the [SRS forwarding configuration](/outbound/mta/setup-cpanel). For other platforms, configure your MTA's supported SRS implementation, including decoding return addresses so delivery failures can reach the original sender. The [Exim SRS documentation](https://www.exim.org/exim-html-current/doc/html/spec_html/ch-dkim_spf_srs_and_dmarc.html) describes this mechanism for Exim. SRS leaves the visible From address unchanged. An SPF pass for the rewritten domain does not by itself provide DMARC alignment with the original sender. Preserve the original DKIM signature and test DMARC at the final recipient. Before moving a group that uses forwarding, verify the rewritten `MAIL FROM` in your MTA logs, SPF results at the destination, and bounce handling back through the forwarding service. Include the SRS domain in your [DNS audit](/outbound/migration-center/prepare-customer-dns). ## Run the test matrix Record the result for each sending source and MTA configuration you plan to migrate. Keep the real message's subject and content, and use its Message-ID and local queue ID to correlate results. Save the UTC timestamp, sender ID, SMTP response, and received headers where available. | Test | What to do | Passing result | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Relay connection | Submit from your test MTA using the configured relay hostname, port, credentials, and TLS settings. | The MTA authenticates over TLS and the logs show the intended MailChannels route. | | Customer sending paths | Send from webmail, authenticated SMTP, local scripts, and scheduled jobs. | Every intended path uses the relay; local delivery and excluded routes still behave as intended. | | Sender attribution | Send from at least two distinct test users and a local application. | [Log Search](/outbound/log-search) and [Sender Profiles](/outbound/sender-profiles) distinguish the senders. Originated mail has the expected `X-AuthUser` identity, rather than a shared placeholder. | | Email authentication | Inspect the receiving server's `Authentication-Results` and the message's envelope sender and visible From address. | SPF, DKIM, and DMARC match your intended configuration. Required alignment passes, and no unexplained DKIM failure remains. | | Domain Lockdown | Send with the authorized test identity. On a domain you control, test an unauthorized identity if your test arrangement permits it. | Authorized traffic succeeds and the unauthorized case is rejected. | | Content and recipients | Send real cron reports or noncritical internal notifications, including the attachments those workloads normally produce, to your controlled recipient mailboxes. | Messages arrive intact; inbox or junk placement is recorded separately from SMTP acceptance. | | Forwarding and bounces | Exercise aliases, external forwarding with SRS, and delivery failure notifications used by your customers. | The rewritten envelope domain authorizes MailChannels in SPF. Routing completes without loops, original DKIM signatures remain valid, and failure notifications reach the original sender. | | Failure recovery | Use a controlled SMTP test server to return temporary and permanent failures. Separately interrupt the test MTA's relay connection and restore it. | The MTA handles retries and failures correctly, retains deferred mail, and recovers without an uncontrolled queue flush. | | Operational response | Trace a failed test message and rehearse the support or abuse response. | Your team can identify the sender, explain the outcome, and reach the correct escalation path. | For failure recovery, verify that temporary `4xx` replies are deferred and retried, while permanent `5xx` replies are surfaced as failures rather than retried indefinitely. These reply classes are defined in the [SMTP specification](https://www.rfc-editor.org/rfc/rfc5321.html#section-4.2.1). Use a controlled test server for repeatable error cases; avoid generating large numbers of invalid recipients or spam messages through the live relay. Check both your MTA logs and MailChannels [Log Search](/outbound/log-search). A final SMTP acceptance response transfers responsibility to the accepting server; it does not prove inbox placement. Confirm arrival and received headers in your test mailboxes. See [SMTP mail transactions](https://www.rfc-editor.org/rfc/rfc5321.html#section-3.3). Set up [monitors and alerts](/outbound/monitors-alerts) if your plan includes them. Verify that the responsible team receives notifications and can act on them. Otherwise, schedule log and queue reviews during each migration window. ## Watch for common migration pitfalls | Pitfall | How to avoid it | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Testing only one message from one mailbox | Cover each sending source, MTA variant, DNS arrangement, and major recipient provider. A website script can use a different transport from webmail. | | Moving mail before DNS is ready | Confirm authoritative records and allow cached records to expire. If you lower a TTL, do it at least the previous TTL before the change. Keep existing authorized senders while both routes are in use. | | Treating optional SPF changes as guaranteed delivery | A policy without hard fail still may not produce SPF pass. Follow the [SPF audit guidance](/outbound/migration-center/prepare-customer-dns) and verify DMARC alignment before deferring changes. | | Publishing duplicate SPF records or exceeding lookup limits | Edit the existing SPF record, put the MailChannels include before `all`, and validate the complete include chain. See [SPF setup](/outbound/spf-records). | | Missing or inconsistent sender IDs | Verify attribution for local scripts as well as authenticated users. Preserve stable identities when you move a customer between servers. | | Losing DKIM signing on the new transport | Verify signing on the relay path. Generate `Message-ID` before signing and investigate any [DKIM failure caused by a missing Message-ID](/outbound/dkim-failure-message-id). | | Overlooking forwarded mail | Configure and test [SRS on every forwarding MTA](#configure-srs-for-forwarded-mail), including non-cPanel setups. Verify SPF for the rewritten envelope domain and test bounce handling. | | Combining plugin and manual routing rules | Choose the supported configuration method for your platform. Check for duplicate routers, unexpected exclusions, and bypassed customer sending limits. | | Assuming every rejection is a migration defect | Inspect the SMTP response and sender history. Follow [false-positive reporting](/outbound/report-false-positives) or [sender remediation](/outbound/unblock-senders) as appropriate. | | Repeating messages such as "Testing 1 2 3" | Repetitive test messages are likely to be classified as spam and blocked. Use real mail from a domain you control, with a natural cadence and little impact if delivery fails. Agree on load-test parameters with support. | ## Roll out in phases Choose groups you can route and roll back independently, such as a server pool or a set of sending domains if your MTA supports that selection. Confirm whether a rule matches the sender domain or the recipient domain before relying on it to select customers. Keep each customer's route stable during an observation window so you can interpret the results. The following sequence is a starting point. Adjust group sizes to your traffic volume, customer mix, and support capacity. | Phase | Scope | Advance when | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1. Dedicated test environment | Domains you control sending real mail from workloads such as noncritical cron reports. | The applicable test matrix passes, logs are available, and you have rehearsed rollback. | | 2. Internal production pilot | A company subdomain or small set of internal accounts sending noncritical notifications, with a higher tolerance for failure. | Real application traffic meets the acceptance criteria through a normal sending cycle, including busy hours and scheduled jobs, without exposing customers to test failures. | | 3. Customer pilot | A small, agreed group covering different sending sources and DNS owners. | Customer DNS is verified, attribution and authentication are correct, and support has resolved unexpected delivery issues. | | 4. Staged expansion | Progressively larger groups, adding new configurations deliberately. | Each group remains within its agreed queue, delivery, and error thresholds before you add the next. | | 5. Completion | Remaining customers whose readiness checks pass. | Queues and support volume are stable, outstanding exceptions have owners, and the previous route can be retired safely. | For a daily sending pattern, an initial observation window of 24–48 hours can be useful. Extend it to cover weekly jobs, peak periods, low-volume customers, or unresolved issues. This is a planning example, not a MailChannels activation or warm-up requirement. Advance based on evidence, not elapsed time alone. Before each phase, confirm the customer list, DNS readiness, routing change, operator, observation window, and rollback decision-maker. Tell affected customers when the change will happen and how to report a problem. Keep customers with unresolved prerequisites on their existing route. ### Decide whether to advance or pause Review these checks for each group, rather than only for the account as a whole: * All intended sending paths use the correct route and retain usable sender attribution. * Authentication results match the agreed configuration, including aligned DKIM where needed. * Queue age and depth return to their expected range after normal bursts. * Deferral, rejection, and delivery-delay rates stay within the limits you set against the baseline. * Controlled recipient tests arrive as expected, and unexpected customer reports have been investigated. * Support can trace a message and the rollback route remains available. Pause expansion for unexplained authentication failures, missing sender identities, persistent queue growth, routing loops, duplicate delivery, or a material rise in legitimate-mail failures. Investigate a change concentrated at one recipient provider even if aggregate delivery looks healthy. ## Prepare and rehearse rollback Save the previous MTA routing configuration and confirm that the previous delivery service remains usable during the rollout. Retain the DNS authorization and credentials needed for both paths until you have completed the observation period and accounted for outstanding mail. If a group needs rollback: 1. Stop adding customers and record the affected group, change time, and symptoms. 2. Determine which messages remain in your local queue and which MailChannels has already accepted. Preserve logs and queue state. 3. Restore the previous route for that group. Confirm its authentication and connectivity before releasing locally queued mail at a controlled rate. 4. Track mail already accepted by MailChannels through Log Search. Avoid manually resubmitting accepted messages through the old route, which can cause duplicates. Investigate ambiguous timeout outcomes before replaying messages. 5. Repeat the delivery checks on the restored route and notify affected customers of the outcome. Keep abuse controls active during rollback. A spam or sender-block rejection should trigger investigation and remediation, rather than automatic delivery through an unfiltered fallback. After the migration is stable, retire the previous route only when its queues are clear and it is no longer needed for rollback. Remove obsolete DNS authorizations without removing other services your customers still use. ## Coordinate with MailChannels support For a migration review, share your MTA and control panel versions, sending-source inventory, expected daily and peak volume, test-account arrangement, DNS audit results, and proposed rollout windows. Include your acceptance and rollback criteria so support can review the plan in context. When reporting a test failure, provide the UTC timestamp, Message-ID, sender and recipient, sender ID, full SMTP response, relevant headers, and affected server or group. Use the [false-positive reporting guide](/outbound/report-false-positives) when a legitimate message is blocked. Exclude SMTP passwords and other credentials from diagnostic material.