libredesk supports three methods for connecting email inboxes: Google OAuth, Microsoft OAuth, and manual IMAP/SMTP configuration with password authentication.
Google setup
Connect your Gmail or Google Workspace inbox using an app password or OAuth 2.0.
App password
An app password is the quickest way to connect Gmail. It needs no Google Cloud Console setup. Your Google account must have 2-Step Verification enabled for this option to be available.
Generate an app password
Visit myaccount.google.com/apppasswords, name the app (e.g. libredesk), and copy the generated 16-character password.
Add inbox in libredesk
Go to Admin → Inboxes → New inbox → Email → Other provider and use these settings:
IMAP Configuration
| Field | Value |
|---|---|
| Host | imap.gmail.com |
| Port | 993 |
| TLS | SSL/TLS |
| Username | Your full Gmail address |
| Password | The app password from step 1 |
SMTP Configuration
| Field | Value |
|---|---|
| Host | smtp.gmail.com |
| Port | 587 |
| TLS | STARTTLS |
| Authentication Protocol (under Advanced) | Plain |
| Username | Your full Gmail address |
| Password | The app password from step 1 |
Create the inbox, then wait for the first scan
Click Create. libredesk does not check the mailbox immediately. It checks on the Scan Interval set under IMAP Configuration → Advanced, which is 5m by default.
Send a test email to the address, wait 5 minutes, then look in Conversations.
OAuth
Prerequisites
- A Google Cloud Console project
- OAuth 2.0 credentials (Client ID & Client Secret)
Required OAuth scopes
Your Google OAuth app needs these scopes:
| Scope | Purpose |
|---|---|
https://mail.google.com/ |
Full Gmail access for reading and sending emails |
https://www.googleapis.com/auth/userinfo.email |
Access to user's email address |
Configuration steps
Get callback URL from libredesk
In libredesk, go to Admin → Inboxes → New inbox → Email → Google. A dialog opens with the Callback URL. Copy it.
Create a Google Cloud project
Go to the Google Cloud Console and create a new project or select an existing one.
Enable Gmail API
In your project, navigate to APIs & Services → Library and enable the Gmail API.
Configure OAuth consent screen
Set up the OAuth consent screen with the required scopes listed above.
Create OAuth credentials
Go to APIs & Services → Credentials and click Create Credentials → OAuth client ID:
- Application type: Web application
- Add the callback URL from step 1 to Authorized redirect URIs
- Note down the Client ID and Client Secret
Complete setup in libredesk
Back in the libredesk dialog, enter the Client ID and Client secret, then click Continue. You'll be redirected to Google's consent screen to grant permissions.
Wait for the first scan
After you grant access, libredesk creates the inbox. It checks the mailbox every 5 minutes by default, so send a test email, wait 5 minutes, then look in Conversations.
Microsoft setup
Connect your Outlook or Microsoft 365 inbox using OAuth 2.0.
Prerequisites
- An Azure Active Directory (Azure AD) app registration
- OAuth 2.0 credentials (Client ID & Client Secret)
Required API permissions
Add the following Microsoft Graph delegated permissions in Azure Portal:
| Permission | Type | Description |
|---|---|---|
| Delegated | View users' email address | |
| IMAP.AccessAsUser.All | Delegated | Read and write access to mailboxes via IMAP |
| offline_access | Delegated | Maintain access to data you have given it access to |
| openid | Delegated | Sign users in |
| SMTP.Send | Delegated | Send emails from mailboxes using SMTP AUTH |
| User.Read | Delegated | Sign in and read user profile |
Configuration steps
Get callback URL from libredesk
In libredesk, go to Admin → Inboxes → New inbox → Email → Microsoft. A dialog opens with the Callback URL. Copy it.
Register an app in Azure Portal
Go to the Azure Portal → Azure Active Directory → App registrations → New registration:
- Enter a name for your application
- Select the appropriate account type (single tenant or multi-tenant)
- Add the callback URL from step 1 as the Redirect URI
Configure API permissions
In your app registration, go to API permissions → Add a permission → Microsoft Graph:
- Add all the delegated permissions shown in the table above
- Click Grant admin consent for Default Directory
Create client secret
Go to Certificates & secrets → New client secret:
- Add a description and expiration period
- Copy the secret value immediately (it won't be shown again)
Note your credentials
From the Overview page, copy:
- Application (client) ID
- Directory (tenant) ID (if using single-tenant)
Complete setup in libredesk
Back in the libredesk dialog, enter the Client ID, Client secret, and Tenant ID (optional), then click Continue. You'll be redirected to Microsoft's consent screen to grant permissions.
Wait for the first scan
After you grant access, libredesk creates the inbox. It checks the mailbox every 5 minutes by default, so send a test email, wait 5 minutes, then look in Conversations.
Manual IMAP/SMTP setup
Use manual IMAP/SMTP for self-hosted mail servers and for providers that don't support OAuth. For Gmail, use the app password option under Google setup instead.
Configuration steps
Add inbox in libredesk
Navigate to Admin → Inboxes → New inbox → Email → Other provider, fill in IMAP Configuration and SMTP Configuration, then click Create.
Wait for the first scan
libredesk does not check the mailbox immediately. It checks on the Scan Interval set in the same form, which is 5m by default.
Send a test email to the address, wait 5 minutes, then look in Conversations.
Email aliases
An inbox can receive and send mail for more than one address. Add the extra addresses under Email aliases in the inbox form.
Each alias must forward to this inbox's mailbox, and your SMTP provider must allow sending as that alias.
Add the alias
Click Add, enter the address, then save the inbox.
Verify the alias
Click Verify next to the alias. libredesk sends a test email from the alias and marks it Verified when the email reaches the inbox. If it shows Failed, fix forwarding or send-as permissions, then click Try again.
Only verified aliases are used for sending. A reply goes out from the alias the contact wrote to. Agents can pick another address in the From field of the reply box.
Inbox options
| Option | What it does |
|---|---|
| From display name template | Sender name on replies, for example {{ .Agent.FirstName }} at {{ .Inbox.Name }} |
| Reply-To address | Where customer replies go, when it differs from the From address |
| Enable plus addressing | Improves conversation threading. Your provider must support it |
| CSAT Surveys | Sends a satisfaction survey when a conversation is resolved |
| Prompt to tag before replying | Warns agents before they reply on a conversation with no tags |
Live chat {#live-chat}
For live chat widget setup, see the Live Chat guide.
WhatsApp {#whatsapp}
For WhatsApp setup, see the WhatsApp guide.
