Riferimento API dei moduli

Usi uno strumento di creazione siti? Inizia da Aggiungi un modulo di contatto per i passaggi e un prompt da copiare.

Copia il link modulo dalle impostazioni del progetto. Ha questo aspetto, con l’ID del tuo modulo alla fine:

POST https://mailcontact.app/api/forms/your-form-id

Accetta sia FormData (i dati inviati da un modulo HTML nativo) e application/json. Gli invii consegnati arrivano nella casella e attivano le tue canali di notifica. I messaggi trattenuti nello Spam attendono la revisione senza notifiche né consumo della quota.

Campi

Un campo di testo obbligatorio chiamato company_website deve essere presente e vuoto. Un valore non vuoto identifica traffico bot e l’invio viene scartato senza avviso (è il trappola honeypot contro lo spam). Qualsiasi altro campo sconosciuto viene ignorato.

Lo script inserisce il campo automaticamente nei moduli contrassegnati. Se manca, genera FORM_CHECK_MISSING; un campo compilato viene scartato senza avviso. Un campo vuoto non aggira gli altri controlli antispam, di frequenza o di verifica. Un bot più evoluto può comunque riconoscere la trappola.

Il client ospitato scarta senza avviso una trappola compilata prima di qualsiasi richiesta di configurazione o invio. Restituisce { ok: true } per mantenere la normale conferma, coerente con la risposta antitrap bot dell’endpoint. Le richieste API dirette mantengono la stessa trappola sul server.

Consigliato: usa lo script MailContact

Aggiungi data-mailcontact-form al modulo e carica lo script una volta per pagina. Mantieni gli stili esistenti. Gestisce invio, messaggi accessibili in linea, verifica automatica e nuovi tentativi. Conserva il testo in caso di errore e azzera il modulo solo dopo un successo confermato.

Il gestore automatico blocca altri invii durante l’invio e per 10 secondi dopo un successo confermato. I controlli restano disabilitati e sono bloccati anche gli invii da tastiera. I campi tornano modificabili e la conferma resta visibile. Gli errori consentono un nuovo tentativo immediato salvo che il server fornisca un Retry-After attesa.

<form action="https://mailcontact.app/api/forms/your-form-id" method="POST" data-mailcontact-form>
  <label>Email <input type="email" name="email" maxlength="320" required /></label>
  <label>Message <textarea name="message" maxlength="5000" required></textarea></label>
  <button type="submit">Send</button>
  <p data-contact-status role="status" aria-live="polite" aria-atomic="true"></p>
</form>
<script defer src="https://mailcontact.app/forms/v1.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script>

Uno script supporta più moduli e quelli aggiunti successivamente dal sito. Inserisce il controllo nascosto una volta all’inizializzazione e ne verifica presenza e valore vuoto all’invio. Un campo rimosso o disabilitato blocca l’invio e conserva la bozza. Invia all’attributo di ogni modulo action, indipendentemente da dove è ospitato lo script. Usa HTTPS (o localhost) per la verifica automatica. Il generatore include anche un noscript alternativa; per un’integrazione manuale senza JavaScript, usa l’esempio HTML qui sotto.

Controlli HTML, CSS, etichette e pulsanti. Devono restare uguali solo i nomi degli input supportati; l’API ignora gli altri campi. Imposta data-mailcontact-success="Thanks, we’ll reply soon." sul modulo per personalizzare il testo di conferma. Per un flusso su misura, usa MailContact.send() qui sotto.

Lingua dei messaggi del modulo

Messaggi di invio, verifica, conferma ed errore seguono le preferenze linguistiche del browser. Sono supportati francese, inglese, spagnolo, tedesco, italiano e portoghese, incluse varianti regionali come fr-CA e pt-BR. Si usa la prima lingua del browser supportata; altrimenti i messaggi sono in inglese.

Imposta data-mailcontact-language="fr" su un modulo automatico per forzare il francese, indipendentemente dal browser e dagli altri moduli della pagina. Le lingue supportate impostate esplicitamente prevalgono; valori vuoti o non supportati usano il rilevamento del browser. L’impostazione viene letta a ogni invio. Etichette, contenuto originale del pulsante e data-mailcontact-success restano sotto il tuo controllo; i testi di conferma personalizzati non vengono mai tradotti automaticamente. I messaggi nativi di validazione HTML restano gestiti dal browser.

<form action="https://mailcontact.app/api/forms/your-form-id" method="POST"
  data-mailcontact-form data-mailcontact-language="fr">
  <!-- Keep your existing fields, button and status element here. -->
</form>

I moduli di un account Free mostrano un piccolo link “Processed by mailcontact.app”. Quelli Pro e Plus non hanno attribuzione MailContact. Lo script legge l’impostazione dal piano del proprietario della casella, quindi si aggiorna al cambio piano senza sostituire l’embed. L’impostazione può restare in cache fino a un minuto. Personalizza lo stile del data-mailcontact-branding elemento per adattarlo al sito.

Se il sito usa una Content Security Policy, autorizza l’origine dello script in script-src e l’origine dell’endpoint del modulo in connect-src e form-action. Questo incorporamento non richiede autorizzazioni per JavaScript inline. Il v1 riceve aggiornamenti compatibili; eventuali modifiche incompatibili useranno una nuova versione. Puoi ascoltare l’evento propagato mailcontact:success evento per aggiungere un comportamento personalizzato dopo l’invio.

Interfacce completamente personalizzate

Carica lo stesso script, poi chiama MailContact.send() dal tuo gestore. Ometti data-mailcontact-form così il gestore automatico non modifica l’interfaccia. Controlli passaggi, caricamento, errori e conferme; la funzione gestisce richiesta, verifica firmata e reinvio. Non cambia mai il DOM né cancella i campi.

const endpoint = "https://mailcontact.app/api/forms/your-form-id";
const form = document.querySelector("#contact-form");
MailContact.prepare(form); // Inject once before the visitor fills the form.
const language = form.getAttribute("data-mailcontact-language") || undefined;
const text = MailContact.getMessages(language);
const config = await MailContact.getConfig({ endpoint, language });
// If config.branding is true, show a visible "Processed by mailcontact.app"
// link to https://mailcontact.app in your own form layout.

async function submit() {
  showStatus(text.sending);
  try {
    await MailContact.send({
      endpoint,
      data: new FormData(form),
      language, // Optional: omit for automatic browser language detection.
      onVerification: () => showStatus(text.verification),
      brandingElement: document.querySelector("[data-mailcontact-branding]"),
      // signal: abortController.signal, // optional cancellation
    });
    showYourConfirmation();
  } catch (error) {
    // error.code, error.status and error.retryAfter (seconds or null)
    // let you choose your own translated feedback. Keep the draft.
    showYourError(error);
  }
}

MailContact.prepare(form) aggiunge solo il campo nascosto; non collega gestori d’invio né cambia il design. Chiamalo una volta su ogni modulo montato prima dell’interazione. Non ricrea mai un campo rimosso né cancella un valore esistente. data accetta anche un oggetto con name, email, subject, message e il campo obbligatorio company_website . Il client fotografa i campi per i nuovi tentativi di verifica. Conferma la ricezione o scarta senza avviso una trappola compilata con { ok: true }, e genera MailContact.FormError per gli errori. Le verifiche mancanti usano FORM_CHECK_MISSING, gli errori di rete usano NETWORK_ERROR, annullamento o timeout usano ABORTED. Il timeout è di 60 secondi ed è consentito un solo nuovo tentativo di verifica.

MailContact.getConfig({ endpoint }) effettua una richiesta GET pubblica all’URL del modulo e restituisce solo { branding: true | false }. Le interfacce personalizzate mostrano l’attribuzione quando richiesta e passano il suo elemento come brandingElement (o una funzione che lo restituisce). Ogni invio controlla l’impostazione del server. Su Free, un link assente, nascosto, illeggibile o non cliccabile verso https://mailcontact.app genera BRANDING_REQUIRED prima dell’invio di ogni messaggio; Pro e Plus non richiedono un link. È un controllo d’integrazione nel browser, non una prova sul server del contenuto di pagine terze. Non espone identità o dati di fatturazione del proprietario. React, Vue e altri framework possono chiamare queste funzioni dopo il caricamento dello script; resta disponibile anche l’API grezza.

Il client personalizzato traduce FormError.message automaticamente; code, status e retryAfter restano invariati. Passa language: "fr" a send() o getConfig() per ignorare la lingua del browser. Un gestore personalizzato legge l’attributo del modulo, come sopra. MailContact.getMessages(language?) restituisce il testo localizzato adatto alla tua interfaccia, inclusi sendingButton, sending, verification, success e wait(seconds). Restituisce un oggetto separato affinché il testo personalizzato non modifichi altri moduli. Una prova automatica fallita usa VERIFICATION_FAILED. Non vengono usati servizi di traduzione né richieste linguistiche aggiuntive; le risposte JSON grezze dell’API mantengono codici e lingua esistenti.

Verifica automatica degli invii sospetti

Lo script ospitato gestisce la verifica per te. I client personalizzati possono inviare _verification: "1" per supportare la verifica automatica. Una richiesta sospetta può restituire HTTP 403 con code: CHALLENGE_REQUIRED e una verifica firmata challenge . Non crea messaggi consegnati né addebiti alla quota. Risolvi la sfida e reinvia i campi originali con la soluzione JSON in _proof. Il componente autonomo /form-challenge.js l’helper espone window.mailcontactSolveChallenge(challenge, signal?), che restituisce quella stringa JSON. Le richieste personalizzate sospette con il controllo obbligatorio del modulo ma senza supporto alla verifica restano in Spam per la revisione; omettere tale supporto non aggira mai il controllo.

La prova scade dopo cinque minuti, è legata agli esatti campi, modulo e client ed è accettata una sola volta. Conserva la bozza se la verifica fallisce. I moduli nativi ricevono invece una pagina di verifica automatica. I messaggi molto sospetti arrivano in Spam senza notifiche né consumo di quota; la risposta pubblica di successo non rivela la classificazione.

Modulo HTML semplice

La versione senza JavaScript. Dai ai campi i nomi sopra e il browser fa il resto:

<form action="https://mailcontact.app/api/forms/your-form-id" method="POST">
  <input type="text" name="name" placeholder="Your name" />
  <input type="email" name="email" placeholder="[email protected]" required />
  <input type="text" name="subject" placeholder="Subject" />
  <textarea name="message" placeholder="Your message" required></textarea>
  <button type="submit">Send</button>
  <input name="company_website" type="text" tabindex="-1" autocomplete="off"
    style="position:absolute;left:-10000px" aria-hidden="true" />
</form>

Un invio nativo apre la risposta JSON dell’endpoint in caso di successo o una pagina HTML di verifica quando serve. Invia con il nostro script (sopra) per mantenere i visitatori sulla pagina e mostrare il successo in linea.

JSON con fetch

Invia application/json con un Content-Type header. Stessi campi, stessa convalida:

const res = await fetch("https://mailcontact.app/api/forms/your-form-id", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Ada",
    company_website: "",
    email: "[email protected]",
    subject: "Hello",
    message: "Trying out the endpoint.",
  }),
});

const data = await res.json();
if (data.ok) {
  // show your inline "thanks, message sent" state
}

Puoi anche inviare via POST un FormData oggetto da JavaScript: salta il Content-Type header e passa new FormData(formElement) come corpo.

CORS

CORS è aperto: l’endpoint risponde con Access-Control-Allow-Origin: * e gestisce il OPTIONS preflight: gli invii browser funzionano da qualsiasi origine, come dominio, localhost, staging o hosting statico come GitHub Pages. Nessuna lista di autorizzazione.

Risposte ed errori

In caso di successo l’endpoint restituisce 200 con {"ok": true}. Ciò include anche i messaggi trattenuti in Spam e i controlli compilati scartati senza avviso; non garantisce la consegna nella casella. Gli errori di validazione sono JSON nel formato {"ok": false, "code": "...", "error": "..."}. La verifica usa {"ok": false, "code": "CHALLENGE_REQUIRED", "challenge": {...}}, oppure una pagina HTML per gli invii nativi del browser. JSON malformato, tipi di campo errati, campi duplicati e campi troppo lunghi restituiscono 400:

Limiti

• Il corpo della richiesta è limitato a 64 KB.
• Limite di frequenza: 20 richieste al minuto per IP, persistente ai riavvii; oltre il limite risponde con 429 e Retry-After.
• Limite mittente: 5 invii accettati al minuto per modulo e indirizzo email. Gli invii identici dello stesso mittente sono limitati a uno al minuto; le variazioni di spazi vengono normalizzate.
• Lunghezza dei campi: name 200, subject 300, message 5.000 caratteri (i valori più lunghi sono rifiutati); email oltre 320 caratteri rifiutate.

Free include 50 invii da modulo al mese per un progetto. Pro include 1.000 messaggi condivisi tra dieci progetti; Plus 10.000 tra cinquanta. Messaggi ricevuti e risposte consumano la stessa quota. Le quote mensili sono condivise nell’account; vedi prezzi.

Correlati

È la prima volta? Inizia da Per iniziare. Con Pro e Plus, aggiungi un indirizzo email di contatto che alimentano la stessa casella. Il Protezione antispam spiega come filtrare lo spam da un endpoint aperto. Per uno snippet pronto, prova generatore di moduli di contatto o il guide ai framework.