# 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

- Base URL: `https://api.formtomail.ru`
- Endpoint: `POST /send`
- Purpose: deliver a form submission to the email and Telegram recipients configured for the user's API key.
- The API key is public and is intended to be used in website code. It is not a substitute for protecting private credentials belonging to the integrating application.

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`:

```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](#field-values-and-formatting). |
| `honeypot` | No | Optional hidden anti-bot field, separate from `body`. Leave empty for normal submissions. |

Example:

```js
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.

```js
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:

- Up to 10 files per request.
- Up to 20 MB total.
- Supported extensions: `.jpg`, `.jpeg`, `.png`, `.webp`, `.bmp`, `.gif`, `.mov`, `.mp4`, `.pdf`, `.xls`, `.xlsx`, `.doc`, `.docx`.
- The server checks the file extension and MIME type. Do not silently discard unsupported files; explain the issue to the user or visitor.

## Field Values and Formatting

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

- String, including empty or `null` values; null is rendered as an empty value.
- Finite number.
- Boolean (`true`/`false`).
- Array of strings and booleans, rendered as a bulleted list.
- Array of rows containing strings, finite numbers, or booleans, rendered as a table.
- Object whose values are strings, finite numbers, booleans, or `null`, rendered as a key/value table.

Example:

```json
{
  "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:

```html
<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:

```json
{
  "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.
