formdata.dev

SMTP Connector

The SMTP connector sends form submissions as plain-text emails using raw TCP sockets via cloudflare:sockets. It supports STARTTLS and AUTH LOGIN authentication.

Config

Field Type Required Default Description
host string Yes — SMTP server hostname
port number Yes — SMTP server port (1 - 65535)
secureTransport string No "starttls" TLS mode: off, starttls, or on
username string Yes — SMTP auth username
password string Yes — SMTP auth password
from string Yes — Sender email address
to string[] Yes — One or more recipient email addresses
subjectTemplate string No "New submission: {{formName}}" Subject line template

TLS Modes

Mode Behavior
starttls Connect in plaintext, upgrade to TLS after STARTTLS command (port 587)
on Connect with TLS immediately (port 465)
off No TLS — plaintext only (not recommended)

Authentication

The connector uses AUTH LOGIN (Base64-encoded username and password). This is the most widely supported SMTP auth mechanism. The SMTP conversation follows this sequence:

  1. EHLO formdata.dev
  2. STARTTLS (if secureTransport is starttls)
  3. TLS upgrade, then EHLO formdata.dev again
  4. AUTH LOGIN with Base64 credentials
  5. MAIL FROM / RCPT TO / DATA
  6. QUIT

Subject Template Variables

The subjectTemplate field supports two variables:

Variable Replaced With Example Output
{{formName}} The form's display name New submission: Contact Form
{{submissionId}} The submission UUID Submission a1b2c3d4-...

Default template: New submission: {{formName}}

Custom example: [{{formName}}] Submission {{submissionId}}

Email Body Format

The email is sent as text/plain; charset=UTF-8 with this structure:

Form: Contact Form Submission ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890 Submitted At: 2026-03-18T12:00:00.000Z Origin: https://example.com IP: 203.0.113.42 Payload: { "name": "Jane Doe", "email": "[email protected]", "message": "Hello!" }

Gmail Setup

App Passwords

Gmail requires an App Password when using SMTP with 2FA enabled. Regular account passwords will not work.

  1. Enable 2-Step Verification on your Google account
  2. Go to App Passwords and generate one for "Mail"
  3. Add the SMTP destination:
curl -X POST https://api.formdata.dev/v1/admin/forms/FORM_ID/destinations \
  -H "Content-Type: application/json" \
  -H "x-tenant-key: sk_live_abc123..." \
  -d '{
    "type": "smtp",
    "config": {
      "host": "smtp.gmail.com",
      "port": 587,
      "secureTransport": "starttls",
      "username": "[email protected]",
      "password": "your-16-char-app-password",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subjectTemplate": "New submission: {{formName}}"
    }
  }'
  1. Test by submitting to your form's ingestion endpoint.

Amazon SES Setup

  1. Verify your sender domain or email in the SES console
  2. Create SMTP credentials in the SES console (SMTP Settings section). SES generates a username and password for you.
  3. Add the SMTP destination:
curl -X POST https://api.formdata.dev/v1/admin/forms/FORM_ID/destinations \
  -H "Content-Type: application/json" \
  -H "x-tenant-key: sk_live_abc123..." \
  -d '{
    "type": "smtp",
    "config": {
      "host": "email-smtp.us-east-1.amazonaws.com",
      "port": 587,
      "secureTransport": "starttls",
      "username": "AKIAIOSFODNN7EXAMPLE",
      "password": "your-ses-smtp-password",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subjectTemplate": "[{{formName}}] New submission"
    }
  }'
SES Region

Replace us-east-1 with your SES region. Use the SMTP endpoint from the SES console.

Common SMTP Ports

Port TLS Mode Typical Use
587 starttls Submission (recommended)
465 on Implicit TLS
25 off Relay (usually blocked by providers)
ON THIS PAGE