Configuring SMTP Server

Last modified on May 06, 2021

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.

  • STARTTLS is not supported.

SMTP settings

To view or change your SMTP server settings:

  1. Open the Admin Center.

  2. Select Settings > Notifications on the left.

  3. Specify the following settings:

    Option Description
    Notification email address The "From" address of email notifications, for example, swaggerhub@YourCompany.com or no-reply@YourCompany.com. 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. For example, 465 or 587.
    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. Please check with your SMTP provider.
    Make sure there are no spaces at the beginning or at the end of the values.
  4. (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:PORT and 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.

      Testing outbound connection 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.
  5. 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.

  6. If you use SwaggerHub On-Premise 1.19.2 or later, click Save Changes and Restart.

    In earlier versions, click Save Changes, then switch to the System page and click Restart SwaggerHub.

  7. 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.

  1. You must verify the "From" email address specified by the Notification email address option in SwaggerHub.

  2. 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.

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:

  1. Log in to Yahoo.

  2. Click on your account picture, then on Account Info.

  3. 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:

  1. Go to SendGrid: https://sendgrid.com/pricing/.

  2. Click Try for Free. This will give you an account that can send 100 emails per day.

  3. Fill out the necessary details and create your account.

  4. Once logged in, click on your name, then on Setup Guide.

  5. Under Integrate using our Web API or SMTP relay, click Start.

  6. Choose SMTP Relay.

  7. Enter a name for the API key, and click Create Key.

  8. 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 apikey
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 Troubleshooting Amazon SES and Amazon SES SMTP Issues.

  • In SwaggerHub On-Premise 1.19.1 and later: 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.

See Also

Configuring SwaggerHub On-Premise

Highlight search results