SMTP

When to Use#

Use this skill when the user needs to configure, test, send, or debug outbound email over SMTP. It is for submission and delivery work: provider setup, ports and TLS, auth failures, relay denials, canary sends, bounce interpretation, and inbox-placement diagnosis.

Architecture#

Memory lives in ~/smtp/. If ~/smtp/ does not exist, run setup.md. Use memory-template.md, memory.md, provider-profiles.md, send-log.md, and deliverability-notes.md as the local baseline.

text

~/smtp/
├── memory.md               # Status, approved providers, domains, and safety defaults
├── provider-profiles.md    # Known-good hosts, ports, auth mode, and sender identity notes
├── send-log.md             # Dry-run decisions, canary sends, message IDs, and outcomes
└── deliverability-notes.md # SPF, DKIM, DMARC, bounce, and inbox-placement learnings

Quick Reference#

TopicFileUse it forSetup and first-run guardrailssetup.mdInitialize ~/smtp/ without storing secrets or sending mail too earlyMemory structurememory-template.mdCreate ~/smtp/memory.md with status and stable contextBaseline memory examplememory.mdShow the expected shape of a live SMTP memory fileProvider profile baselineprovider-profiles.mdTrack approved providers, ports, auth modes, and sender identitiesSend decision log baselinesend-log.mdRecord dry runs, canaries, queue IDs, and verification evidenceDeliverability notes baselinedeliverability-notes.mdCapture DNS auth status, spam-folder evidence, and bounce patternsSafe execution workflowsend-flow.mdRun draft -> preflight -> canary -> verify -> scaleFault isolation guidediagnostic-playbook.mdSeparate DNS, TLS, auth, relay, and placement failuresDeliverability rulesdeliverability.mdCheck SPF, DKIM, DMARC, alignment, and inbox placementCLI probe patternsswaks-recipes.mdUse deterministic SMTP tests with placeholder-only examples

Requirements#

• SMTP host access only when the user wants real network testing or live sending.
• Credentials must come from a user-approved secret source at runtime, never from files under ~/smtp/.
• Recommended tools: swaks for SMTP probes, openssl for TLS inspection, and dig or nslookup for DNS checks.
• Explicit confirmation before any live send, external-recipient test, or multi-recipient action.

Core Rules#

1. Separate Draft, Probe, and Live Send#

• Decide which mode the task is in before touching the network: draft-only, connectivity probe, auth probe, canary send, or live send.
• Draft and explain first. Do not jump from "help me configure SMTP" to "message sent."

2. Match Port, TLS, and Auth Exactly#

• Port 465 means implicit TLS. Port 587 usually means STARTTLS. Port 25 is relay transport and is often blocked or policy-limited.
• Treat host, port, TLS mode, and auth mechanism as one contract. A single mismatch can look like a generic timeout or auth error.

3. Debug One Layer at a Time#

• Validate in order: DNS and hostname, TCP reachability, TLS handshake, EHLO capabilities, auth, submission response, then mailbox placement.
• Do not tweak deliverability records before proving the connection and auth layers are healthy.

4. Keep Sender Identity Aligned#

• Check whether the authenticated account, envelope sender, visible From address, DKIM domain, and return-path domain actually belong together.
• Misalignment often produces 550/553 rejections, spam placement, or "sent successfully" with no inbox result.

5. Canary Before Scale#

• The first live test should target one approved canary recipient, ideally on the same org or a controlled inbox.
• Only widen recipients after you have queue acceptance, message ID evidence, and inbox-or-spam confirmation.

6. Handle Credentials and Logs Safely#

• Never write raw SMTP passwords, API tokens, or full secrets into ~/smtp/.
• Redact logs and screenshots before storing or sharing them. Keep only the smallest evidence needed to debug.

7. Acceptance Is Not Delivery#

• A 250 queued or similar server response means the SMTP server accepted the message, not that the recipient inbox accepted it.
• Always verify final state through bounce evidence, mailbox placement, or downstream provider logs when available.

Common Traps#

TrapWhy It FailsBetter MoveTreating port 465 and 587 as interchangeableTLS handshake breaks or auth never startsMatch implicit TLS vs STARTTLS explicitlyChanging SPF before fixing authWrong layer, no effect on login failureProve DNS, TLS, and auth separatelyAssuming 250 means inbox successQueue acceptance is not mailbox placementCheck spam, bounces, and final recipient evidenceUsing external recipients as the first testIncreases blast radius and riskStart with one approved canary inboxDisabling certificate checks to "make it work"Hides real TLS or hostname issuesFix hostname, CA trust, or port selection insteadLetting From differ wildly from auth identityTriggers relay denial or spam scoringAlign sender identity or document the relay policy

External Endpoints#

EndpointData SentPurposeConfigured SMTP submission server, such as smtp.example.comMessage headers, recipients, body, and attachments only for approved live tests or sendsSubmit or test outbound mailDNS resolvers or authoritative nameservers for the sender domainDomain names and record lookups for SPF, DKIM, DMARC, MX, and PTR checksDiagnose deliverability and domain alignment

No other data should be sent externally unless the user explicitly approves broader tooling.

Data Storage#

Local state in ~/smtp/ includes:

• activation state, approved providers, and safety defaults in memory.md
• known-good server profiles and sender-identity notes in provider-profiles.md
• dry-run decisions, canary evidence, and message IDs in send-log.md
• domain-auth and placement findings in deliverability-notes.md

Security & Privacy#

Data that leaves your machine:

• SMTP envelope and message content only during approved probes or live sends
• DNS queries needed to validate sender-domain health and routing

Data that stays local:

• safe defaults and approved provider context in ~/smtp/memory.md
• known-good provider settings and debugging evidence in ~/smtp/provider-profiles.md, ~/smtp/send-log.md, and ~/smtp/deliverability-notes.md

This skill does NOT:

• send live mail without explicit confirmation
• store raw SMTP passwords or tokens in local memory
• modify DNS records, mailing lists, or provider settings unless the user explicitly asks
• disable TLS verification silently
• modify its own skill definition

Trust#

By using this skill, approved message content is sent to the configured SMTP provider and related DNS infrastructure. Only install and run it if you trust those providers with your outbound mail flow.

Scope#

This skill ONLY:

• helps configure and diagnose outbound SMTP submission
• maintains small local notes in ~/smtp/
• runs canary-first send workflows with explicit confirmation gates

This skill NEVER:

• guess live-send approval from vague user intent
• keep credentials in ~/smtp/
• treat queue acceptance as the final delivery result
• broaden a one-off test into a bulk-send workflow without consent

Related Skills#

Install with clawhub install <slug> if user confirms:

• mail - broader mailbox operations across IMAP, SMTP, and Apple Mail workflows
• dns - deeper DNS record work for SPF, DKIM, DMARC, MX, and TTL changes
• network - port reachability, TLS, and connection debugging beyond mail workflows
• newsletter - message design and campaign structure once SMTP delivery is healthy
• email-marketing - deliverability and audience strategy after the send path is stable

Feedback#

• If useful: clawhub star smtp
• Stay updated: clawhub sync