Email (SMTP) connector

How to let an agent prepare or send email through your own mail server, with a fixed sender, recipient limits and approval before every send.

Enterprise module

Connectors are an enterprise module. Create an email connector from the Email (SMTP) card in Build → Connectors → Catalog (see Install connector packages).

Console connects to the mail server you name in the settings, signs in with the stored account and builds the message. The connector package never sees the password. The package runs on SaaS and on-prem Consoles, with some differences listed below.

The two tools

Tool	Access	What it does
Draft email (draft_email)	read	Builds the message with the same code as a send and returns exactly what would go out: sender, recipients, subject, body, size and warnings. It contacts no server and sends nothing.
Send email (send_email)	write	Sends one message from the connector's fixed sender address. Returns the message id and the recipients the server accepted and refused.

Both tools are always offered. The agent owner binds the one they want. The connector has no drafts-only mode and no approval setting of its own: it only marks the access of each tool.

send_email is a write tool, so it asks for approval by default. The agent owner can set it to Never ask in the agent's Approvals & questions settings. A run with nobody to approve (a schedule, a channel, an API call without a session) refuses send_email unless it is set to Never ask. draft_email never asks. See Tools and approvals and which tools ask.

Input of both tools: to (1 to 25 recipients), cc, bcc, subject, text and an optional simple html. The sender and the reply-to address come from the settings only. The agent cannot change them.

Set up the connector

1. Open Build → Connectors → Catalog and choose Install on the Email (SMTP) card. It opens the form that creates the connector (see Create and connect).
2. Fill the settings below.
3. Choose a sign-in method and connect. Console connects, negotiates TLS, signs in and quits. It sends no message.

Settings

Setting	Meaning
Mail server	The SMTP server, for example smtp.example.com. The only server the connector can reach.
Security	STARTTLS (usually port 587) (default), Implicit TLS (usually port 465) or No encryption (on-prem only).
Port	1 to 65535. Empty uses the usual port of the security mode: 465, 587 or 25.
Sender address	Required. The sender of every message. The server must allow the account to send as this address.
Sender name	Optional display name, up to 100 characters.
Reply-to address	Optional. Agents cannot set it.
Allowed recipient domains	Optional list of domains, for example example.com or *.example.com. Recipients outside the list are refused. Empty means any recipient, and the draft shows a warning.
Most recipients per message	Advanced. 1 to 25, default 10. To, cc and bcc together, after duplicates are removed.
Messages per hour	Advanced. 1 to 60, default 20. Counted per clock hour for this connector.
CA certificate (PEM)	On-prem, advanced. Certificates of a private CA. Shown for the two encrypted modes.

Which port goes with which security setting:

Port	Security	Meaning
465	Implicit TLS	Encrypted from the first byte.
587	STARTTLS	Starts in clear text and is upgraded to TLS before sign-in. Console requires the upgrade.
25	No encryption (on-prem only)	Nothing is encrypted. Only for a server inside a network you trust.

TLS is always verified (chain and host name, TLS 1.2 or later) for the two encrypted modes.

Sign-in

Method	Use it for
User name and password	A mail server that asks for a user name and password. Usually the user name is the full mailbox address. If the account uses two-step verification, use an app password where your provider offers it. The password is stored encrypted and is never shown to agents or to the connector's code.
Relay without sign-in (trusted network)	A relay that trusts the network address of your Console. On-prem only.

OAuth sign-in (XOAUTH2) is not supported.

Setup notes by provider

Generic SMTP server

1. Set Mail server, Security and Port as in the table above.
2. Set Sender address to an address the account may send as. Otherwise the server refuses the message when an agent sends.
3. Set Allowed recipient domains to limit who an agent can write to.
4. Choose User name and password and connect.

If the server only accepts connections from known addresses, allow the address your Console connects from. On SaaS, your Cognipeer contact can tell you the egress address.

Microsoft 365 (Exchange Online)

• Set Mail server to smtp.office365.com, Security to STARTTLS (usually port 587) and Port to 587. Do not choose Implicit TLS: Microsoft says port 465 does not support the TLS versions that client submission requires.
• Choose User name and password. The user name is the full mailbox address.
• Turn on SMTP AUTH for the sending mailbox. It is enabled per mailbox.
• Set Sender address to that mailbox, or to an address the account has Send As permission for. Otherwise Microsoft refuses the message with the error 5.7.60.
• Security defaults and Conditional Access policies of your tenant can block the sign-in.
• Password sign-in (Basic authentication) for SMTP AUTH is being retired by Microsoft. It works until December 2026, and from the end of December 2026 it is off by default for existing tenants, though an administrator can turn it back on. New tenants after December 2026 do not have it by default. Plan for an SMTP relay on an on-prem Console, and do not build a process that depends on password sign-in lasting.
• Microsoft limits client SMTP submission to 30 messages per minute and 10,000 recipients per day per mailbox. The connector sends at most 10 per minute.

Google Workspace

This covers organisation accounts only.

• First choice, on an on-prem Console with a fixed egress address: the SMTP relay service. Set it up in the Google Admin console so that it accepts your Console's address. In Console, choose Relay without sign-in (trusted network), set Mail server to smtp-relay.gmail.com, Security to STARTTLS (usually port 587), and Sender address to an address in your domain.
• Second choice, only where your admin allows app passwords: turn on 2-Step Verification, create an app password, set Mail server to smtp.gmail.com with STARTTLS and port 587 (or Implicit TLS and port 465), and choose User name and password with the app password. Google limits this route to 2,000 messages per day, and changing the Google Account password revokes all app passwords.
• Google's restricted server (aspmx.l.google.com, port 25, no TLS or sign-in) is not supported.

On-prem relay

For your own relay (for example Postfix, an Exchange receive connector or a mail appliance) that accepts mail from your Console without sign-in.

1. On the relay, allow the address of the Console hosts to relay, choose the port and encryption (prefer encryption), and decide which sender addresses the relay accepts.
2. In Console, fill Mail server, Security and Port. If the relay's certificate comes from your own authority, paste its certificates into CA certificate (PEM).
3. Fill Sender address, and fill Allowed recipient domains. A relay without sign-in does not know who is asking, so the domain list, the recipient cap and Messages per hour are the limits that stay with the connector.
4. Choose Relay without sign-in (trusted network) and connect.

Private server addresses work on an on-prem Console when the operator's network allowance covers them. If the connection is refused before it starts, ask whoever runs your Console.

Message rules

Console checks every draft and send. A message that breaks a rule is refused, never changed, so the draft shows what is sent.

Rule	Value
Recipients	1 to 25 in to, and at most 25 in to, cc and bcc together. At most Most recipients per message after duplicates are removed.
Subject	1 to 200 characters.
Text	Up to 100,000 characters.
HTML	Optional. Up to 100,000 bytes.
Whole message	At most 1,048,576 bytes (1 MiB).
Sender name	Up to 100 characters, without control characters, <, > or ".
Addresses	At most 254 characters. The part before the @ accepts letters, digits and . _ + - only, is at most 64 characters, and does not start, end or repeat a dot. The domain needs at least two labels. No quoted parts, comments, display names or address literals in brackets.
Attachments	Not supported.
Headers	The agent cannot add or change any. Bcc is never written into the message.

HTML is accepted only when it uses simple tags: p, br, h1 to h6, ul, ol, li, a, strong, b, em, i, u, blockquote, code, pre, hr, table, thead, tbody, tr, th, td, span and div. The only attribute is href on a link, and it must start with https: or mailto:. Styles, images, comments, other tags and other attributes are refused.

Console adds an X-Cognipeer-Console header with the first characters of the connector id, so recipients can see the message came from a Console connector.

Rates

Limit	Value
Per connector	10 messages a minute, and Messages per hour (default 20, at most 60). Console's own ceiling is 60 an hour.
Per workspace, all mail connectors together	30 a minute, 300 an hour.
Duplicate window	The same message (recipients, subject, text and HTML) twice is one. The second is refused for 60 seconds after the first. If a send failed after the server may have taken it, the message stays held for 10 minutes.
Sessions at once	2 per connector, 6 per workspace.
Connection attempts	20 a minute per connector. Failed attempts: 6 a minute per connector, 20 per workspace.
Time	10 seconds to reach the server, 45 seconds for the whole request.

A call that hits a rate limit returns how many seconds to wait.

What SaaS does not allow

	SaaS	On-prem
Ports	465, 587, 2525 and ports from 1024 up that are not on the well-known list of other services. Port 25 and every other port below 1024 is refused ("Port 25 is not allowed on this Console; use 587 or 465").	Any port.
Servers	Public addresses only.	Private addresses too, when the operator's network allowance covers them.
No encryption (on-prem only)	Not available.	Available.
Relay without sign-in (trusted network)	Not available.	Available.
CA certificate (PEM)	Not available.	Available.

Preview before you send

Bind Draft email with Send email, or run it alone while you test. The draft returns the sender, the recipients as Console will use them, the subject, the body, the size and warnings (for example that Allowed recipient domains is empty). The recipient sees the message from Sender address. If you set Reply-to address, replies go there.