If you are using Manuscript On Demand, do the first three steps below, then contact us.  The rest of this guide is meant for Manuscript On Site.

Troubleshooting Email Notifications (all versions of Manuscript)

You can use Manuscript to send email manually, and Manuscript will also send automatic email notifications when a bug is created or modified. This article will tell you how to troubleshoot this process in case email is not successfully being sent.

Specific to notification problems

  1. Make sure you’re assigning the case to someone other than yourself. If you assign a case to yourself you won’t receive a notification. Look in the bottom-left corner of the screen to see who you’re logged on as.
  2. Make sure the missing notification is not for a new email sent into Manuscript from your email address. Manuscript will not notify you of a case assigned to you if you were the correspondent who emailed into Manuscript. Since you sent the email, Manuscript assumes you don’t need to know about the corresponding change to the case.
  3. Check that the assignee has email notifications turned on. Make sure the email notification frequency is set to either “Periodic” or “Instant”.

Any spam filters?

Check that you don’t have any spam filter programs on the recipient end that are trapping messages delivered by Manuscript. If you’re only testing with email addresses at your company, try sending to an address at Gmail or Yahoo etc.

(On Demand only) Have you verified your account?

If you haven’t added a credit card to your Manuscript On Demand account (even for free trials and accounts on free plans), the number of emails you can send per day will be extremely limited. You can add a credit card (which will not be charged on free plans) to verify your account.


Further troubleshooting in Manuscript On Site

Is the FogBugz Heartbeat Pinger running?

Check the services control panel or your processes listing to make sure the FogBugz Heartbeat Pinger service is running.  If it’s running, restart it. If you have mail piled up in your MailQueue table in your database, it could be because this service just isn’t running.

It connects to the “Manuscript URL” set in the site settings and hits heartbeat.asp.  This URL may no longer be set correctly because you moved the machine or changed its name.  For example, if your site settings say your Manuscript URL is http://manuscript.yoursite.com, then the Heartbeat Pinger will connect to http://manuscript.yoursite.com/heartbeat.asp.  Double check that this URL is correct on your Site Settings page and then make sure you hit OK to have Manuscript save that info (even if it looks correct already — Manuscript may need to rewrite this to the registry and hitting OK will do this).  You can access that URL manually and refresh a few times to see if that sends a few messages.  If it returns “+”, that means there are things left for the heartbeat to take care of.  If it returns “-“, that means there is nothing left for the service to do.

Any antivirus or firewall programs interfering?

Check to see if you have Norton or McAfee or another antivirus or firewall or “Internet security” program running. These programs have email scanning features which will simply kill your emails from Manuscript. (This is true even if you have Manuscript set to simply use the default SMTP server in IIS.) Disable any such email scanning features.

For example, in McAfee VirusScan it’s called On-Delivery E-mail Scanner:

One place you might want to look in McAfee is the Access Protection section. You will need to make sure this does not contain a policy preventing the sending of email, e.g. “Prevent mass mailing works from sending mail”. These policies are intended to prevent spam from being sent, but you will need to make sure they do not prevent non-spam from being sent! Add FogBugzMaint.exe and DLLHOST.exe (a Windows process) to the “Excluded Processes” list.

Is the SMTP server set correctly within Manuscript?

  1. Log on as an administrator.
  2. Navigate to Avatar iconSite ConfigurationMail.
  3. Check the value for SMTP Server
  4. This should contain the Internet address of a standard mail server that is configured to accept mail from the Manuscript server.
  5. If your SMTP server uses SSL, make sure it is setup correctly according to this guide

Note: Manuscript On Site does not provide its own SMTP server for delivering email. You can use any SMTP server that is set up for delivering email inside your company. If you do not already have one, Windows Internet Information Services (IIS) which is required for Manuscript has a built in SMTP server which you can turn on. Configuring and administering email servers is beyond the scope of this article.

Is relaying set correctly on the SMTP server?

If email sending only fails when you send to a domain that is not your domain, then relaying is probably not allowed on your SMTP server. This is often done as a security precaution so that spammers don’t use your SMTP server to send out a million spam without you knowing.

Instructions for setting relaying in the IIS SMTP server: In the properties dialogue for the Default SMTP Server in IIS, go to the Access tab and click Relay. Make sure “Only the list below” is selected and make sure that the IP of your server appears in that list, i.e. that your web server (and Manuscript) is granted access to this SMTP server.

Check that the SMTP server can be reached

  1. From the computer where Manuscript is running, open a command prompt (choose Start, Run, type cmd, and click OK).
  2. Type ping followed by a space and the name of the SMTP server.
  3. If this works correctly, you will quickly see four lines that start with Reply from…
  4. If you see the message Unknown host, the SMTP server which you specified cannot be found. This could be because:
    • you typed the name incorrectly
    • the Manuscript computer does not have a reliable connection to a DNS (Internet domain name) server
    • the name is not listed with a DNS server.
  5. If you see the message Request timed out, the SMTP server which you specified cannot be reached. This could be because:
    • the SMTP server is off
    • the SMTP server refuses connections from the Manuscript server
    • there is no network route from the Manuscript server to the SMTP server.

Check that the Manuscript server is reverse-DNSable

Most SMTP servers will try to reverse lookup the IP address of the Manuscript server when the Manuscript server connects to send email. Using DNS, they will try to lookup the numeric IP address of Manuscript (such as 192.168.0.1) to a name (such as ManuscriptMachine.example.com). If this fails or takes too long, mail delivery will be impaired.

  1. From the computer where your SMTP server is running, open a command prompt.
    • If this is a Unix host, simply log on.
    • If this is a NT machine, choose Start, Run, type cmd, and click OK.
  2. Using the numeric IP address of the Manuscript machine, type nslookup 1.2.3.4. This is asking the name resolution system to find out what computer has that numeric IP address.
  3. If you see the domain name of your Manuscript machine on the Name line, everything is OK. However, if you see an error message like “Non-existent host/domain,” your Manuscript server is not reverse-DNSable. Contact the person who administers DNS on your network and make sure there is a reverse mapping for the Manuscript machine. (This is sometimes called “the in-addr.arpa” address.)
  4. Many SMTP servers will not accept mail from machines that are not reverse-DNSable.
  5. If the nslookup command takes more than a second to execute and then fails, it is likely that there is a connectivity problem between the SMTP machine and the DNS server such as a firewall. This will cause a delay every time you try to send mail with Manuscript. If you are experiencing 30 second – 1 minute delays every time you assign a case in Manuscript, this is probably the cause.

Check that you are not blocking ident traffic

Some mail servers will attempt to connect to the ident port (113) of the mail sender to see who the mail is coming from. (More info) If the mail server is outside a firewall and the Manuscript server is inside a firewall, the mail server attempts to connect to port 113 on the Manuscript computer. If these packets are dropped by the firewall, the mail server will stall for a minute or so before it can deliver the mail.

Check that the SMTP server accepts email

Follow these steps to simulate what Manuscript does when it tries to send mail. If you see an error at any point, it will likely give you some clues as to what’s wrong with the SMTP server.

Secure SMTP (SSL)

If your SMTP server is using SSL, see this guide to debug.

Normal SMTP

  1. From the computer where Manuscript is running, open a command prompt (choose Start, Run, type cmd, and click OK).
  2. Type (replace 25 with your SMTP server’s port number if it is non-standard)telnet YourSmtpServer 25
    • If you get a message saying that the command is not found, you’re likely on Windows 7, which removed telnet from the default installation. You can search Google for “enable telnet windows 7” to get several options to re-enable.
    • If you get a message that says something like Connect Failed, the SMTP server in question is not accepting any connections. This may be because:
      • the SMTP server is not running
      • the SMTP server is configured to reject email connections from the Manuscript machine
    • If all is well, you will see a message that starts with the number 220 followed by a greeting.
  3. Type HELO YourSmtpServer
    • You should see a message starting with the number 250 followed by something glib like “pleased to meet you”
  4. Using the email address configured as “Notification Return Address” in the Manuscript Site configuration screen, type MAIL FROM:youremail@example.com
    • You should see a message starting with the number 250 followed by something like Sender ok.
  5. Using the email address you want to send a notification to, typeRCPT TO:destemail@example.com
    • You should see a message starting with the number 250 followed by something like Recipient okIf you see a message that says something like “Relay Access Denied” this means that the SMTP server is configured to refuse any email that is not intended for its own domain. For example if you are sending mail to joe@example.com using an SMTP server at mycompany.com and you see a message about relaying denied, this SMTP server probably thinks you are a spammer. You will need to find an SMTP server that is configured to accept email from the Manuscript machine to its recipients.
  6. Type DATA
    • You should see a message starting with the number 354 followed by instructions to enter the email message.
  7. Type
    Test message
    .

    Note that the last line contains a period (dot) alone. This signals that you are done typing the message.

    • You should see a message starting with the number 250 followed by something like Message Accepted for Delivery.
  8. Type QUIT
    • Check that the email was received. If it was not received even though the message was accepted for delivery, there is something wrong with the SMTP mail server.

Still stuck?

This solves the issue in the vast majority of cases. If you need further help, contact us at http://contact.fogcreek.com