On-Premises to Cloud Email Migration Guide

Bird

Jun 28, 2020

Email

1 min read

On-Premises to Cloud Email Migration Guide

Key Takeaways

    • Bird Cloud was built on the proven Momentum MTA engine, giving customers the performance of a mature on-prem system with the added advantages of a modern cloud email API platform.

    • Many legacy senders still rely on Momentum or PowerMTA, and Bird provides a clear migration path for both—full cloud migration or hybrid routing through on-prem nodes.

    • Migrating requires understanding whether you will:

      1. eliminate all on-prem infrastructure, or

      2. continue using your MTA for pre-processing, routing, or legacy constraints.

    • Bird only accepts authenticated SMTP injection over ports 587 or 2525 (TLS strongly recommended). REST API injection is also available for direct JSON-based delivery.

    • Option #1 (“cold turkey”) allows full decommissioning of MTAs by sending directly to Bird via SMTP or REST, removing complexity and modernizing sending architecture.

    • Option #2 supports hybrid environments—routing select streams from Momentum or PMTA to Bird by configuring outbound domains with SMTP_Auth to Bird.

    • PowerMTA and Momentum configurations can forward traffic to Bird securely using TLS, API-key-based SMTP_Auth, and route definitions.

    • Customers using advanced Lua scripts, inline substitution, or pre-delivery filtering may remain hybrid until logic is refactored into upstream systems.

    • Bird supports BYOIP (Bring Your Own IP) for customers with a contiguous /24 block, allowing you to retain warmed IP reputation and skip full IP warmup.

    • For non-BYOIP users, Bird provides automatic IP warmup, and recommends staged migration—starting with small volumes, then gradually increasing traffic.

    • Proper domain setup (DKIM, SPF, DMARC, bounce domains, tracking domains) is essential for alignment and smooth coexistence during migration.

    • Bird provides real-time event data via webhooks or Events API, enabling downstream automation, ETL flows, and log-style reconstruction if needed.

Q&A Highlights

  • What are the two main migration scenarios?

    Either fully decommission all on-prem MTAs (Option #1) or maintain a hybrid setup where some traffic is routed through Momentum/PMTA before reaching Bird (Option #2).

  • What determines whether you choose Option #1 or Option #2?

    Your reliance on Lua scripts, preprocessing logic, message rewrites, security requirements, or generators that cannot send authenticated traffic over port 587.

  • Does Bird accept SMTP injection over port 25?

    No—Bird requires SMTP injection via port 587 or 2525, authenticated with SMTP_Auth.

  • Is TLS required?

    Not strictly required, but strongly recommended for secure message injection from either generators or on-prem MTAs.

  • Can senders use the REST API instead of SMTP?

    Yes—senders can deliver JSON payloads via the Transmissions REST API, often simplifying workflows and removing the need to generate raw SMTP messages.

  • What is Bird’s BYOIP program?

    A process that allows customers with a contiguous /24 block to migrate their existing IPs into Bird, maintaining reputation and skipping warmup.

  • What if BYOIP is not an option?

    Use new sending domains (e.g., sp.yourdomain.com), run both environments in parallel, and rely on Bird’s automatic IP warmup.

  • How do you route only selected streams through Bird in a hybrid setup?

    By configuring outbound domains (Momentum) or rollup configs/VMTAs (PowerMTA) that authenticate and deliver to Bird’s SMTP endpoint.

  • What metadata changes are required when injecting via SMTP?

    Add an X-MSYS-API header containing attributes like ip_pool, campaign, and any custom metadata previously handled through X-Headers.

  • What should be configured in DNS before migration?

    DKIM records, SPF, DMARC, bounce domains, and tracking domains to ensure domain alignment and reduce deliverability risk during the transition.

  • How should traffic be migrated to Bird?

    Gradually: start with a small stream, then 10%, then 20%, increasing daily until all traffic has moved—similar to IP warming best practices.

  • How can senders collect delivery and engagement data after migrating?

    By using Bird’s real-time webhook system or the Events API; webhook collectors can be built quickly and feed downstream storage or ETL systems.

So many times, we hear the question, “Do you have a playbook of some kind that lays out the process for migrating from an on-premises installation to Bird”?

Why yes, yes we do. Keep reading.

First, some back story. The Bird Cloud service was created in 2014 out of the enormous success of the On-Premises Momentum MTA solution. Momentum sits at the core of the Bird Cloud, providing high-speed delivery and traffic shaping for thousands of customers on the cloud service. Because of this, Momentum receives a large portion of our engineering attention, but the results of that work are often buried in performance improvements that don’t get a great deal of press.  Momentum customers see the benefits of this work every time a new public release of Momentum is published.

This does NOT mean that Bird is just “Momentum in the Cloud”. MessageBird is much more than that and can have added benefits for customers who choose to migrate or use them in a hybrid approach. These benefits stem from our modern cloud-based email API architecture, which provides capabilities not available in traditional on-premises solutions. In addition, we have made it very easy for PowerMTA customers to migrate or use PowerMTA with Bird in a hybrid configuration as well. The rest of this document will describe in detail how you can migrate your message streams from Momentum or PowerMTA to the Bird Cloud service. 

There are really two separate scenarios to consider when migrating to Bird from Momentum or PowerMTA. 

  1. You are ready to leave the on-premises world entirely, shut down your physical data centers and no longer manage any on-premises MTA directly.  This means eliminating Momentum or PowerMTA from your deployment and sending messages directly to SparkPost for message handling. Before decommissioning your on-premises infrastructure, ensure you have comprehensive database backups of all critical systems, especially if you're running PostgreSQL databases that contain important historical data or configurations.

  2. You have reason to keep some on-premises footprint for one reason or another.  Some possibilities might be:

  • specific delivery streams that require pre-processing in Momentum

  • capacity splitting for burst or disaster recovery needs

  • supporting legacy customers in PMTA while shifting new customers to SparkPost

 …then you want to forward the other messages on to Bird for onward message handling.  

In either situation, you need to be aware that Bird will only accept SMTP messages for delivery that are injected over port 587 or 2525 and use SMTP_Auth with a specific username and password (See SMTP docs here). We also highly recommend connecting with a TLS connection, but that is not strictly required. If you are replacing your MTA layer entirely (scenario 1), then you may also want to consider using the Transmissions REST API which can accept messages over HTTPS connections. Documentation on that API is here.

For organizations maintaining on-premises infrastructure that requires secure email capabilities, our S/MIME implementation guide for PowerMTA and Momentum provides detailed setup instructions for encrypted email delivery.

Which option do I choose?

To figure out if you are in option #1 or option #2, consider these factors:

  • Do you use Momentum’s Lua scripting engine for anything more complicated than message routing?

    • Lua is a comprehensive script tool for manipulating messages in-line, but the vast majority of our users only use it to select a binding for delivery.  If that is the case, you can modify your generation code to add an ip_pool attribute to the X-MSYS-API header and have Bird assign the route for you. 

    • If you use Lua to do more complicated things like body filtering, Mail_From rewrites, or message cadence calculations, and it’s not feasible to move that logic into your injecting application, you may want to consider switching to the Option #2 camp.

  • Is your generation system able to send messages over port 587 using TLS and SMTP_Auth?

    • Some campaign management systems can only push mail out on port 25 in cleartext. This causes a security problem for Bird so you may want to consider Option #2

  • Are you using PowerMTA substitution syntax or other in-line message modification?

    • If you can move this function up into your generators or use the Bird Template Language, then you can still use option 1, but otherwise, you may need to think about keeping a PMTA node online for this message modification before shipping to Bird for delivery.

  • Do you require any inbound AV/AS scanning before injection? While this is possible in Momentum and PowerMTA, eBird assumes you have already performed all those checks.  You may want to consider doing that before injection.

No matter which way you go, it is sure to affect your commercial relationship.  As you can imagine, this is not our first rodeo. Be sure to loop in your Commercial Account Manager and Customer Success Manager so we can help you through the details and make sure you are getting the best value for your dollar.

For Option #1 Camp (Going “cold turkey”):

Let’s assume you are OK with option 1 and you are ready to shut down your on-premises MTAs and you have decided to continue using the SMTP injection method, not changing your message creation systems at all.  Your generation systems should create a fully formatted SMTP message, then push to Bird over TLS using SMTP_AUTH where the username and password are as described on this page. Remember that the “password” is the API key you generate in your Bird account with the SMTP delivery option turned on.

If you are in the Option #1 camp, consider switching to the REST API right out of your generation system. In most cases, we find that customers’ processing systems are already using JSON over HTTP and have to convert to SMTP before injection. You can skip that step and send it directly to us as a JSON formatted REST payload.

If you choose to inject with the REST API, you may need to alter your content creation system a bit, but it may be worth it.  You can find out more here.

One of the biggest concerns large ESPs have with a Migration is IP Warming. Typically they have spent many years grooming their inventory of IP addresses with great care so the thought of abandoning all that work is painful. Bird has worked out a Bring Your Own IP (BYOIP) process that takes care of that issue. If you have at least one contiguous /24 CIDR block, Bird can use those existing IPs for delivery which saves you the pain of having to warm them up again. If you are able to take advantage of that option, you can skip the section here on IP warmup.

If you feel you are ready to go here, skip ahead to “Making it happen”

Let’s assume you are OK with option 1 and you are ready to shut down your on-premises MTAs and you have decided to continue using the SMTP injection method, not changing your message creation systems at all.  Your generation systems should create a fully formatted SMTP message, then push to Bird over TLS using SMTP_AUTH where the username and password are as described on this page. Remember that the “password” is the API key you generate in your Bird account with the SMTP delivery option turned on.

If you are in the Option #1 camp, consider switching to the REST API right out of your generation system. In most cases, we find that customers’ processing systems are already using JSON over HTTP and have to convert to SMTP before injection. You can skip that step and send it directly to us as a JSON formatted REST payload.

If you choose to inject with the REST API, you may need to alter your content creation system a bit, but it may be worth it.  You can find out more here.

One of the biggest concerns large ESPs have with a Migration is IP Warming. Typically they have spent many years grooming their inventory of IP addresses with great care so the thought of abandoning all that work is painful. Bird has worked out a Bring Your Own IP (BYOIP) process that takes care of that issue. If you have at least one contiguous /24 CIDR block, Bird can use those existing IPs for delivery which saves you the pain of having to warm them up again. If you are able to take advantage of that option, you can skip the section here on IP warmup.

If you feel you are ready to go here, skip ahead to “Making it happen”

Let’s assume you are OK with option 1 and you are ready to shut down your on-premises MTAs and you have decided to continue using the SMTP injection method, not changing your message creation systems at all.  Your generation systems should create a fully formatted SMTP message, then push to Bird over TLS using SMTP_AUTH where the username and password are as described on this page. Remember that the “password” is the API key you generate in your Bird account with the SMTP delivery option turned on.

If you are in the Option #1 camp, consider switching to the REST API right out of your generation system. In most cases, we find that customers’ processing systems are already using JSON over HTTP and have to convert to SMTP before injection. You can skip that step and send it directly to us as a JSON formatted REST payload.

If you choose to inject with the REST API, you may need to alter your content creation system a bit, but it may be worth it.  You can find out more here.

One of the biggest concerns large ESPs have with a Migration is IP Warming. Typically they have spent many years grooming their inventory of IP addresses with great care so the thought of abandoning all that work is painful. Bird has worked out a Bring Your Own IP (BYOIP) process that takes care of that issue. If you have at least one contiguous /24 CIDR block, Bird can use those existing IPs for delivery which saves you the pain of having to warm them up again. If you are able to take advantage of that option, you can skip the section here on IP warmup.

If you feel you are ready to go here, skip ahead to “Making it happen”

Leveraging Option #2 (on-prem pre-processing):

If, however, you are on team Option #2, then you will want to add some configuration changes to your deployment. The least painful way to migrate some select message streams from Momentum or PMTA to Bird while still using SMTP injection from your generation systems is to add a special route in your config.

For Momentum:

  1. Set up a version of Momentum > 3.6.23. 

  2. Install a valid SSL Certificate and open outbound port 587 so Momentum can talk to Bird Configure an outbound domain so you can route a message through Momentum to Bird. 

  3. With the configuration below, any message hitting this configuration will be routed to smtp.sparkpostmail.com using port 587 and SMTP_Auth with the username and password defined there.

    outbound_smtp_auth { }
Keep_Message_Dicts_In_Memory = true
Domain "smtp.sparkpostmail.com" {
  Remote_SMTP_Port = "587"
  Outbound_SMTP_AUTH_Type = "LOGIN"
  Outbound_SMTP_AUTH_user = "SMTP_Injection"
  Outbound_SMTP_AUTH_pass = "17258redacted8bd6cd7a8redacted8c22bce"
}

  4. Configure the bindings you want to relay through MessageBird with TLS and gateway them to the domain you defined above.

    Note:     TLS is not strictly required but is a strong recommendation. If TLS is not possible for some reason, then IP whitelisting the API keys is also a strong recommendation.

    binding "CustomerA-Outbound" {
  Gateway = "smtp-demo.sparkpostelite.com"
  TLS = "required"
  TLS_Certificate = "/etc/pki/tls/certs/trymsys.net.crt"
  TLS_Key = "/etc/pki/tls/certs/trymsys.net.key"
  TLS_Ciphers = "DEFAULT"
}

For PowerMTA:

  1. Set up a version of PowerMTA > 4.5.0

  2. Install a valid SSL Certificate and open outbound port 587 so PowerMTA can talk to Bird.

  3. Configure an outbound domain path so you can route a message through PowerMTA to Bird. With the configuration below, any message hitting this configuration will be routed to smtp.sparkpostmail.com using port 587 and SMTP_Auth with the username and password defined there.  In PowerMTA, this is also where you can set TLS. Note this is also documented more fully here 

<domain sparkpost.rollup>
  use-unencrypted-plain-auth yes
  auth-username SMTP_Injection
  auth-password YourAPIKeygoesherewhenyougenerateit
  route smtp.sparkpostmail.com:587
  use-starttls yes
  require-starttls yes
  max-smtp-out 10
</domain>

4. Configure the VMTAs you want to relay through Bird with the {sparkpost} rollup config you defined above.

<virtual-mta SparkPostRelay>
  <domain *>
    queue-to {sparkpost}
  </domain>
</virtual-mta>

Once you have those configuration changes made, any messages sent to the selected “binding” or “VMTA” should be routed automatically through Bird for delivery.  

Making it happen

When you start down this road, don’t make the mistake of thinking this is an overnight operation.  Doing this right will take some time and care.  

  1. Setup your Bird account and fully test using a development subaccount so you can filter out that traffic later.  You will need to do this for either option because you will need the API key for the SMTP_Auth password either way.

  2. If you are using SMTP injection, plan to add an X-MSYS-API header to incorporate all the metadata and message attributes needed.  Any X-Headers should be re-written as metadata and you should include the ip_pool and campaign attributes as well. A sample is available here

  3. If you are NOT using BYOIP, then you should make sure you set up slightly different sending domains for use with MessageBird so that you can run both environments in parallel for as long as it is needed.  If your current sending domain is mycompany.com, maybe set up sp.mycompany.com specifically for Bird delivery.  This allows you to migrate slowly and carefully while not compromising either domain.

  4. Make sure you have full domain alignment and security features enabled.  In DNS, set up DKIM, SPF, DMARC, bounce and tracking domains so they all look like they belong to the same organization.

  5. Configure Automatic IP Warmup on your defined IP_Pools.  If you are using the previously mentioned BYOIP option, you can ignore the warmup step.

  6. Start with one message stream and move forward from there.  Just like IP Warmup, you don’t want to do this all at once. Redirect a few hundred messages first, then 10% of the volume, then 20% the following day and increase until you have moved all the volume over. If you are an ESP, select a customer you can work with and test the process with their feedback.  If it all works well, move on to the next one. If you run into problems, take the time to fix it and work it into the process for the next one.

  7. Automate as much as possible with APIs.  Outside of the DNS changes, the SparkPost config can be mostly automated with a few API calls.

Data Collection from Bird

MessageBird reports message delivery in a webhooks feed or in the message events API.  Accessing Bird plain text logs is just not possible. You can pull this data back to your environment with a webhooks collector or by calling the Events API periodically and consuming the data.  We recommend using webhooks and have some recommendations on doing that right.  In its most basic form, a PHP webhook collector can be deployed in a few  lines of code:

<?php
$verb = $_SERVER['REQUEST_METHOD'];
if ($verb === "POST") {
    $jsonStr = file_get_contents("php://input");
    http_response_code(200);
    $rnum = rand(1000, 9999);
    $timestamp = date("YmdHis") . $rnum;
    $filePath = './data/data_' . $timestamp . '.txt';
    // Handle duplicate filenames (edge case)
    if (file_exists($filePath)) {
        $baseName = basename($filePath, ".txt");
        $seq = 0;
        $ftail = substr($baseName, -2, 1);
        if ($ftail === "-") {
            $seq = (int)

While you are experimenting, you can try them out with free collectors such as http://webhook.site/.

Once you have collected all the webhook data, you can read that into a data store for additional processing.  There are also ways to push Webhooks through services like StitchData and Segment.

The same information is available in the Events API if you have a need to PULL the data and cannot accept PUSH data.  Here is a sample Event API call:
GET https://api.sparkpost.com/api/v1/events/message?/

recipients=recipient@example.com&templates=my-template&events

That API is fully documented with samples here:  https://developers.sparkpost.com/api/events/#events-get-search-for-message-events

If you really need the event data back in a form that looks like PMTA or Momentum logging, that is possible as well if you employ some additional conditioning code. The great news is there are a few examples to steal from already.

Recap

Make sure you talk to your Sales and Success Management team.  We’ve done this before and can help you through it quickly and cost-effectively.

  1. Figure out if you are in Camp #1 (able to move entirely from On-Prem) or Camp #2 (Still need some on-prem MTA).

  2. Sign up for a free test account to evaluate the integration details.

  3. Decide on SMTP or REST API injection methods.

  4. If you are using SMTP injection, figure out how to get header data and message attributes into an X-MSYS-API header.

  5. Confirm if you can use our BYOIP process.

  6. Update your DNS with new domains if necessary.

  7. Build a small sample to test your migration.  You may need to adjust your config.

  8. Ramp up the volume until all the traffic is migrated

  9. If you fit into Camp #1, you can finally shut down your on-prem MTAs after all the traffic is migrated.

When planning DNS changes for high-volume email systems, be aware of potential AWS DNS scaling challenges that can affect email delivery performance at scale.

Other news

Read more from this category

A person is standing at a desk while typing on a laptop.

The complete AI-native platform that scales with your business.

Contact sales

Start for free

© 2025 Bird

Contact Support

A person is standing at a desk while typing on a laptop.

The complete AI-native platform that scales with your business.

Contact sales

Start for free

© 2025 Bird

Contact Support

A person is standing at a desk while typing on a laptop.

The complete AI-native platform that scales with your business.

Contact sales

Start for free

© 2025 Bird

Contact Support