Outlook Entra — SKILL.md

Microsoft Outlook via OAuth 2.0 (device code flow) et Microsoft Graph API. Lecture seule — seules les permissions Mail.Read, Calendars.Read, Contacts.Read sont utilisées.

Prérequis

• App enregistrée sur Entra (Azure AD) avec permissions :
  • Mail.Read, Calendars.Read, Contacts.Read
  • OAuth 2.0 device code flow activé
• Python 3.8+ avec requests, html2text, cryptography
• Python 3.8+ avec un .venv créé dans le répertoire du skill (uv venv .venv && uv pip install html2text requests cryptography)
• Fichier .env configuré (voir .env.example)

Installation

# Créer l'environnement virtuel (obligatoire)
cd ~/.openclaw/workspace/skills/outlook-entra
uv venv .venv
uv pip install html2text requests cryptography

# Copier et éditer la config
cp .env.example .env
# ⚠️ Remplir client_id, client_secret, tenant_id dans .env

Authentification (Flow)

Le device code flow (RFC 8628) nécessite une intervention utilisateur unique.

Étape 1 — Lancer le script d'auth

.venv/bin/python scripts/outlook_auth.py

Le script va :

1. Demander un device code à Microsoft
2. Afficher un code utilisateur et une URL de vérification

Étape 2 — S'authentifier

Aller sur https://login.microsoft.com/device et entrer le code affiché. Délai : 15 minutes maximum.

Étape 3 — Attendre la confirmation

Le script poll automatiquement le endpoint Microsoft jusqu'à obtention du token. Une fois confirmé, les tokens sont sauvegardés localement.

Fonctionnement des tokens

• L'access_token expire après ~1h
• Le refresh_token permet d'obtenir un nouvel access_token sans intervention
• Le refresh est automatisé par cron toutes les heures (voir section Cron)
• Si le refresh_token expire aussi (plusieurs mois d'inactivité) → relancer le flow complet

Commandes utiles

# Vérifier le statut du token
.venv/bin/python scripts/outlook_auth.py --status

# Rafraîchir le token manuellement
.venv/bin/python scripts/outlook_refresh.py

# Révoquer et supprimer les tokens
.venv/bin/python scripts/outlook_auth.py --revoke

Commandes (lecture seule)

# Statut de connexion
.venv/bin/python scripts/outlook_auth.py --status

# Lire les derniers messages
.venv/bin/python scripts/outlook_graph.py messages --folder Inbox --top 10

# Détail d'un message (corps complet, Markdown par défaut)
.venv/bin/python scripts/outlook_graph.py message \x3CmessageId>

# Détail en HTML brut (pour extraction/collage)
.venv/bin/python scripts/outlook_graph.py message \x3CmessageId> --raw

# Lister les dossiers mail
.venv/bin/python scripts/outlook_graph.py folders

# Pièces jointes d'un message
.venv/bin/python scripts/outlook_graph.py attachments \x3CmessageId>

# Télécharger une pièce jointe
.venv/bin/python scripts/outlook_graph.py download \x3CmessageId> --attach-id \x3CattachmentId> --output /path/to/file

# Événements calendrier
.venv/bin/python scripts/outlook_graph.py events --top 10

# Contacts
.venv/bin/python scripts/outlook_graph.py contacts --top 20

# Rechercher dans les mails
.venv/bin/python scripts/outlook_graph.py search "mot-clé"

# Profil utilisateur
.venv/bin/python scripts/outlook_graph.py profile

Variables d'environnement (.env)

Structure du skill

outlook-entra/
├── SKILL.md
├── README.md
├── .env.example
├── .gitignore
├── .venv/                   # Environnement virtuel Python (créé via uv venv)
├── scripts/
│   ├── outlook_auth.py      # OAuth device code flow + status/revoke
│   ├── outlook_graph.py     # Appels Graph API (lecture seule)
│   ├── outlook_refresh.py   # Refresh token automatisé (pour cron)
│   └── outlook_token.py     # Module partagé (lecture/refresh tokens)
└── tests/
    └── test_outlook.py      # Tests unitaires

Notes

• Le device code flow (RFC 8628) : l'utilisateur authentifie via https://microsoft.com/devicelogin. Une seule fois.
• Les refresh tokens sont automatiquement utilisés quand l'access token expire.
• Si TOKEN_FILE_KEY est défini, les tokens sont chiffrés AES-GCM avant stockage.
• Les erreurs 401 du Graph API déclenchent un refresh automatique.

Cron — Refresh automatique du token

Le script outlook_refresh.py vérifie si le token expire bientôt et le rafraîchit automatiquement.

Crontab — refresh toutes les heures à HH:55 :

55 * * * * /home/fred-ghilini/.openclaw/workspace/skills/outlook-entra/.venv/bin/python /home/fred-ghilini/.openclaw/workspace/skills/outlook-entra/scripts/outlook_refresh.py >> /home/fred-ghilini/.openclaw/outlook_refresh.log 2>&1

Installation :

SKILL_DIR="/home/fred-ghilini/.openclaw/workspace/skills/outlook-entra"
( crontab -l 2>/dev/null | grep -v outlook_refresh; echo "55 * * * * ${SKILL_DIR}/.venv/bin/python ${SKILL_DIR}/scripts/outlook_refresh.py >> ~/.openclaw/outlook_refresh.log 2>&1" ) | crontab -

Vérification :

crontab -l | grep outlook_refresh

Ressources

• OAuth 2.0 Device Code Flow — Microsoft
• Microsoft Graph — Mail API
• Microsoft Graph — Calendar API