# FormSMTP API reference

FormSMTP sends email from websites and apps through the customer's own SMTP account (Gmail, Outlook, Zoho, Amazon SES, Brevo, Resend, any SMTP server). Every project has one API key, a From address and its SMTP settings. Dashboard: https://app.formsmtp.com

## HTML form endpoint (no JavaScript)

POST https://app.formsmtp.com/api/v1/form/<API_KEY> with a normal HTML form (application/x-www-form-urlencoded) or JSON.
Every field is emailed to the project owner (first full address under "Allowed recipients", otherwise the From address). A visitor can never pick the recipient, so the key can sit in public HTML.

Special fields:
- _subject: subject line (default "New form submission from <site>")
- _next: redirect after success, same site only
- _replyto: reply-to address (defaults to a field named "email")
- _to: choose one of several inboxes; only used if it matches "Allowed recipients"
- _gotcha: honeypot, keep it hidden; bot submissions are silently dropped

Send "Accept: application/json" to get {"success": true} instead of a thank-you page. File uploads are not supported.

## Send API

POST https://app.formsmtp.com/api/v1/send
Headers: Authorization: Bearer <API_KEY>, Content-Type: application/json

Body fields:
- to (required): "a@x.com", "Name <a@x.com>", comma-separated string, or array
- subject (required unless the template has one)
- html and/or text (required unless template is given)
- template: template name or id from the dashboard
- variables: object for the template's {{variables}}
- cc, bcc: same format as "to"; at most 50 recipients in total
- replyTo: reply-to address
- fromName: display-name override (the address is always the project's From email)
- attachments: [{ "filename", "content": "<base64>", "contentType" }], 15 MB request limit

Success: 200 {"success": true, "messageId": "..."}
Errors: {"success": false, "error": "..."} with status 400 (invalid), 401 (bad key), 403 (website/recipient not allowed or project off), 404 (template not found), 429 (hourly limit; Retry-After header), 502 (SMTP server refused; message says why).

## Contacts API

POST https://app.formsmtp.com/api/v1/contacts with {"email", "name", "tags": [...], "fields": {...}} adds or updates a contact (tags and fields are merged). Use it for newsletter and waitlist forms. Contacts can then be emailed by tag from the dashboard, now or on a schedule, each with a working unsubscribe link.

## Templates and variables

Templates are designed in the dashboard (visual builder or raw HTML) and sent by name.
Variables: {{name}} or with a fallback {{first_name|there}}. If the recipient is a contact, their name, first_name, email and custom fields are filled in automatically, plus {{unsubscribe_url}}.

## Securing a key that is used in a browser

Settings → Security in the dashboard:
- Allowed websites: origins allowed to call the API from a browser
- Allowed recipients: addresses or @domains that may receive email (for a contact form, list only yourself)
- Max emails per hour: caps what a copied key can send
For server-side code, leave Allowed websites empty and keep the key in an environment variable.

## MCP server for AI assistants

Remote MCP endpoint (Streamable HTTP): https://app.formsmtp.com/mcp
Sign in with OAuth (Claude, ChatGPT, Claude Code, Cursor, VS Code) or send an AI key from the dashboard (AI & MCP page) as "Authorization: Bearer <AI key>". Project API keys do not work on the MCP endpoint.
Tools: list_projects, get_stats, list_emails, list_templates, get_template, list_contacts, list_scheduled_emails, check_deliverability, get_integration_guide, send_email, create_template, update_template, add_contact, set_contact_subscription, schedule_email, cancel_scheduled_email.