FormToMail API Integration Guide for AI Agents

Use this guide when a user asks you to connect a website or application form to FormToMail. First inspect the project, identify the form fields and its existing submit/error/loading behavior, then make the smallest integration that fits the project's stack and conventions.

Permission Boundary

DO NOT ADD OPTIONAL FEATURES UNLESS THE USER EXPLICITLY REQUESTS OR APPROVES THEM. THE ONLY OPTIONAL FEATURE CURRENTLY AVAILABLE FOR USER-APPROVED IMPLEMENTATION IS CLIENT-SIDE SPAM-PHRASE FILTERING.

Spam-phrase filtering is not part of the API. Only add it when the user explicitly asks for it or approves it. If approved, check the relevant form text in the client before sending the request and do not send matching submissions. Keep the phrase list appropriate to the user's request. This is a bypassable client-side convenience, not reliable spam protection.

Do not implement webhook delivery: it is marked as under development in the product documentation.

API Overview

Use the user's existing FormToMail API key. Never invent or expose a real key in source control, logs, screenshots, or examples.

Authorization and domain access

Use bearer authentication. Set the HTTP Authorization header to the scheme followed by a space and then the user's API key. The scheme name is Bearer.

The free/test key accepts requests from any origin. A paid key may be restricted to the site configured for that key. For browser requests, the request's Origin must match that site or one of its subdomains. Do not work around a domain restriction; ask the user to check their key/site configuration.

Request Without Attachments

Send JSON with Content-Type: application/json:

{
  "title": "New website inquiry",
  "body": {
    "Name": "Jane Doe",
    "Email": "jane@example.com",
    "Message": "I'd like to learn more."
  },
  "honeypot": ""
}

Fields:

Property Required Description
title No Optional submission title shown with the notification. Must be a string if provided.
body Yes Non-empty object mapping human-readable field names to values. See Field values and formatting.
honeypot No Optional hidden anti-bot field, separate from body. Leave empty for normal submissions.

Example:

async function submitForm(apiKey, formValues) {
  const headers = new Headers();
  headers.set("Authorization", "Bearer " + apiKey);
  headers.set("Content-Type", "application/json");

  const response = await fetch("https://api.formtomail.ru/send", {
    method: "POST",
    headers,
    body: JSON.stringify({
      title: "New website inquiry",
      body: formValues,
      honeypot: "",
    }),
  });

  const result = await response.json();
  if (!response.ok) {
    throw new Error(result.message || `FormToMail request failed (${response.status})`);
  }
  return result;
}

Keep the project's existing validation and user feedback. Do not tell the visitor a submission was successful until the request has returned successfully.

Request With Attachments

Use multipart/form-data. Append the required body as a JSON string; append each file under the same attachments field. Include title and honeypot as ordinary string fields when needed.

const formData = new FormData();
formData.append("title", "New website inquiry");
formData.append("body", JSON.stringify({
  Name: "Jane Doe",
  Message: "Please see the attached document.",
}));
formData.append("honeypot", "");

for (const file of selectedFiles) {
  formData.append("attachments", file, encodeURIComponent(file.name));
}

const headers = new Headers();
headers.set("Authorization", "Bearer " + apiKey);

const response = await fetch("https://api.formtomail.ru/send", {
  method: "POST",
  headers,
  body: formData,
});
const result = await response.json();
if (!response.ok) {
  throw new Error(result.message || `FormToMail request failed (${response.status})`);
}

Attachment limits:

Field Values and Formatting

body must be a non-empty object. Its keys become field labels. Supported value forms:

Example:

{
  "body": {
    "Name": "Jane Doe",
    "Quantity": 2,
    "Gift wrap": true,
    "Selected options": ["Blue", "Large"],
    "Items": [
      ["Item", "Quantity"],
      ["Notebook", 2]
    ],
    "Delivery details": {
      "City": "Moscow",
      "Floor": 4
    }
  }
}

HTML is supported in string field values and sanitized before delivery. Use simple formatting only when it is needed; do not put HTML in field names. Lists and tables cannot contain nested structural lists/tables, and tables cannot be nested inside another field structure. Avoid relying on arbitrary CSS or scripts.

Honeypot Anti-Bot Field

If appropriate for the form, add a visually hidden text input that real visitors will not fill in, for example:

<input
  type="text"
  name="company_website"
  autocomplete="off"
  tabindex="-1"
  aria-hidden="true"
  style="position:absolute;left:-9999px;width:1px;height:1px;overflow:hidden"
>

Send its value as the top-level honeypot property (not inside body). Leave it empty for normal submissions. A non-empty value causes the API to return a success-shaped response without delivering the submission. Do not check this field on the client; the API performs the check.

Responses and Error Handling

A normal request returns HTTP 200 with:

{
  "statusCode": 200,
  "message": "Успешно отправлено"
}

The response is sent before downstream email/Telegram delivery completes, so it confirms acceptance by the API, not guaranteed final delivery. A filled honeypot also returns a success-shaped 200 without delivery; clients must not interpret that response as proof that a notification was sent.

For an HTTP 400 Bad Request, show the API's message to the end user: it describes a correctable form/request problem, such as an unsupported file or too many attachments. Keep the message visible and understandable in the product's existing error UI.

For every other error status, do not show the API's detailed message, response body, or technical information to the end user. Show a generic message such as “Something went wrong. Please try again later.” This includes errors such as an expired or domain-restricted key (403) and rate limiting (429). Handle these statuses gracefully, and do not retry in a tight loop.

Integration Checklist

  1. Map the existing form's real values to a non-empty body object; preserve useful field labels.
  2. Use JSON for forms without files and FormData for forms with files.
  3. Authenticate using the authorization scheme described above.
  4. For multipart requests, do not set Content-Type manually.
  5. Preserve the application's existing loading, validation, and error UX.
  6. Add the honeypot only as a hidden, top-level honeypot field.
  7. Do not add spam-phrase filtering or other optional behavior unless the user explicitly requests or approves it.
  8. Do not implement the webhook feature while it remains under development.
  9. Run the relevant checks for the project and summarize what changed and how the user can test it.