Courier troubleshooting

Use this page when a Courier configuration doesn't send the emails you expect.

Troubleshooting email notifications

A triggered configuration runs when a Quickbase email notification sends a request to Courier. See Email notification setup for triggered configurations for how to set it up. If a triggered configuration doesn't send the emails you expect, work through these checks in order.

1. Check that the notification fires

Courier can only run when it receives the notification. To confirm the notification is going out, temporarily add your own email address to the notification's list of email addresses, next to qbcourier@courier.quickbasetools.com, and change a record the way your users would.

You don't receive a copy—the notification isn't firing. Check its Notify When settings and conditions against the change you made. Courier isn't involved yet.
You receive a copy—the notification is firing. Look at the copy you received and continue with the next check.

Remove your address from the notification when you're done.

2. Check the notification settings

Compare the notification with the values on the configuration's Finish tab (View Email Notification Settings):

The email address is exactly qbcourier@courier.quickbasetools.com.
The custom message includes configkey= with your configuration's key. A request without the key, or with a key that doesn't match, is not processed.
The configid= value matches the configuration you expect—for example, after you duplicated a configuration, the notification may still point to the original.
For the Multiple Record Version, the custom message line sits on its own line between %RepeatOn% and %RepeatOff%. In the copy you received, each record should appear on a separate line. If the lines run together, Courier can't tell the records apart and processes only one of them. Create a new email notification from the values on the Finish tab (rather than copying the existing one), and disable the old notification.

3. Check the configuration

Processing Mode is Trigger. On Demand and Scheduled configurations don't take a record ID—a request that includes recid= for one of them is not processed.
Status is Enabled. In Test Mode, emails go only to the Copy email address; a Disabled configuration doesn't run.

4. Check the source of the email notification

Courier reads the custom message as plain text. If the notification's message contains HTML tags—often added when the line is pasted with formatting or styled in the editor—Courier can't read the values and doesn't process the request.

In the copy of the notification you received in check 1, view the message source (for example, Show original in Gmail or View source in Outlook) and find the custom message line.
Look for HTML tags or entities mixed into the line, such as <div>, <span>, <p>, <font>, style="..." attributes, or   between the values.
If you find any, open the email notification in Quickbase and remove the additional HTML tags so only the plain text remains, for example:
```
configid=Q123:4567 recid=[Record ID#] configkey=a1b2c3 type=courier
```
For the Multiple Record Version, keep %RepeatOn%, the custom message line, and %RepeatOff% each on their own line.
Save the notification and fire it again to confirm.

5. Check the configuration's activities

In the Courier configurations list, select the Activities icon for the configuration. Each run shows the run date, run mode, the record ID processed, the number of emails to be sent and sent, records bypassed and updated, and Processing Details. If there is no activity for the time the notification fired, Courier didn't receive or accept the request—go back to checks 1 to 4.

Processing Details explains why a record was skipped or an email wasn't sent. Common reasons:

Processing details	What to do
The email addresses are invalid, or Found Email Addresses that were blank.	Check the value of the configuration's Email field on that record. Separate multiple addresses with `;`.
Fields are missing in the clist used to select the data for the message.	A field used in the subject or message isn't in the configuration's Message/Subject Field List. Courier adds a field to this list only when you drag it from Table Fields into the subject or message on the Email Message tab; a field name typed by hand in square brackets isn't added, and saving the tab again doesn't update the list. Drag the field in, or type its field ID into Message/Subject Field List (separate field IDs with a period), and save the tab.
A limit was reached (per run, daily, monthly, or file attachments).	Check View Limits on the configuration. To raise a limit, submit a technical support case.
Unable to include the HTML table in your email body message.	An embedded table in the message isn't set up correctly. Check the table settings in the message body.
The Office 365 refresh token has expired.	Regenerate the refresh token. See Office 365 refresh token expired.

6. The email was sent but not received

If the activity shows the email as sent (and the configuration's Update field was updated), Courier handed the email to the mail server. If a recipient still doesn't get it:

Ask the recipient to check their spam or junk folder, and to allow the sending address.
If you send from your own mail server, check whether anything changed on that account—for example, a new password, an expired Gmail app password, or an Office 365 refresh token that needs to be regenerated. Use Test Mail Server Settings on the mail server to confirm it can still send.
Check the SPF, DKIM, and DMARC records for your mail domain. See DNS considerations for your mail domain.

7. IP filtering on your Quickbase account

If your Quickbase account restricts access by IP address, Courier can't read your records or update them. Add these Courier IP addresses to your allowed list:

3.219.142.212/32
32.193.119.5/32
34.231.252.118/32

Still not working?

Submit a technical support case and include:

The Courier configuration ID.
The Record ID# of a record that should have sent an email.
The date and time (with time zone) the notification fired.
The copy of the notification you received in check 1.

Office 365 refresh token expired

When a configuration sends through your own Office 365 mail server with modern authentication, Courier signs in to that mailbox with a refresh token. You generate the token once from the mail server in the Extensions Portal. When the token expires or is revoked, Courier can no longer send from that mailbox.

What you'll see

The configuration's activities show the error QB Courier is unable to send out email(s), your Office 365 Refresh Token has expired.
Emails stop for every configuration that uses that mail server. When the error occurs, Courier stops processing the remaining records for that configuration in that run.
Emails that failed aren't sent again automatically. After you regenerate the token, fire the notification again or run the configuration again for the records that were missed.

Why the token expires

It reached the lifetime set by your organization's Microsoft 365 policy. The default is 90 days; your Microsoft 365 administrator can confirm the policy for your organization.
The mailbox password changed. Changing the password of the mailbox Courier sends from invalidates the token—regenerate it every time the password changes.
Access was revoked by your Microsoft 365 administrator, for example, by signing the mailbox out of all sessions.

Regenerate the refresh token

In the Extensions Portal, on the QB Courier tile, select Mail Servers.
Edit the Office 365 mail server. The form shows the Refresh Token Generated Date of the current token.
Select the Please check here to regenerate the refresh token checkbox.
Select Generate Refresh Token. A new browser tab opens.
In the new tab, select Generate Token and sign in to Microsoft with the mailbox that's entered as the mail server's User name—the same address Courier sends from.
Return to the mail server form and select Refresh Settings. The Refresh Token Generated Date changes to today.
Set Refresh Token Expiration Days to match your organization's policy (30 days, 60 days, 90 days, 120 days, or Does not expire), and select Save.
Select Test Mail Server Settings, enter an email address, and select Test Mail Server Settings to confirm Courier can send again.

Important
The token must be generated while signed in as the mail server's mailbox. If your browser is already signed in to a different Microsoft account, the token is created for that account and Courier still can't send. Copy the link from the new tab into a private (incognito) browser window, sign in with the mail server's mailbox, and generate the token there.

Avoid interruptions

Note the Refresh Token Generated Date and your organization's token lifetime, and regenerate the token before it expires. The Refresh Token Expiration Days setting records your policy—it doesn't extend the token.
Regenerate the token right after anyone changes the mailbox password.
Use a dedicated mailbox for Courier, so password changes for a person's account don't stop your emails.

Note
The Office 365 refresh token is different from the Quickbase user token Courier uses to read and update your Quickbase app. An error such as Please provide a valid Quickbase USER TOKEN to execute this add-on. means the Quickbase user token needs updating, not the refresh token. Update it under Client Credentials in the Extensions Portal.