Getting Credentials

This page covers how to obtain API credentials for each messaging platform and email provider. These steps are only needed for self-hosted deployments. If you are using the hosted version, credentials are already configured.

Discord

1. Create an application

1. Go to the Discord Developer Portal
2. Click New Application, give it a name (e.g. "MailFellow"), and click Create

2. Create a bot

1. In your application, go to Bot in the left sidebar
2. Click Reset Token to generate a bot token
3. Copy the token. You will not be able to see it again.

3. Enable required intents

On the same Bot page, scroll down to Privileged Gateway Intents and enable:

• Message Content Intent:required for reading message content in threads

4. Generate the invite URL

1. Go to OAuth2 in the left sidebar
2. Under OAuth2 URL Generator, select the bot scope
3. Under Bot Permissions, select:
   • Send Messages, Create Public Threads, Send Messages in Threads
   • Manage Threads, Manage Channels, Embed Links
   • Attach Files, Manage Webhooks, Read Message History
   • Add Reactions, Use Slash Commands
4. Copy the generated URL. This is your Bot Invite URL

5. Enter in MailFellow

Go to Admin > Platform and enter:

Slack

For self-hosted deployments, MailFellow uses Slack's Socket Mode which does not require a public URL.

1. Create a Slack app

1. Go to Slack API: Your Apps
2. Click Create New App, choose From scratch
3. Name it (e.g. "MailFellow") and select your workspace

2. Enable Socket Mode

1. Go to Socket Mode in the left sidebar
2. Toggle Enable Socket Mode on
3. Give the app-level token a name (e.g. "mailfellow-socket") and click Generate
4. Copy this xapp- token. This is your App Token.

3. Configure bot permissions

1. Go to OAuth & Permissions
2. Under Bot Token Scopes, add:
   • chat:write, chat:write.customize
   • channels:history, channels:read, channels:manage
   • files:write, reactions:read, commands

4. Enable event subscriptions

1. Go to Event Subscriptions
2. Toggle Enable Events on
3. Under Subscribe to bot events, add: message.channels, reaction_added
4. Click Save Changes

5. Enable interactivity

1. Go to Interactivity & Shortcuts
2. Toggle Interactivity on
3. Click Save Changes (no URL needed since Socket Mode handles it)

6. Install to workspace

1. Go to Install App
2. Click Install to Workspace and authorize
3. Copy the xoxb- token. This is your Bot Token.

7. Enter in MailFellow

Go to Admin > Platform and enter:

Telegram

1. Create a bot with BotFather

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Choose a display name (e.g. "MailFellow Email")
4. Choose a username ending in bot (e.g. mailfellow_email_bot)
5. Copy the bot token (looks like: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Configure commands (recommended)

In BotFather, send /setcommands and paste:

send - Send a new email
quick - Reply with a saved quick response
assign - Assign this email thread
unassign - Remove assignment
start - Get your Chat ID and help info

3. Enter in MailFellow

Go to Admin > Platform and enter the Bot Token.

WhatsApp

WhatsApp requires the WhatsApp Business Platform (Cloud API) from Meta.

1. Create a Meta App

1. Go to Meta for Developers
2. Click Create App, select Business type
3. Name your app and select your Meta Business account

2. Add WhatsApp and get credentials

1. In the app dashboard, find WhatsApp and click Set up
2. Go to WhatsApp > API Setup and copy the Phone Number ID
3. Get a permanent access token from Meta Business Suite > System Users:
   • Create a System User with Admin role
   • Generate a token with whatsapp_business_messaging and whatsapp_business_management permissions
4. Get your Business Account ID from WhatsApp Accounts

3. Configure the webhook

1. In your Meta App, go to WhatsApp > Configuration
2. Set Callback URL to: https://your-domain.com/api/whatsapp/webhook
3. Set a Verify Token (a secret string of your choice)
4. Subscribe to messages webhook field
5. Copy the App Secret from App Settings > Basic

4. Enter in MailFellow

Go to Admin > Platform and enter:

Microsoft Teams

1. Register an Azure Bot

1. Go to the Azure Portal - Create Azure Bot
2. Fill in: Bot handle, Subscription, Resource group, Pricing tier (Free F0), Type: Multi Tenant
3. Click Review + create, then Create

2. Get App ID and Secret

1. In the bot's Configuration, copy the Microsoft App ID
2. Click Manage Password, go to Certificates & secrets
3. Click New client secret and copy the Value

3. Set the messaging endpoint

In the bot's Configuration, set Messaging endpoint to: https://your-domain.com/api/teams/webhook

4. Enable the Teams channel

1. In your Azure Bot resource, go to Channels
2. Click Microsoft Teams and accept the terms

5. Enter in MailFellow

Go to Admin > Platform and enter:

Mattermost

1. Enable bot accounts

1. Go to Mattermost System Console > Integrations > Bot Accounts
2. Set Enable Bot Account Creation to true

2. Create a bot

1. Go to Integrations > Bot Accounts (from main menu)
2. Click Add Bot Account
3. Username: mailfellow, Role: System Admin
4. Copy the Access Token

3. Enable interactive messages

1. Go to System Console > Integrations > Integration Management
2. Enable: Incoming Webhooks, Outgoing Webhooks, Interactive Messages

4. Enter in MailFellow

Go to Admin > Platform and enter:

Gmail (Google OAuth)

You need a Google Cloud project with the Gmail API enabled.

1. Go to the Google Cloud Console - Credentials
2. Create a new project (or select an existing one)
3. Go to APIs & Services > Library, search for Gmail API, and click Enable
4. Go to APIs & Services > Credentials
5. Click Create Credentials > OAuth client ID
6. Choose Web application
7. Add your redirect URI: https://your-domain.com/auth/google/callback
8. Click Create
9. Copy the Client ID and Client Secret

If this is a new project, configure the OAuth consent screen:

1. Go to APIs & Services > OAuth consent screen
2. Choose External user type
3. Fill in app name, support email, and developer email
4. Add scopes: gmail.readonly, gmail.send, gmail.modify
5. Add your email as a test user (required while app is in "Testing" mode)
6. To allow anyone to connect, submit for verification

Outlook (Microsoft OAuth)

You need an Azure AD app registration with Microsoft Graph permissions.

1. Go to the Azure Portal - App registrations
2. Click New registration
3. Name it (e.g. "MailFellow"), select Accounts in any organizational directory and personal Microsoft accounts
4. Set redirect URI to Web: https://your-domain.com/auth/outlook/callback
5. Click Register
6. Copy the Application (client) ID
7. Go to Certificates & secrets, click New client secret, copy the Value
8. Go to API permissions > Add a permission > Microsoft Graph > Delegated permissions:
   • Mail.Read, Mail.Send, offline_access, User.Read
9. Click Grant admin consent if you are the admin