# Envoyer les inscriptions de votre propre formulaire de newsletter vers Kit > Reliez votre propre formulaire de newsletter à Kit avec un relais qui crée l'abonné, l'ajoute à un formulaire Kit pour l'incentive email et étiquette l'emplacement. Publié le 2026-10-25 · https://ikiform.com/fr/guides/newsletter-signup/kit Envoyez votre propre formulaire à Ikiform, et faites pointer un webhook Ikiform vers un relais qui fait jusqu'à trois appels à l'API v4 de Kit : créer l'abonné, l'ajouter à un formulaire Kit, et étiqueter l'endroit où il s'est inscrit. Créez-le en `inactive` et ajoutez-le à un formulaire dont l'incentive email est activé : Kit devrait alors envoyer sa propre confirmation, à tester une fois avec une adresse à vous, car Kit ne le documente que pour son endpoint en masse. Le relais détient la clé d'API Kit ; votre page ne la voit jamais. ## Ce qui change avec Kit Kit découpe une inscription en objets distincts. Un abonné est une personne. Un formulaire est l'endroit d'où il vient, et il porte l'e-mail de confirmation, que Kit appelle aussi incentive email : son étape de double opt-in. Un tag est une étiquette pour segmenter. L'API v4 a un endpoint pour chacun, et les endpoints du formulaire comme du tag exigent que l'abonné existe déjà. Une inscription Ikiform devient donc une courte suite d'appels, dans l'ordre : Schéma : Les appels à l'API Kit que fait le relais pour une inscription 1. Le relais reçoit le webhook signé d'Ikiform et le vérifie. 2. Il crée l'abonné dans Kit en inactive. Si l'adresse existe déjà, Kit met à jour le prénom et ne touche pas à l'état. 3. Il ajoute l'abonné à votre formulaire Kit. Si l'incentive email de ce formulaire est activé, Kit envoie la confirmation. 4. Si la source de l'inscription a un tag, il étiquette l'abonné. Cette étape est facultative. Chaque appel dépend du précédent : le relais s'arrête donc au premier échec et laisse Ikiform réessayer. | Appel | Réponse de Kit | Signification | | --- | --- | --- | | Créer l'abonné | `201` | Nouvel abonné, créé dans l'état envoyé | | Créer l'abonné | `200` | Existe déjà. Prénom mis à jour, état inchangé | | Ajouter au formulaire | `201` ou `200` | Ajouté, ou déjà dans le formulaire. La documentation des formulaires en masse de Kit indique que les personnes déjà inscrites à un formulaire ne reçoivent pas à nouveau l'incentive email | | Tout appel | `401` | Clé d'API erronée ou manquante | | Ajout au formulaire ou au tag | `404` | L'id du formulaire ou du tag n'existe pas dans ce compte | | Tout appel | `429` | Au-delà de la limite de débit de la clé d'API | ## Configurer Kit 1. Dans Kit, créez un formulaire pour ces inscriptions, par exemple « Inscription site web ». Vous ne l'intégrerez pas ; il sert à enregistrer d'où viennent les abonnés et à héberger l'incentive email. 2. Ouvrez les réglages du formulaire et activez l'incentive email si vous voulez le double opt-in. Rédigez l'e-mail et définissez où mène le lien de confirmation. 3. Trouvez l'id numérique du formulaire, dans l'application Kit ou avec l'endpoint de l'API qui liste les formulaires. Créez un tag par emplacement si vous le souhaitez, et notez leurs id. 4. Créez une clé d'API v4 dans les réglages développeur de Kit et gardez-la pour l'environnement du relais. > La documentation de l'API de Kit indique que l'accès à l'API dépend de l'éligibilité de l'offre du compte, et sa page de tarifs liste les apps et intégrations à partir de l'offre Creator. Vérifiez que votre offre peut créer une clé v4 avant de construire dessus. ## Le relais Un route handler Next.js reçoit le webhook et un petit module dialogue avec Kit. Les deux mêmes fichiers tournent sur n'importe quel hébergeur Node ou edge qui fournit une URL HTTPS publique. `lib/kit.ts`: ```ts const KIT = "https://api.kit.com/v4"; const TAGS: Record = { footer: 1111111, post: 2222222, }; function call(path: string, body: Record) { return fetch(`${KIT}${path}`, { method: "POST", headers: { "X-Kit-Api-Key": process.env.KIT_API_KEY!, "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify(body), }); } export async function addToKit(signup: { email: string; firstName?: string; source: string; referrer?: string }) { const created = await call("/subscribers", { email_address: signup.email, first_name: signup.firstName ?? null, state: "inactive", }); if (!created.ok) return created; const joined = await call(`/forms/${process.env.KIT_FORM_ID}/subscribers`, { email_address: signup.email, referrer: signup.referrer ?? null, }); if (!joined.ok) return joined; const tag = TAGS[signup.source]; if (!tag) return joined; return call(`/tags/${tag}/subscribers`, { email_address: signup.email }); } ``` `app/api/kit/route.ts`: ```ts import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks"; import { addToKit } from "@/lib/kit"; export async function POST(request: Request) { const payload = await request.text(); let event; try { event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! }); } catch (error) { if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 }); throw error; } if (event.type !== "submission.created") return new Response(null, { status: 204 }); const { email, first_name, consent, source } = event.data.fields; if (consent !== true || typeof email !== "string") return new Response("Skipped", { status: 200 }); const answer = await addToKit({ email, firstName: typeof first_name === "string" ? first_name : undefined, source: typeof source === "string" ? source : "unknown", referrer: typeof event.data.meta.referrer === "string" ? event.data.meta.referrer : undefined, }); if (answer.status === 429) return new Response("Kit rate limit", { status: 503, headers: { "retry-after": "60" } }); if (!answer.ok) return new Response(`Kit answered ${answer.status}: ${await answer.text()}`, { status: 502 }); return new Response(null, { status: 204 }); } ``` `.env.local`: ```bash IKIFORM_WEBHOOK_SECRET=whsec_... KIT_API_KEY=your-v4-api-key KIT_FORM_ID=1234567 ``` - `X-Kit-Api-Key` est la façon dont l'API v4 de Kit reçoit une clé d'API personnelle. OAuth sert aux applications que d'autres installent ; un relais pour votre propre liste n'en a pas besoin. - Envoyer `state: "inactive"` est ce qui garde un nouvel abonné non confirmé jusqu'à son clic. Sans cela, Kit le crée en `active`, et l'état ne peut plus être modifié ensuite via le même endpoint. - Le referrer de la page part chez Kit comme `referrer` du formulaire : Kit montre donc l'article d'où vient le lecteur. - Le corps d'erreur de Kit va dans le `502` : le journal de livraison d'Ikiform affiche donc le message de Kit. - Associez chaque valeur `source` à un id de tag dans `TAGS`. Une source sans tag saute le troisième appel. Ajoutez l'URL de la route sous **Webhooks** dans le tableau de bord Ikiform, choisissez le formulaire de newsletter et copiez le secret `whsec_` dans `IKIFORM_WEBHOOK_SECRET`. Chaque règle concernant l'URL et chaque réponse est dans la [documentation des webhooks](https://ikiform.com/fr/docs/webhooks.md). ## Limites de débit et nouvelles tentatives Kit autorise 120 requêtes par fenêtre glissante de 60 secondes pour une clé d'API. Chaque inscription en coûte deux ou trois : environ 40 à 60 inscriptions par minute passent avant que Kit ne réponde `429`. C'est largement suffisant pour un formulaire de pied de page, et juste le jour où un article devient viral. Le relais répond `503` avec `Retry-After` quand Kit répond `429`, et Ikiform attend avant de réessayer. Une nouvelle tentative rejoue toute la séquence depuis le début. C'est sans risque : la création renvoie `200` pour un abonné existant, et l'ajout de quelqu'un déjà dans le formulaire renvoie `200`. La documentation des formulaires en masse de Kit indique que les personnes déjà inscrites à un formulaire ne reçoivent pas à nouveau l'incentive email ; l'endpoint unitaire ne le précise pas, testez donc une nouvelle tentative avec une adresse à vous. [Votre propre serveur](https://ikiform.com/blog/form-submissions-to-your-own-server.md) montre comment enregistrer chaque `webhook-id` si vous préférez sauter les nouvelles tentatives déjà traitées. ## Pièges - **Les champs personnalisés doivent exister d'abord.** Si vous ajoutez `fields` à l'appel de création, utilisez la clé de chaque champ, comme `last_name`, et créez le champ dans Kit avant de l'envoyer. - **Les abonnés actifs restent actifs.** Comme la création ne change jamais l'état d'un abonné existant, un lecteur confirmé qui s'inscrit à nouveau n'a pas à reconfirmer. - **Les lecteurs désinscrits.** Un lecteur désinscrit qui s'inscrit à nouveau existe déjà : la création renvoie `200` et ne change pas son état. Voyez dans Kit comment vous voulez les traiter. - **Un formulaire, plusieurs emplacements.** Utilisez un seul formulaire Kit pour le site et des tags pour les emplacements. Plusieurs formulaires Kit, ce sont plusieurs incentive emails à garder synchronisés. - **Pas d'e-mail de la part d'Ikiform.** Ikiform n'envoie pas d'e-mail à la personne qui remplit le formulaire. Les e-mails de notification vont uniquement à vous et à votre équipe : il n'y a donc ni réponse automatique, ni e-mail de confirmation, ni double opt-in. Envoyez-les depuis votre outil d'e-mailing, déclenché par un [webhook](https://ikiform.com/fr/docs/webhooks.md). ## Vérifiez que tout fonctionne 1. Choisissez **Send test** sur l'endpoint dans Ikiform. La livraison affiche `204`, et rien ne change dans Kit. 2. Abonnez-vous sur votre page avec une adresse à vous. La livraison affiche `204`. 3. Dans Kit, l'abonné apparaît dans votre formulaire comme non confirmé, avec le tag de l'emplacement. 4. L'incentive email arrive. Cliquez sur le lien et l'abonné devient confirmé. 5. Abonnez-vous à nouveau avec la même adresse. La livraison affiche `204` et aucun second incentive email n'arrive. 6. Mettez un `KIT_FORM_ID` erroné un instant. La livraison affiche `502` avec le message `404` de Kit. ## Questions ### Puis-je utiliser mon propre formulaire HTML avec Kit au lieu d'un embed Kit ? Oui. Envoyez votre formulaire à Ikiform et laissez un relais ajouter chaque inscription via l'API v4 de Kit : créer l'abonné, l'ajouter à un formulaire Kit et, si vous le souhaitez, l'étiqueter. Kit le considère comme venant de ce formulaire. ### Kit enverra-t-il l'e-mail de confirmation pour les inscriptions de mon propre formulaire ? Normalement oui, si le relais crée l'abonné en inactive et l'ajoute à un formulaire Kit dont l'incentive email est activé. La documentation des formulaires en masse de Kit indique qu'ajouter des abonnés à un formulaire en double opt-in envoie l'incentive email. L'endpoint unitaire qu'utilise ce relais ne le précise pas : testez-le donc avec une adresse à vous. ### Ai-je besoin du flux OAuth de Kit ? Non. OAuth sert aux applications que d'autres utilisateurs de Kit installent. Pour votre propre liste, une clé d'API v4 dans l'en-tête X-Kit-Api-Key suffit, et elle reste dans l'environnement du relais. ### Combien d'inscriptions par minute le relais peut-il gérer ? Kit autorise 120 requêtes par fenêtre glissante de 60 secondes par clé d'API, et chaque inscription demande deux ou trois requêtes : environ 40 à 60 par minute. Au-delà, le relais répond 503 et Ikiform réessaie plus tard. ### Puis-je connecter Kit sans code ? Oui. Faites pointer le webhook Ikiform vers Zapier ou Make et utilisez leur action Kit pour ajouter un abonné à un formulaire. Vérifiez les options de l'action pour le tag et le formulaire. ## Autres guides - [Formulaire d'inscription à la newsletter](https://ikiform.com/fr/guides/newsletter-signup.md): Créez un formulaire d'inscription à la newsletter avec votre propre markup, enregistrez le consentement, bloquez les inscriptions de bots et transmettez chaque abonné à Kit, MailerLite, beehiiv ou n'importe quel outil. - [Double opt-in](https://ikiform.com/fr/guides/newsletter-signup/double-opt-in.md): Ikiform n'envoie pas d'e-mails de confirmation : le double opt-in se fait donc dans votre outil d'e-mailing. Un relais ajoute chaque inscription comme non confirmée et l'outil envoie le lien. - [MailerLite](https://ikiform.com/fr/guides/newsletter-signup/mailerlite.md): Reliez votre propre formulaire d'inscription à MailerLite : un relais ajoute les nouveaux lecteurs comme non confirmés pour le double opt-in, sans jamais demander deux fois à un abonné de confirmer. - [beehiiv](https://ikiform.com/fr/guides/newsletter-signup/beehiiv.md): Reliez votre propre formulaire d'inscription à beehiiv : un relais crée chaque abonnement avec le double opt-in activé, l'emplacement comme source UTM et la page comme referrer. - [Site statique](https://ikiform.com/fr/guides/newsletter-signup/static-site.md): Ajoutez un formulaire d'inscription à la newsletter à un site statique Hugo, Jekyll, Eleventy ou Astro, gardez la clé d'API de l'outil d'e-mailing hors de la page et confirmez dans l'outil. - [Formulaire de newsletter Next.js](https://ikiform.com/fr/guides/newsletter-signup/nextjs.md): Un formulaire de newsletter en pied de page Next.js : une server action avec vérification du consentement et Turnstile, qui envoie à Ikiform, plus un route handler qui ajoute les lecteurs à Kit.