We're experiencing difficulty. Our engineers are on it. Please check status.mailgun.com for real-time updates.

FAQ: The Coming Domains API Change To Remove The SMTP Password On November 1, 2021

Table Of Contents
Quick Overview
FAQs
    How does this change impact me?
    Will this change impact my Mailgun account?
    Will this change impact any emails I send through Mailgun?
    Will this change impact the application I have integrated with Mailgun?
    I'm not sure if my applications use the Domains API for this purpose. How would I find out?
    What exactly is the change? Can you show me a "before and after"?
    Can you provide more details about why you're doing this?
    Great, but what do I need to do?
    Before November 1, 2021, how can I see my current SMTP password?
    After November 1, 2021, how can I see my current SMTP password?
    I reset my password, but it's too long for my application. Can I shorten or customize my password?
    Can you do this* for me? (*customize my password, show which password I'm using, fix my application)
Got Questions?

Quick Overview

Beginning on November 1, 2021, Mailgun's Domains API will no longer display the password value inside the smtp_password field, which is present in two API calls:

  • GET /domains
  • GET /domains/<domain>

As such, the SMTP password returned in those calls to the postmaster@ address for each of your domains will no longer be visible in plain text since the value will be hashed. 

At Mailgun, we are serious about security! As such, this change is part of our continual efforts to uphold the highest security standards possible to protect our customers. The rest of this article consists of a FAQ to address any questions and concerns you may have about what this change means for you.

FAQs

How does this change impact me?

If - and only if - you have any applications that use the Domains API to view the SMTP passwords of your Mailgun SMTP credentials, this functionality will no longer be possible starting on November 1, 2021.

Note: the Mailgun WordPress plugin is not impacted by this upcoming change.

 

Will this change impact my Mailgun account?

Nope!  SMTP passwords are not used for account management purposes. Your account will not be disabled suddenly or login restricted as a result of this release.

Note: the Mailgun WordPress plugin is not impacted by this upcoming change.

 

Will this change impact any emails I send through Mailgun?

That's also a nope!  The passwords currently configured and stored within Mailgun are not changing as a result of this release. Mailgun will not be changing the value of your SMTP passwords.

Note: the Mailgun WordPress plugin is not impacted by this upcoming change.

 

Will this change impact the application I have integrated with Mailgun?

The short answer: maybe, but most likely not.

As mentioned earlier in the article, this release is narrowly focused on the information that is returned when making two specific API requests to the Domains API.  If your applications do not make these API calls, there will be no impact; however, if your applications do make these calls, how your application is using the provided data - particularly the smtp_password field - there is the potential for impact.

If impacted, specifically how errors reveal themselves will vary application-by-application.  Depending on how your application is processing the resultant data from these requests, possibilities include the presence of error messages or blank pages/windows in parts of your application.  Typically, if programs encounter data errors, you will see 500-599 errors on the screen or within troubleshooting logs, and sections of pages, dashboards, or control panels will fail to render.

While we are not able to see your application, and thus, understand everything that it may be doing, the exercise below will guide you in evaluating the potential impact.

First, do any of your applications make those calls to the Mailgun Domains API?

  • If unsure, please first review the below question, "I'm not sure if my applications use the Domains API for this purpose. How would I find out?"
  • If no, there will be no impact.
  • If yes, let's ask another question.

Second, do those API requests - along with any subsequent code/logic in your applications capturing the responses - utilize the smtp_password field for any further processing?

  • If unsure, this will need to be investigated further and confirmed definitively by the technical resource(s) who assisted in integrating Mailgun into your application.
  • If no, there is a high likelihood of no impact.
  • If yes, there is a high likelihood of impact.

While our team cannot specify the exact configuration or coding changes that any given application may need, we can highlight that the key task will be to adjust any code that depends upon the smtp_password field for any of the application's functionality.  

Note: the Mailgun WordPress plugin is not impacted by this upcoming change.

 

I'm not sure if my applications use the Domains API for this purpose. How would I find out?

The best source to confirm this information will be the person(s) who integrated Mailgun into your sending applications.  This could be a consultant, a developer, your IT team, or a service provider (such as a CRM platform or a server host).

Note: the Mailgun WordPress plugin is not impacted by this upcoming change.

 

What exactly is the change? Can you show me a "before and after"?

The functionality of these two endpoints of the Domains API is changing how data in the smtp_password field is presented in the API response:

  • GET /domains
  • GET /domains/<domain>

The smtp_password field in the API response will contain an empty value rather than the plain text value of the SMTP password.  Therefore, if your sending applications have relied on calling these endpoints to obtain or check the SMTP passwords of your Mailgun SMTP credentials, this will no longer be possible starting November 1, 2021.

Therefore, we strongly recommend securely storing all of the currently configured SMTP passwords, ideally through the use of a robust password management application.

This is what the API response looks like now when sending requests to the two endpoints:

{
            "created_at": "Wed, 16 Jun 2021 22:47:38 GMT",
            "id": "************************",
            "is_disabled": false,
            "name": "sample.mailgun.com",
            "require_tls": false,
            "skip_verification": false,
            "smtp_login": "postmaster@sample.mailgun.com",
           "smtp_password": "supersecretpassword",
            "spam_action": "disabled",
            "state": "unverified",
            "type": "custom",
            "web_prefix": "email",
            "web_scheme": "http",
            "wildcard": false
        },

This is what the API response will look like on November 1, 2021, when sending requests to the two endpoints:

{
            "created_at": "Wed, 16 Jun 2021 22:47:38 GMT",
            "id": "************************",
            "is_disabled": false,
            "name": "sample.mailgun.com",
            "require_tls": false,
            "skip_verification": false,
            "smtp_login": "postmaster@sample.mailgun.com",
            "smtp_password": "",
            "spam_action": "disabled",
            "state": "unverified",
            "type": "custom",
            "web_prefix": "email",
            "web_scheme": "http",
            "wildcard": false
        },

As seen when comparing the two examples, the former displays the smtp_password field as a string containing the plain text password while the latter displays the smtp_password field as an empty string.

 

Can you provide more details about why you're doing this?

As a security best practice, we are moving towards hashing SMTP passwords, just as we do with all other passwords on our platform. Due to this new standard, we will be unable to show the passwords in plain text (and thus, in the smtp_password field) once they are hashed and stored in our secure database.

 

Great, but what do I need to do?

Concisely: ensure that your passwords are known and securely stored. Then, if applicable, update your applications to no longer utilize the plain text SMTP password returned in the two API calls.

The very first task is to identify and then securely store the SMTP passwords of all SMTP credentials that exist on your Mailgun domain(s).  Beginning on November 1, 2021, there will be no method available to view your currently configured SMTP passwords.  Additionally, you may wish to cross-reference the password values as stored in Mailgun with the values stored in your sending applications or password managers. If your applications mask the password, you may want to re-enter the Mailgun password into your sending application.  In short, after securely storing your SMTP password, you will need to update any reliant systems

The second task is to complete the guided evaluation found above in question, "Will this change impact the application I have integrated with Mailgun?"  If the impact is determined to be likely due to the applications expecting the plain text password to be present in the smtp_password field, then the application will need to be updated to no longer rely on that password in order to function correctly.  As such, it will be imperative to ensure your technical resource(s) update the applications prior to November 1, 2021.

 

Before November 1, 2021, how can I see my current SMTP password?

While it's not possible to view the current SMTP password within the Mailgun Control Panel, it is possible by using the Domains API and these two endpoints:

  • GET /domains
  • GET /domains/<domain>

However, the only passwords that are visible with this method are the postmaster@ passwords for your domains.  The passwords of any other SMTP credentials that you have created are not visible through any means.

For example, the below HTTP GET request to the Domains API will retrieve the SMTP password for all your domains within the specified region (US or EU):

# for all domains in the US region
curl -s --user 'api:YOUR_API_KEY' -G \
https://api.mailgun.net/v3/domains

# for all domains in the EU region
curl -s --user 'api:YOUR_API_KEY' -G \
https://api.eu.mailgun.net/v3/domains

This example (available in multiple programming languages) can be found in our API documentation (the 1st example).

Alternatively, to view the SMTP password for a single domain, a different HTTP GET request will be needed:

# if the domain resides in the US region
curl -s --user 'api:YOUR_API_KEY' -G \
https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME

# if the domain resides in the EU region
curl -s --user 'api:YOUR_API_KEY' -G \
https://api.eu.mailgun.net/v3/domains/YOUR_DOMAIN_NAME

The above is the 2nd example in the aforementioned API documentation.

 

After November 1, 2021, how can I see my current SMTP password?

There will no longer be a way to see any current SMTP passwords as they will be hashed.  The only time that you will be able to see an SMTP password is immediately after resetting it. A dark-gray notification window will appear in the bottom-right portion of the Control Panel allowing you to copy-and-paste the password into your application and password manager.

For step-by-step guidance in resetting the SMTP password, please reference the "SMTP Credentials" section in this article.

Note: Only users with "Admin" privileges within your Mailgun account will have access to reset SMTP passwords.  For more information concerning user roles, please see this article.

 

I reset my password, but it's too long for my application. Can I shorten or customize my password?

While it's not possible to shorten or customize the SMTP password within the Mailgun Control Panel, it is possible by using the Domains API.  For example, the below HTTP POST request to the Domains API creates a new pair of SMTP credentials (customized password included): 

# if the domain and its credentials reside in the US region
curl -s --user 'api:YOUR_API_KEY' \
 https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/credentials \
 -F login='alice@YOUR_DOMAIN_NAME' \
  -F password='supasecret'

# if the domain and its credentials reside in the EU region
curl -s --user 'api:YOUR_API_KEY' \
https://api.eu.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/credentials \
 -F login='alice@YOUR_DOMAIN_NAME' \
-F password='supasecret'

This example (available in multiple programming languages) can be found in our API documentation (the 6th example).

But what if you wish to update an existing pair of SMTP credentials rather than create a new pair of SMTP credentials? To update an existing pair of SMTP credentials with a new customized password, an HTTP PUT request will be needed:

# if the domain and its credentials reside in the US region
curl -s --user 'api:YOUR_API_KEY' -X PUT \
https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/credentials/alice \
-F password='abc123'

# if the domain and its credentials reside in the EU region
curl -s --user 'api:YOUR_API_KEY' -X PUT \
https://api.eu.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/credentials/alice \
-F password='abc123'

The above is the 7th example in the aforementioned API documentation.

If Mailgun considers the password too short, you'll see this API response:

{
"message": "Password is too short."
}

And if Mailgun considers the password insecure, you'll see this API response:

{
"message": "Password is not secure."
}

The solution to either case is to increase the complexity of the password. For more about passwords and security, check out this blog post!

 

Can you do this* for me? (*customize my password, show which password I'm using, fix my application)

Unfortunately, it would not be in accordance with best security practices for Mailgun to retrieve the password and then communicate the password over our Support channels.  For this reason, we have included numerous sections in this article that describe the methods through which you may perform these actions. 

If you run into trouble using these methods to obtain or customize your password, it is critical to contact the person(s) who integrated Mailgun into your sending applications.  This could be a consultant, a developer, your IT team, or a service provider (such as a CRM platform or a server host).

Enlisting the assistance of your technical resource(s) is especially important for investigating and reconfiguring any impacted sending applications. While we cannot specify the exact configuration or coding changes that any given application may need, the key focus will be to adjust any code that depends upon the smtp_password field for any of the application's functionality.  

Got Questions?

Mailgun by Pathwire has answers! If you still have any concerns or questions, please send us a Support ticket through the Support page within your Mailgun Control Panel.  Our Support Team will be happy to assist! 

Powered by Zendesk