SMTP configuration: four values that must agree, and what an agent sets instead

The four values

The hostname identifies the submission server, and it is usually distinct from the incoming mail hostname even at the same provider. It comes from the provider's own documentation rather than from the domain's MX record, which points at the servers that receive mail rather than the one that accepts submissions.

The port selects the submission mode. Port 587 is the submission port defined in RFC 6409, where the session upgrades through STARTTLS, and port 465 carries an implicitly encrypted connection recommended for submission in RFC 8314.

The encryption type must match the port. Selecting STARTTLS against 465 fails because that port expects a TLS handshake before any command, and selecting implicit SSL against 587 fails for the mirror-image reason.

The credential is the username and password pair. On most hosted mail the username is the full email address rather than the local part, because one server serves many domains.

What changes when an AI agent sets up an app's email

An agent asked to make an app send email usually reaches for an SMTP settings form or a mailer library and fills in the four values. That leaves the app holding a long-lived mailbox password, an encryption mode guessed from the framework's default rather than read from the provider, and no view of domain alignment or bounces, because none of that passes through the submission session.

The alternative is to send through an API instead of a mailbox login. With Nitrosend, the app calls the transactional email API, the agent works through the MCP server, or a script uses the CLI. What gets configured is a verified sending domain and an API key in the app's environment, not a hostname, port and password. Connecting the MCP server to an agent such as Claude is a one-time step a person does in the client's settings.

The four values are also the background for reading the SMTP commands a session exchanges and the SMTP authentication step that checks the credential.

Gmail as a worked example

Google publishes smtp.gmail.com as the submission host, accepting port 465 with SSL or port 587 with TLS. Authentication is required on both.

Sign in with the full Gmail address as the username, paired with a 16-character app password generated in Google Account security settings, which Google issues only on accounts that have two-step verification enabled.

The account password does not work. Google blocks account passwords for third-party mail clients on accounts with two-step verification, because an SMTP client cannot complete the second factor, so the app password exists to fill that gap, as Google explains on its sign in with app passwords page.

General setup rules

Match the sender address to the authenticated account. A From header that does not correspond to the authenticated mailbox or an authorized domain can be rejected outright and fails alignment checks at the receiver even where it is accepted.

Read the credential from the environment rather than the source. A password in a repository is a live sending credential distributed to everyone with read access, and rotating it is the only remedy afterwards.

Send a test before any real send. A passing test proves the hostname, port, encryption and credential agree, which is the scope of what a configuration can guarantee. A check that validates the settings without attempting the thing the settings are for is not a check, so a preflight that only confirms the fields are filled in can pass while the send itself fails.

On Nitrosend that wider check is nitro_review_delivery, a read-only review that never sends. It runs validation, spam analysis, preflight and previews on the email itself, which a connection test cannot see.

What configuration does not determine

A correct configuration authenticates a client to one server. It says nothing about whether a receiving system will place the resulting message in an inbox, because that decision belongs to the receiver and happens after acceptance.

Domain authentication is a separate layer entirely. SPF, DKIM and DMARC are DNS records published for the sending domain and evaluated by the receiver, and no client setting substitutes for them.

That layer is where a sending domain gets checked. On Nitrosend, nitro_manage_domains adds, verifies and diagnoses the sending domain, and nitro_get_insights reports the email analytics after sends, because none of this is visible from the four submission settings. The IMAP vs SMTP split is similar: the submission settings cover sending, not what happens in the recipient's mailbox.

Acceptance is not delivery. The submission server returning success means it has taken responsibility for the message, and bounces, deferrals and spam filing all happen after that point without notifying the client.

Worked example: an agent moves password-reset email off a mailbox login

The prompt: "Our app sends reset emails through a Gmail app password. Move it to Nitrosend and show me a test first."

Before. The app's mail settings hold smtp.gmail.com, port 587, STARTTLS, the Gmail address and a 16-character app password in .env, and every reset email leaves from a personal mailbox.

After. The app's sending domain is verified once and the app holds a Nitrosend API key in its environment. The agent gets there in a fixed order:

1. nitro_get_status reports whether the account is ready and which sender identity the reset email would leave from.
2. nitro_manage_domains adds the app's own sending domain, verifies it and diagnoses any DNS record still missing.
3. nitro_manage_template creates the reset email as a reusable template with a slot for the reset link.
4. nitro_review_delivery checks the reset template before anything goes out, without sending it.
5. nitro_send_test_message mails one real copy of the reset email to the team's test address. That address is set once in sender defaults with nitro_configure_account, not passed in the call.
6. A person opens the test, follows the link and approves the switch. Until then the app keeps its old settings.
7. The app then calls nitro_send_message once per reset request, reusing the same idempotency_key only when it retries that exact request.
8. nitro_get_insights reports how reset emails perform after the switch, with trends and recommendations.

The app password can then be revoked in the Google account, which removes the last live mailbox credential from the app's environment.

Common configuration failures

Some networks and hosting providers block outbound SMTP, so the first failure can be no answer at all. The list below runs from network causes to the agent-specific ones.

• A timeout is a blocked port. A connection that times out rather than refusing is usually a blocked outbound port, and the symptom is silence rather than an error message.
• Authentication fails after a rotation. A rejection on a previously working setup normally means the credential was revoked or the client fell back to the account password. Regenerating the application-specific credential resolves the ordinary case.
• A policy or blocklist rejection is reputation. Changing the hostname, port or credential has no effect on it, because the receiving server has already decided about the source address.
• Certificate errors are a name or trust problem. They indicate a name mismatch or an outdated trust store rather than a wrong port. Disabling certificate validation removes the protection against an active attacker while leaving the misconfiguration in place.
• The From domain was never verified. It survives a passing connection test. The credential authenticates, the message goes out, and the From address belongs to a domain nobody verified. The fix is to check the template sender against the verified domains when the template is saved and again before it goes live, so the problem is caught while someone is still editing.
• An agent picks implicit TLS on 587. A mailer library's default encryption setting is taken as given, the session expects a STARTTLS upgrade, and the handshake fails before any command.
• An agent commits the app password. The password is written into a config file that lands in the repository instead of the environment, and it stays a live sending credential until someone rotates it.
• An agent cycles ports to fix a blocklist rejection. Trying 465, then 587, then another port changes nothing, because the rejection is about the source address and not the settings.

Common questions

Go deeper