DOCTAG Logo DOCTAG
DE DE ES ES FR FR IT IT
Start free

Configure Mail Connection

In addition to manual upload, PDFs can be imported by email.

How it works

  • The email must contain a PDF file.
  • The PDF must contain a valid DOCTAG QR code.
  • Only if validation is successful, the document is imported.
  • If multiple QR codes are found, the PDF is split before each code into separate documents.

Setup

Open Settings > System > E-mail and enter the credentials of a mailbox that is used exclusively by the DOCTAG server. The mail import always uses the workflow marked as default (with asterisk) in the settings.

Important Note: In the e-mail settings, make sure to switch to the "Security" tab and check "Receive documents via mail active". Without this checkbox enabled, automatic mail import remains disabled and the server log will show: "Mail import skipped because shouldReceiveDocumentsViaMail is disabled".

Mailimport deletes emails from the mailbox after import.

Modern OAuth2 Mail Integration

Starting in 2026, DOCTAG supports secure and universal mailbox integration via OAuth2 (RFC 6749) and XOAUTH2 (RFC 7628). This allows you to connect Google, Microsoft, Yahoo, and many other providers without proprietary APIs or extra libraries.

  • ✅ Universal: Works with Google, Microsoft, Yahoo, and any OAuth2 provider
  • ✅ Secure: No plain text passwords, tokens are stored encrypted (AES-256)
  • ✅ Simple: Unified setup, fewer dependencies
  • ✅ Backward compatible: Classic IMAP/POP3 still possible

Supported Providers

  • Google: imap.gmail.com
  • Microsoft: outlook.office365.com
  • Yahoo: imap.mail.yahoo.com
  • Others: Any IMAP server with XOAUTH2 support

Setup Steps

  1. Go to Settings > System > E-Mail, select "OAuth2 (Google, Microsoft, Yahoo)" as the sign-in method and pick the matching provider template (Google/Microsoft/Yahoo/Custom).
  2. Copy the automatically displayed redirect URI (https://<your-domain>/api/oauth2/callback) – you will need it in the next step.
  3. Register an OAuth2 app with the provider and enter the redirect URI there:
    • Google: Google Cloud Console → set up the OAuth consent screen and publish the app to "In production" (in testing mode, refresh tokens expire after just 7 days) → create an OAuth client ID of type "Web application".
    • Microsoft: Azure/Entra Admin Center → create an app registration → generate a client secret → add the API permissions IMAP.AccessAsUser.All, SMTP.Send and offline_access.
    • Yahoo: Yahoo Developer Network → register an app.
  4. Copy the client ID and client secret from the provider into the DOCTAG mail settings.
  5. Click "Connect with provider", sign in to the mailbox and confirm access.
  6. DOCTAG automatically redirects you back to the mail settings; credentials are now stored encrypted.

Security & Token Management

  • All OAuth2 tokens are stored encrypted with AES-256.
  • Access tokens are refreshed automatically in the background (including during the automatic cronjob mail import), no manual action required.
  • If a token cannot be refreshed automatically (e.g. because the refresh token became invalid), DOCTAG shows a warning at the top of the page – simply repeat "Connect with provider" once.

Migration & Compatibility

  • Existing IMAP/POP3 mailboxes continue to work (legacy mode).
  • For new Google/Microsoft/Yahoo mailboxes, OAuth2 is strongly recommended.

Troubleshooting

  • "XOAUTH2 not supported": Mail server does not support XOAUTH2 – please use legacy mode.
  • "Invalid access token": Token expired – please re-authorize.
  • "OAuth2 configuration missing": Check OAuth2 client data in environment variables.
  • Redirect URI mismatch: The redirect URI registered with the provider must match the one shown in DOCTAG exactly.