formdata.dev

SMTP Connector

The SMTP connector sends form submissions as plain-text emails using the platform SMTP relay over raw TCP sockets via cloudflare:sockets. Tenants configure recipient addresses and subject templates; the worker uses platform-managed SMTP credentials and sender identity.

Config

Field Type Required Default Description
to string[] Yes — One or more recipient email addresses
subjectTemplate string No "Form submission: {{formName}}" Subject line template

Platform SMTP Settings

The worker must be configured with these environment variables:

Variable Description
PLATFORM_SMTP_HOST SMTP server hostname
PLATFORM_SMTP_PORT SMTP server port
PLATFORM_SMTP_SECURE_TRANSPORT TLS mode: off, starttls, or on
PLATFORM_SMTP_USERNAME SMTP auth username
PLATFORM_SMTP_PASSWORD SMTP auth password
PLATFORM_SMTP_FROM_EMAIL Sender email address used for MAIL FROM; the visible From: header uses this address with a form-specific display name

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). 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: Form submission: {{formName}}

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

Email Body Format

The email is sent as a multipart/alternative message with both plain-text and HTML parts. It includes:

  • a stable Message-ID
  • a form-specific From: display name
  • Reply-To when the submission payload includes a valid top-level email
  • metadata headers for the form and submission IDs

The plain-text part looks like this:

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

Add a Destination

With platform SMTP already configured for the worker, add an email destination like this:

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": {
      "to": ["notifications@yourcompany.com"],
      "subjectTemplate": "Form submission: {{formName}}"
    }
  }'

Then test by submitting to your form's ingestion endpoint.

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