Skip to main content
The easiest path is the desktop setup assistant:
1
Open Integrations settings
2
In the desktop app, go to Settings → Integrations → Gmail / Google Calendar.
3
Run the setup assistant
4
Click Run setup assistant.
5
Choose the Google services you want:
6
  • Email only — Gmail read/send scopes
  • Email + Calendar — Gmail read/send plus Calendar
  • Calendar only — Calendar without Gmail tools
  • All current Google services — legacy full ntrp scope set, including Pub/Sub
    • 7
    Create Google OAuth credentials
    8
    The assistant walks you through Google Cloud setup. In short:
    9
  • Go to Google Cloud Console
  • Create or select a project
  • Enable the Gmail API
  • Configure the OAuth consent screen
  • Create an OAuth 2.0 client with application type Desktop app
  • Download the credentials JSON
    • 10
    Import credentials
    11
    Use the assistant to either:
    12
  • Select/import the downloaded credentials file by path, or
  • Paste the credentials JSON directly
    • 13
    ntrp saves the normalized credentials to ~/.ntrp/gmail_credentials.json.
    14
    Add account
    15
    Click Add account. ntrp opens a local browser OAuth consent flow and saves the token under ~/.ntrp/.

    ​
    Manual setup

    If you do not use the desktop assistant, place your Google OAuth Desktop app credentials at: 
    ~/.ntrp/gmail_credentials.json
    Then enable Gmail: 
    export NTRP_GMAIL=true
    Start the server and desktop app, then add the account from Settings → Integrations or call: 
    curl -X POST http://localhost:6877/gmail/add \
  -H "Authorization: Bearer $NTRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_choice":"email"}'

    ​
    Google verification note

    ntrp currently uses bring-your-own Google OAuth credentials. Gmail scopes such as read/send are restricted Google scopes, so shipping a shared public OAuth app would require Google’s verification/security-assessment process. BYO credentials keep setup local and avoid routing Gmail access through a third-party auth broker.

    ​
    Configuration

    VariableDefaultDescription
    NTRP_GMAILfalseEnable Gmail integration
    NTRP_GMAIL_DAYS30Days of email history to index

    ​
    Available tools

    ToolDescription
    emailsSearch and list emails by date or query
    read_emailGet full email content by ID
    send_emailSend an email (requires approval)

    ​
    Troubleshooting

    • Missing credentials — import a Google OAuth Desktop app JSON; Web application credentials are rejected.
    • Access denied / test user — if your OAuth app is still in Testing mode, add your Google account as a test user.
    • API not enabled / 403 — enable the Gmail API in the same Google Cloud project.
    • Missing scope — re-run setup and choose a service option that includes the needed Gmail scope.

    ​
    Multiple accounts

    Add more accounts from the desktop Integrations tab, or call /gmail/add again. Tokens are saved as account-specific files such as gmail_token_<email>.json.