Mankomail

Airtable ​

Vos bases Airtable : chercher une fiche, créer ou compléter une ligne sans doublon, y déposer une pièce jointe du mail et commenter un enregistrement.

Une connexion Airtable permet au nœud Airtable de lire, créer et compléter des lignes de vos bases sans doublon, d’y déposer les pièces jointes d’un e-mail et de commenter un enregistrement. La même connexion alimente le déclencheur Ligne Airtable modifiée, qui interroge une table à intervalle régulier et démarre un workflow pour chaque ligne nouvelle ou modifiée.

La connexion porte un jeton d’accès personnel. Il est chiffré au repos, appliqué par le serveur au moment de l’appel, et n’apparaît jamais dans un workflow.

En bref ​

  • Identifiant : airtable
  • Famille : Service
  • Configurée par : Un membre (personnelle) ou un administrateur (partagée avec l’organisation)
  • Authentification : Clé d’API ou jeton
  • Type de credential : service:airtable
  • Documentation officielle de l’API : https://airtable.com/developers/web/api/introduction
  • URL de base de l’API : https://api.airtable.com
  • Limite de débit appliquée par Mankomail : 4 requêtes par seconde et par connexion ; jusqu’à 4 tentatives sur un 429 ou un 5xx
  • Signature des webhooks : en-tête X-Airtable-Content-MAC, HMAC-SHA256 du corps brut
  • Test de connexion : Oui

Pas à pas ​

Les mêmes étapes s’affichent dans le formulaire de connexion de l’application.

  1. Connectez-vous à Airtable et ouvrez airtable.com/create/tokens, puis cliquez sur « Create new token ».
  2. Nommez le jeton de façon explicite : ce nom apparaît dans l’historique des enregistrements (« Untel via <nom> »).
  3. Dans « Scopes », ajoutez data.records:read, data.records:write et schema.bases:read — plus data.recordComments:write si vous voulez commenter. Le déclencheur sonde la table : il ne demande aucun droit de plus.
  4. Dans « Access », cliquez sur « Add a base » et choisissez la ou les bases concernées : le jeton ne verra rien d’autre.
  5. Cliquez sur « Create token » et copiez-le immédiatement — Airtable ne l’affiche qu’une fois — puis collez-le ci-dessous et testez la connexion.
  6. Le secret de signature ne sert qu’aux webhooks Airtable : Airtable le rend une seule fois, à la création du webhook. Laissez-le vide sinon.

Champs de la connexion ​

ChampNatureRequisRemarques
Jeton d’accès personnel (token)Secret — jamais réaffichéOuiIl agit comme le compte qui l’a créé : si cette personne perd ses droits sur une base, les workflows s’arrêtent.
Secret de signature des webhooks (macSecret)Secret — jamais réaffichéNonFacultatif. Le « macSecretBase64 » rendu par Airtable à la création du webhook, et jamais réaffiché ensuite.

Avant de commencer ​

  • Il vous faut un compte Airtable ayant accès aux bases à automatiser. Chaque utilisateur crée ses jetons d’accès personnels sur airtable.com/create/tokens ; les anciennes clés d’API (key…) ne fonctionnent plus.
  • Le jeton agit comme le compte qui l’a créé. Si cette personne perd ses droits sur une base ou quitte la structure, les workflows qui l’emploient s’arrêtent. Pour une équipe, créez le jeton depuis un compte de service dédié.
  • Pour écrire, le compte doit avoir au moins des droits d’éditeur sur la base. L’éditeur affiche le niveau de droit de chaque base (read, comment, edit, create…) à côté de son nom : c’est ce qui explique à l’avance pourquoi une écriture serait refusée.
  • Le déclencheur Ligne Airtable modifiée exige un champ « Date de dernière modification » (ou « Date de création ») dans la table surveillée. Ajoutez-le dans Airtable avant de configurer le déclencheur.

Autorisations ​

Airtable appelle ces autorisations des scopes. Ne cochez que ce que vous utilisez.

ScopeObligatoireÀ quoi il sert
data.records:readOuiRechercher, Lire un enregistrement, Lister celles d’un enregistrement (pièces jointes), et chaque passage du déclencheur Ligne Airtable modifiée.
data.records:writeOuiCréer, Créer ou mettre à jour, Mettre à jour, Supprimer et Déposer les pièces jointes.
schema.bases:readOuiLister les bases, Lire le schéma d’une base, et toutes les listes de l’éditeur (base, table, vue, champ). Sans lui, aucune liste ne se remplit.
data.recordComments:writeSeulement pour commenterL’opération Commenter.
data.recordComments:readNonProposé par le guide de l’application ; aucune opération actuelle ne lit les commentaires.
webhook:manageNonProposé par le guide de l’application pour les déclencheurs ; le déclencheur Ligne Airtable modifiée fonctionne par sondage et ne l’utilise pas.
user.email:readNonPermet au test de connexion d’afficher l’e-mail du compte plutôt que son identifiant Airtable.

Dans Access, ajoutez chaque base que les workflows doivent atteindre : le jeton ne voit rien d’autre.

Ajouter la connexion ​

  1. Ouvrez Connexions. Dans la section Services tiers, repérez la carte Airtable et cliquez sur Connecter.
  2. Donnez un Nom à la connexion : c’est ce que vous lirez dans le sélecteur de connexion d’un nœud.
  3. Choisissez la Portée : Personnelle (vous seul la voyez et l’utilisez) ou Organisation (toute l’organisation l’utilise ; seul un administrateur peut la créer).
  4. Collez le jeton, laissez vide le secret de signature des webhooks, puis cliquez sur Créer la connexion.
  5. De retour dans la liste, cliquez sur Configurer sur la nouvelle connexion, puis sur Tester la connexion.

Le test appelle GET /v0/meta/whoami, puis GET /v0/meta/bases :

  • si les deux répondent et qu’au moins une base est joignable, il affiche La connexion fonctionne, suivi de l’e-mail du compte (avec user.email:read) ou de son identifiant Airtable ;
  • si le jeton répond mais n’atteint aucune base, le test échoue et indique schema.bases:read comme manquant. La cause habituelle n’est pas le scope mais la liste Access : aucune base n’a été ajoutée au jeton ;
  • pour un jeton de type OAuth qui annonce ses scopes, le test liste les scopes obligatoires manquants.

Dans un nœud, choisissez la connexion dans Connexion Airtable, puis descendez la cascade : Base → Table → Vue ou Champ. Changer de base vide la table. Chaque liste accepte aussi un identifiant saisi à la main ou une URL Airtable collée (https://airtable.com/appXXXX/tblYYYY/viwZZZZ). Les listes de champs sont filtrées selon l’opération : seulement les champs « pièces jointes » pour un dépôt, seulement les champs non calculés pour une clé de rapprochement. Le workflow enregistre les identifiants (app…, tbl…, fld…, viw…) : renommer une colonne dans Airtable ne casse rien.

Pour remplacer le jeton, ouvrez Configurer, collez la nouvelle valeur et enregistrez ; un champ secret laissé vide conserve la valeur en place. Supprimer est refusé tant qu’un workflow publié utilise la connexion : dépubliez-le ou changez sa connexion d’abord.

Webhooks ​

Le déclencheur Ligne Airtable modifiée n’utilise pas les webhooks Airtable : il procède par sondage.

  • Il s’arme à la publication du workflow. Sa position de départ est « maintenant » : publier ne rejoue jamais l’historique de la table, et republier ne remet jamais la position à zéro.
  • Vérifier toutes les (minutes) vaut 15 par défaut, accepte de 5 à 1 440, et ne descend jamais sous le plancher de l’instance (INTEGRATION_POLL_MIN_MINUTES, 5 minutes par défaut — voir les variables d’environnement).
  • Chaque passage lit au plus une page de lignes ; le reste attend le passage suivant. Chaque ligne donne une exécution, avec ses données sous data.airtable. La clé de déduplication dérive de la ligne et de son heure de modification : un passage répété après un incident ne crée pas de seconde exécution.
  • Sur l’offre gratuite d’Airtable, le quota mensuel d’appels d’API est bas : un intervalle court peut l’épuiser vite.

Le formulaire de connexion comporte aussi un champ Secret de signature des webhooks. Mankomail sait vérifier l’en-tête X-Airtable-Content-MAC d’Airtable (hmac-sha256= suivi d’un HMAC-SHA256 du corps brut, avec pour clé le macSecretBase64 décodé), mais aucun déclencheur actuel ne reçoit de webhooks Airtable. Laissez ce champ vide.

Erreurs fréquentes ​

Message ou codeCauseQue faire
Test : « la clé est refusée par le service » (integration.unauthorized)Jeton révoqué, mal copié ou expiré.Créez un nouveau jeton et remplacez-le dans Configurer.
Test : « le jeton ne porte pas tous les droits nécessaires (schema.bases:read) »Le jeton n’atteint aucune base (rien dans Access), ou un réglage d’entreprise bloque l’accès par API.Ajoutez les bases au jeton sur airtable.com/create/tokens, puis testez à nouveau.
Test : « le jeton ne porte pas tous les droits nécessaires (…) » avec d’autres scopesLe jeton annonce ses scopes et il en manque d’obligatoires.Ajoutez data.records:read, data.records:write et schema.bases:read.
Test : « le quota du service est dépassé » (integration.rate_limited)Airtable a répondu 429.Le jeton est bon : réessayez dans un moment.
integration.unauthorized pendant une exécution401 ou 403 : jeton révoqué, ou scope manquant pour cette opération (par exemple data.recordComments:write pour Commenter).Élargissez les scopes du jeton ou remplacez-le. Rejouer n’y changera rien.
integration.not_found404 : la base, la table ou l’enregistrement n’existe pas, ou la base n’est pas dans la liste Access du jeton.Vérifiez les identifiants et les accès du jeton.
integration.rejected400 ou 422 : Airtable a refusé le corps (champ inconnu, mauvais type de valeur, clé d’upsert non unique, valeur absente d’une liste de choix sans conversion automatique).Corrigez le paramétrage du nœud ; la même requête serait refusée à nouveau.
integration.rate_limited429 après les nouvelles tentatives. Mankomail envoie au plus 4 requêtes par seconde et par connexion, réessaie jusqu’à 4 fois et respecte l’attente de 30 secondes imposée par Airtable.Temporaire : le moteur reprend l’étape plus tard. Étalez les workflows qui partagent le même jeton.
integration.unavailable5xx, 409 ou panne réseau, après rejeu.Temporaire : le moteur reprend l’étape plus tard.
integration.connection_unusableLa connexion a été supprimée, n’est pas active, est hors de votre portée (connexion personnelle d’un autre membre), ou appartient à un autre service.Choisissez une connexion valide dans le nœud.
Notification « Le déclencheur du workflow … est en panne »Un passage de Ligne Airtable modifiée a échoué de façon définitive. La raison affichée suit le code : integration.unauthorized (reconnectez), integration.not_found (la base ou la table n’existe plus), integration.rejected (vérifiez le paramétrage du déclencheur), integration.poll_misconfigured (aucune connexion choisie), integration.poll_failed (par exemple une base, une table ou un Champ de date laissé vide). Une notification par panne ; les échecs temporaires (429, 5xx) ne réveillent personne.Corrigez la cause, puis attendez le passage suivant : le déclencheur repart tout seul.

Nœuds qui utilisent cette connexion ​