Configure SMTP Server
Note: This information applies to SwaggerHub On-Premise.
An SMTP server is required to send user invitations, email notifications and other outgoing mail from SwaggerHub. You will be asked to specify your SMTP server information during the initial setup of SwaggerHub. You can also change it at any time later in the SwaggerHub Admin Center.
If you are only trialling and need a temporary SMTP server, check out the examples below.
Considerations
The SMTP server must be directly reachable from your SwaggerHub On-Premise instance. A proxy is not used for SMTP connections.
SMTP settings
To view or change your SMTP server settings:
Open the Admin Center.
Select Settings > Notifications on the left.
Specify the following settings:
Option
Description
Notification email address
The "From" address of email notifications, for example,
[email protected]or[email protected]. Depending on the SMTP service you use, this may need to be a real address verified with the SMTP service provider. For example, Amazon SES requires that you verify the ownership of the From email address or the domain of this address.Notification email sender
The "From" name used in email notifications. For example, SwaggerHub.
SMTP Mail Host
The SMTP server used for outbound email from SwaggerHub. For example,
smtp.sendgrid.com.SMTP Mail Port
The SMTP server port. The typical port numbers are 465 for SSL, 587 for STARTTLS, and 25 for unencrypted (plain) connections.
SMTP Username and SMTP Password
The username and password used to access the SMTP server.
SMTP Protocol
The type of the connection to the SMTP server: PLAIN, SSL, TLS (STARTTLS). Please check with your SMTP provider.
Important
Make sure there are no spaces at the beginning or at the end of the values.
(Optional.) To test the connection to the SMTP server from your SwaggerHub On-Premise instance:
Scroll down to the Privacy section.
Under Proxy Server Test, enter
socket://SMTP_SERVER:PORTand click Test Proxy.If you get an error, double-check the server name and port, and make sure your firewall allows connections from the SwaggerHub On-Premise instance to the SMTP server.
Note
Despite the name, the "test proxy" button also works without a proxy. In this case, it tests a direct connection.
Click Send Test Email to make sure you have configured the notifications correctly. An email message will be sent to the admin email address you specified during the SwaggerHub On-Premise installation.
If you do not see the test email, check your junk folder. See also the troubleshooting tips below.
Click Save Changes and Restart.
In v. 1.19.1 or earlier, click Save Changes, then switch to the System page and click Restart SwaggerHub.
Wait a few minutes for the system to restart completely.
Amazon SES notes
To send email via Amazon SES, you must verify the ownership of your email addresses or domains with Amazon.
You must verify the "From" email address specified by the Notification email address option in SwaggerHub.
If your account is in the sandbox mode, you must also verify the email addresses of all existing and future SwaggerHub users, including the admin user. This is required to deliver invitations and other email to SwaggerHub users. Alternatively, you can ask Amazon to move your account out of the sandbox.
Amazon lets you verify individual email addresses and domains. For more information, see Verifying identities in Amazon SES.
Important
Email address verification is case-sensitive. Be sure to use the same letter case for the email addresses you specify in SES and in SwaggerHub.
Temporary SMTP examples
Gmail
To use Gmail as an outgoing server, you may need to configure your Gmail account:
If your Gmail account has 2-Step Verification enabled, you need to create an application-specific password for SwaggerHub here: https://myaccount.google.com/apppasswords. Use this password in SwaggerHub SMTP settings instead of the account password.
If you do not use 2-Step Verification for Gmail, you may need to lift restrictions on your account and enable access for “less secure apps” on this page: https://myaccount.google.com/lesssecureapps.
Use the following values for the SMTP settings in the SwaggerHub Admin Center:
Option | Value |
|---|---|
Notification email address | Your full @gmail.com address. |
Notification email sender | A name of your choice. |
SMTP Mail Host | smtp.gmail.com |
SMTP Mail Port | 587 (TLS) or 465 (SSL) |
SMTP Username | Your full @gmail.com address. |
SMTP Password | Your Gmail account password. |
SMTP Protocol | TLS if port 587 is used, or SSL if port 465 is used. |
Yahoo
You may need to lift restrictions on your Yahoo account. To do this:
Log in to Yahoo.
Click on your account picture, then on Account Info.
Under Account Security, select Allow apps that use less secure sign in.
Use the following values for the SMTP settings in the SwaggerHub Admin Center:
Option | Value |
|---|---|
Notification email address | Your full @yahoo.com address. |
Notification email sender | A name of your choice. |
SMTP Mail Host | smtp.mail.yahoo.com |
SMTP Mail Port | 587 (TLS) or 465 (SSL) |
SMTP Username | Your full @yahoo.com address. |
SMTP Password | Your Yahoo account password. |
SMTP Protocol | TLS if port 587 is used, or SSL if port 465 is used. |
Outlook, Hotmail or MSN
Option | Value |
|---|---|
Notification email address | Your full email address. |
Notification email sender | A name of your choice. |
SMTP Mail Host | smtp-mail.outlook.com |
SMTP Mail Port | 587 |
SMTP Username | Your full email address. |
SMTP Password | Your account password. |
SMTP Protocol | TLS |
SendGrid
To use SendGrid as an outgoing mail server, do the following:
Go to SendGrid: https://sendgrid.com/pricing/.
Click Start for free. This will give you an account that can send 100 emails per day.
Fill out the necessary details and create your account.
Once logged in, click your name, then click Setup Guide.
Under Integrate using our Web API or SMTP relay, click Start.
Choose SMTP Relay.
Enter a name for the API key, and click Create Key.
Note down the generated key. You will not be able to see it again.
Use the following values for the SMTP settings in the SwaggerHub Admin Center:
Option | Value |
|---|---|
Notification email address | An email address of your choice. Do not use a secured domain, as mail will likely be flagged as phishing. |
Notification email sender | A name of your choice. |
SMTP Mail Host | smtp.sendgrid.net |
SMTP Mail Port | 465 |
SMTP Username |
|
SMTP Password | The SendGrid key that you generated earlier. |
SMTP Protocol | SSL |
Troubleshooting
If you do not receive emails from SwaggerHub On-Premise:
Check the junk folder.
Make sure your SwaggerHub On-Premise instance can connect to your SMTP server directly (without a proxy).
Make sure your mail server does not block SMTP traffic from SwaggerHub On-Premise.
Make sure the SMTP settings are correct. Use the Send Test Email button to test the email functionality.
Note
Test emails are sent to the email address of the admin user, so make sure this address is correct. You can see the admin email address on the License page in the Admin Center. If you need to change the admin email address, contact SmartBear support.
Try using a real existing email address as the Notification email address. Some SMTP services require a real "From" address verified with the SMTP service provider. Refer to the documentation of your SMTP service provider to learn if the "From" address must be verified.
Amazon SES users: see Troubleshoot Amazon SES and Amazon SES SMTP issues.
Check the system logs for SMTP errors. Examine the log named swaggerhub.json and search for
"thread": "mail-sender". You might see errors like this:"thread": "mail-sender", "level": "ERROR", "logger": "com.smartbear.email.client.EmailHandler", "message": "invalid configuration processing emails : javax.mail.AuthenticationFailedException: 535 Authentication Credentials Invalid\n",
The error messages can give you clues as to what is wrong.