SMTP

Connect SMTP to send receipts, contact-form notifications, and other app emails through your existing mail provider. SMTP (Simple Mail Transfer Protocol) is the protocol mail servers use to send email. Swarmz stores the credentials encrypted behind the connector gateway, so your app and AI chat don't receive the SMTP password.

This is a shared project connection: app emails use the connected sending account. It doesn't give each app user their own mailbox connection. Use the Gmail connector if you need Gmail account access through Google sign-in.

Before you start

You need permission to manage workspace connections and an SMTP provider that accepts username-and-password authentication (AUTH LOGIN) over TLS, the encryption used to protect the connection. Have these ready:

• Your provider's SMTP host, port, username, and SMTP password or app password.
• A sender address that the provider permits you to use. Complete its sender or domain verification first.
• An inbox you control for a test email.

The server must be reachable on the public internet. Localhost, private network addresses, and hostnames that resolve to private addresses are blocked.

An administrator must enable SMTP for your workspace's platform before it appears in Settings > Integrations. If it is missing, ask your administrator to check connector availability. SMTP uses service credentials and doesn't require a Swarmz OAuth application.

Connect your SMTP server

1. Open Settings > Integrations, select SMTP, then select Add connection.

2. Give the connection a recognizable display name, such as App receipts.

3. Enter all four connection fields:

   Field	What to enter
   SMTP host	Your provider's hostname, such as smtp.example.com. Enter the host only, without https://, a path, or a port.
   Port	465 or 587, matching your provider's instructions.
   Username	The provider's SMTP username. This may differ from your account login or sender address.
   Password	The provider's SMTP password, SMTP key, or supported app password. Enter it in this form, never in AI chat or project source.

4. Select Save connection.

5. Open your project and ask the AI to use this SMTP connection for its email action. Select the saved connection if prompted, then run the test below.

Swarmz selects encryption from the port; there is no separate encryption setting:

Ports 25 and 2525 aren't supported. Swarmz doesn't fall back to unencrypted sending.

Find your provider's credentials

Use the SMTP settings from your provider rather than its website password or HTTP API credentials.

For a custom sending domain, complete the provider's domain-authentication instructions, including the DNS records it requires. The SMTP connector doesn't configure those records for you.

Send a test email

Replace the addresses in this prompt with your permitted sender and an inbox you control:

Use my App receipts SMTP connection to send one test email from receipts@example.com to tester@example.net. Use the subject "SMTP setup test" and the plain-text body "This is a test from my Swarmz project."

Sending is a write action. By default, the AI asks for approval before sending in chat; workspace tool permissions can change this behavior. Approve only after checking the sender, recipient, and content.

Check the result in three places:

1. Confirm the connector reports that the SMTP server accepted the email.
2. Check the provider's sending logs, if available, for rejection, deferral, or bounce information.
3. Open the recipient inbox, including its spam folder, and verify the subject, body, and displayed sender. If you set a reply-to address, verify that replying uses it.

An accepted result means the SMTP server accepted the message for delivery. It doesn't confirm arrival in the inbox. The returned message ID may be null.

Use SMTP in your app

Tell the AI what event should send an email, who should receive it, and which sender to use. For example:

Use our shared SMTP connection to email the signed-in customer a receipt after a verified payment webhook succeeds. Send from receipts@example.com, show "Example Store" as the sender name, and direct replies to support@example.com. Send from the server and prevent duplicate receipts for the same payment.

For a contact form, keep your permitted sender address in from and put the visitor's validated email address in reply_to. Using an arbitrary visitor address as the sender can cause provider rejection.

Generated server code uses the connector gateway. Keep its project gateway key on the server, and enforce your app's authorization rules before sending. SMTP supports the shared connection mode; it doesn't support per-user SMTP credentials for published app users.

Connecting SMTP doesn't automatically replace your authentication service's signup, password-reset, or magic-link emails. Configure those in the service responsible for authentication.

Supported email fields and limits

The connector exposes one operation, send_email, which sends to one recipient per call.

At least one body must contain non-whitespace content. The combined text and html limit is 1,000,000 UTF-8 bytes. Use bare email addresses in address fields and put the display name in from_name. Header fields can't contain line breaks or control characters.

The operation input looks like this. Replace the example addresses before sending; this is the email payload, not connection credentials:

{
  "from": "receipts@example.com",
  "from_name": "Example Store",
  "to": "tester@example.net",
  "reply_to": "support@example.com",
  "subject": "SMTP setup test",
  "text": "This is a test from my Swarmz project.",
  "html": "<p>This is a test from my Swarmz project.</p>"
}

The gateway allows 30 send_email requests per minute for each project gateway key, project, and connection combination. Your provider's sending quotas also apply.

Recipient lists, CC, BCC, attachments, custom headers, scheduled sending, inbox reads, and delivery-event lookup aren't supported by this connector. Check delivery in your provider's tools.

Troubleshoot setup and sending

SMTP has no read operation. For the connector verification checklist, use a controlled test email in place of the usual read test.

Update credentials or disconnect

To rotate credentials, open Settings > Integrations > SMTP and select the saved connection. Re-enter all four SMTP fields, including the new password, then select Save changes. The saved secret isn't prefilled, and changing a credential requires the complete set of fields.

Send another controlled test email before revoking the previous credential, if your provider permits both to remain active during rotation. If the old credential is exposed, revoke it immediately and update the connection before resuming sends.

To stop using the connection, open it and select Remove, then confirm removal. This blocks future use of that connection; it doesn't recall messages already accepted by the mail server. Revoke an unused SMTP credential with the provider as well.