From 69768a1187c28170fd83ff5bc5a51c2b60680b9f Mon Sep 17 00:00:00 2001 From: duharry0915 <57567430+duharry0915@users.noreply.github.com> Date: Tue, 30 Dec 2025 19:46:03 -0500 Subject: [PATCH 1/2] add documents for SMTP/IMAP server --- fern/docs.yml | 3 + fern/pages/guides/imap-smtp.mdx | 229 ++++++++++++++++++++++++++++++++ 2 files changed, 232 insertions(+) create mode 100644 fern/pages/guides/imap-smtp.mdx diff --git a/fern/docs.yml b/fern/docs.yml index aa261c7..033c113 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -134,6 +134,9 @@ navigation: - page: Sending & Receiving Email icon: fa-solid fa-right-left path: pages/guides/sending-receiving-email.mdx + - page: IMAP & SMTP + icon: fa-solid fa-envelope-open-text + path: pages/guides/imap-smtp.mdx # - page: Semantic Search # path: pages/guides/semantic-search.mdx # - page: Automatic Labeling diff --git a/fern/pages/guides/imap-smtp.mdx b/fern/pages/guides/imap-smtp.mdx new file mode 100644 index 0000000..4141eb1 --- /dev/null +++ b/fern/pages/guides/imap-smtp.mdx @@ -0,0 +1,229 @@ +--- +title: "IMAP & SMTP" +subtitle: "Connect to AgentMail with standard email protocols" +slug: imap-smtp +description: "Configure IMAP and SMTP to access your AgentMail inboxes using email clients or programmatic access." +--- + +AgentMail supports standard IMAP and SMTP protocols, allowing you to connect using traditional email clients or integrate with existing systems that rely on these protocols. + +## What are IMAP and SMTP? + +**IMAP (Internet Message Access Protocol)** and **SMTP (Simple Mail Transfer Protocol)** are the standard protocols that power email communication across the internet. + +- **IMAP** is used to **read and manage emails**. It allows email clients to sync with a mail server, keeping your messages organized across multiple devices. When you check your inbox in Outlook or Thunderbird, you're using IMAP. + +- **SMTP** is used to **send emails**. When you hit "Send" on an email, SMTP handles delivering that message to the recipient's mail server. + +### Why Use IMAP/SMTP with AgentMail? + +- **Email Client Integration**: Connect Outlook, Thunderbird, Apple Mail, or any IMAP/SMTP-compatible client to your AgentMail inbox +- **Programmatic Access**: Send and receive emails using standard libraries (like Python's `imaplib` or `smtplib`) in any programming language +- **Legacy System Integration**: Bridge AgentMail with existing systems that only support IMAP/SMTP protocols +- **Familiar Tooling**: Use email tools you already know during development and testing + +## Finding Your Credentials + +Before configuring IMAP or SMTP, you'll need two pieces of information from the [AgentMail Console](https://console.agentmail.to): + + + + Navigate to **Dashboard → Inboxes** and find the **Inbox ID** column. Your inbox ID is your inbox's email address (e.g., `myinbox@agentmail.to`). This will be your username for IMAP/SMTP authentication. + + + Navigate to **Dashboard → API Keys** and create or copy an API key—this will be your password. + + + +## IMAP Configuration + +Use IMAP to read emails from your AgentMail inbox. + + + SSL/TLS is **required** for all IMAP connections. Connections without SSL will be rejected. Make sure to enable SSL/TLS in your email client settings. + + +| Setting | Value | +|---------|-------| +| **Host** | `imap.agentmail.to` | +| **Port** | `993` | +| **Username** | Your inbox email (e.g., `myinbox@agentmail.to`) | +| **Password** | Your API key | +| **SSL/TLS** | **Required** (must be enabled) | + + + Currently, only the **INBOX** folder is accessible via IMAP. Other folders (Sent, Drafts, Trash) are not available through IMAP. Use the [AgentMail API](/introduction) for full folder access. + + +### Python IMAP Example + +```python +import imaplib +import os +import email + +# Your credentials from AgentMail Console +inbox_email = "myinbox@agentmail.to" # From Dashboard → Inboxes +api_key = os.getenv("AGENTMAIL_API_KEY") # From Dashboard → API Keys + +# Connect with SSL (required) +imap = imaplib.IMAP4_SSL("imap.agentmail.to", 993) + +try: + # Authenticate using inbox email as username + imap.login(inbox_email, api_key) + + # Select INBOX (only supported folder) + imap.select("INBOX") + + # Search for all messages + status, message_ids = imap.search(None, "ALL") + + if status == "OK": + for msg_id in message_ids[0].split(): + # Fetch message + status, msg_data = imap.fetch(msg_id, "(RFC822)") + if status == "OK": + email_body = msg_data[0][1] + message = email.message_from_bytes(email_body) + print(f"Subject: {message['subject']}") +finally: + imap.logout() +``` + +### TypeScript IMAP Example + +```typescript +import Imap from "imap"; + +// Your credentials from AgentMail Console +const inboxEmail = "myinbox@agentmail.to"; // From Dashboard → Inboxes +const apiKey = process.env.AGENTMAIL_API_KEY!; // From Dashboard → API Keys + +const imap = new Imap({ + user: inboxEmail, + password: apiKey, + host: "imap.agentmail.to", + port: 993, + tls: true, // SSL required +}); + +imap.once("ready", () => { + imap.openBox("INBOX", false, (err, box) => { + if (err) throw err; + console.log(`${box.messages.total} messages in INBOX`); + imap.end(); + }); +}); + +imap.once("error", (err: Error) => { + console.error("IMAP error:", err.message); +}); + +imap.connect(); +``` + +## SMTP Configuration + +Use SMTP to send emails from your AgentMail inbox. + + + SSL/TLS is **required** for all SMTP connections. Connections without SSL will be rejected. Make sure to enable SSL/TLS in your email client settings. + + +| Setting | Value | +|---------|-------| +| **Host** | `smtp.agentmail.to` | +| **Port** | `465` | +| **Username** | Your inbox email (e.g., `myinbox@agentmail.to`) | +| **Password** | Your API key | +| **SSL/TLS** | **Required** (must be enabled) | + + + The "From" address in your email should match the email address of your inbox (e.g., `myinbox@agentmail.to`). Using a different From address may result in delivery failures. + + +### SMTP Limits + +- **Max recipients**: 50 per email +- **Max message size**: 10MB +- **Session timeout**: 30 minutes + +### Python SMTP Example + +```python +import smtplib +import os +from email.mime.text import MIMEText +from email.mime.multipart import MIMEMultipart + +# Your credentials from AgentMail Console +inbox_email = "myinbox@agentmail.to" # From Dashboard → Inboxes +api_key = os.getenv("AGENTMAIL_API_KEY") # From Dashboard → API Keys + +# Create message +msg = MIMEMultipart() +msg["Subject"] = "Hello from AgentMail" +msg["From"] = inbox_email # Use your inbox email as the From address +msg["To"] = "recipient@example.com" +msg.attach(MIMEText("This is a test email sent via SMTP.", "plain")) + +# Connect with SSL (required) and send +with smtplib.SMTP_SSL("smtp.agentmail.to", 465) as server: + server.login(inbox_email, api_key) + server.send_message(msg) + print("Email sent successfully!") +``` + +### TypeScript SMTP Example + +```typescript +import nodemailer from "nodemailer"; + +// Your credentials from AgentMail Console +const inboxEmail = "myinbox@agentmail.to"; // From Dashboard → Inboxes +const apiKey = process.env.AGENTMAIL_API_KEY!; // From Dashboard → API Keys + +const transporter = nodemailer.createTransport({ + host: "smtp.agentmail.to", + port: 465, + secure: true, // SSL required + auth: { + user: inboxEmail, + pass: apiKey, + }, +}); + +async function sendEmail() { + const info = await transporter.sendMail({ + from: inboxEmail, // Use your inbox email as the From address + to: "recipient@example.com", + subject: "Hello from AgentMail", + text: "This is a test email sent via SMTP.", + }); + console.log("Email sent:", info.messageId); +} + +sendEmail().catch(console.error); +``` + +## Troubleshooting + +| Error | Cause | Solution | +|-------|-------|----------| +| "Authentication failed" | Invalid credentials | Verify your inbox email and API key from the console | +| "Connection refused" | SSL not enabled | Enable SSL/TLS in your client settings | +| "Connection timeout" | Firewall blocking ports | Ensure ports 993 (IMAP) and 465/587 (SMTP) are open | +| "Sender not authorized" | Wrong From address | Use your inbox's email address as the From address | +| "Folder not found" | Non-INBOX folder | Only INBOX is supported; use the API for other folders | + +## When to Use IMAP/SMTP vs API + +| Use Case | Recommendation | +|----------|----------------| +| Email client integration | IMAP/SMTP | +| Simple programmatic sending | SMTP | +| Full inbox management | API | +| Real-time notifications | API (Webhooks) | +| Access to all folders | API | +| Bulk operations | API | From 12ff74c48268a67f67b072e83d0bc2ce3f609c9b Mon Sep 17 00:00:00 2001 From: duharry0915 <57567430+duharry0915@users.noreply.github.com> Date: Wed, 21 Jan 2026 16:21:12 -0800 Subject: [PATCH 2/2] adding claude skill --- fern/docs.yml | 3 + fern/pages/integrations/claude-skill.mdx | 79 ++++++++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 fern/pages/integrations/claude-skill.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 033c113..8197cc3 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -123,6 +123,9 @@ navigation: # path: pages/integrations/overview.mdx - page: Replit path: pages/integrations/replit.mdx + - page: Claude Skill + icon: fa-solid fa-wand-magic-sparkles + path: pages/integrations/claude-skill.mdx # - page: Smithery # path: pages/integrations/smithery.mdx # - page: Mastra diff --git a/fern/pages/integrations/claude-skill.mdx b/fern/pages/integrations/claude-skill.mdx new file mode 100644 index 0000000..aff8b59 --- /dev/null +++ b/fern/pages/integrations/claude-skill.mdx @@ -0,0 +1,79 @@ +--- +title: "Claude Skill" +description: "Teach Claude how to build email agents with the AgentMail API" +--- + +## What is a Claude Skill? + +A Claude Skill is a "skill pack" that helps Claude (in Cursor, Claude Code, or other IDEs) learn to use specific APIs and tools. It contains documentation, best practices, and code examples that Claude references when helping you build. + +With the AgentMail skill installed, Claude can: +- Build email agents using the AgentMail SDK +- Set up webhooks and websockets for real-time email processing +- Write idempotent, production-ready code +- Avoid common pitfalls (bounce handling, SPF records, etc.) + +## Repository + +**GitHub**: [github.com/agentmail-to/agentmail-claude-skill](https://github.com/agentmail-to/agentmail-claude-skill) + +### Structure + +``` +agentmail-claude-skill/ +├── SKILL.md # Core skill file +└── references/ + ├── api-reference.md # Complete API signatures + ├── webhook-events.md # Event types and payloads + └── examples.md # Advanced agent patterns +``` + +## Installation + +### For Cursor + +```bash +git clone https://github.com/agentmail-to/agentmail-claude-skill.git + +# Create the directory if it doesn't exist +mkdir -p ~/.cursor/skills + +# Global (all projects) +cp -r agentmail-claude-skill ~/.cursor/skills/agentmail + +# Or project-level +cp -r agentmail-claude-skill .cursor/skills/agentmail +``` + +### For Claude Code + +```bash +git clone https://github.com/agentmail-to/agentmail-claude-skill.git + +# Create the directory if it doesn't exist +mkdir -p .claude/skills + +cp -r agentmail-claude-skill .claude/skills/agentmail +``` + +## Usage + +Once installed, Claude automatically uses the skill when you ask about: +- Building email automation +- Creating AI email agents +- Setting up webhooks for email +- Integrating email into AI workflows + +### Example Prompts + +``` +"Build an email agent that auto-replies to incoming messages" + +"Set up a webhook to process emails in real-time" + +"Create a multi-step workflow that tracks conversation state" + +"Send an email with an attachment using AgentMail" +``` + +Claude will reference the skill to write correct, idiomatic AgentMail code.