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/3] 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 3d20f5c7c7b9be768aed54a8b964f0113c34795a Mon Sep 17 00:00:00 2001 From: duharry0915 <57567430+duharry0915@users.noreply.github.com> Date: Sun, 4 Jan 2026 19:53:05 -0500 Subject: [PATCH 2/3] adding explaination for organization --- fern/docs.yml | 4 ++ fern/pages/core-concepts/organizations.mdx | 81 ++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 fern/pages/core-concepts/organizations.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 033c113..003c86a 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -95,6 +95,9 @@ navigation: # path: pages/get-started/what-is-agentmail.mdx - section: Core Concepts contents: + - page: Organizations + icon: fa-solid fa-building + path: pages/core-concepts/organizations.mdx - page: Inboxes icon: fa-solid fa-inbox path: pages/core-concepts/inboxes.mdx @@ -239,6 +242,7 @@ navigation: python: agentmail typescript: agentmail layout: + - organizations - inboxes - threads - messages diff --git a/fern/pages/core-concepts/organizations.mdx b/fern/pages/core-concepts/organizations.mdx new file mode 100644 index 0000000..6d77463 --- /dev/null +++ b/fern/pages/core-concepts/organizations.mdx @@ -0,0 +1,81 @@ +--- +title: Organizations +subtitle: The top-level container for all your AgentMail resources. +slug: organizations +description: Learn how Organizations serve as the root entity that contains all your Inboxes, Domains, and API keys. +--- + +## What is an Organization? + +An `Organization` is the top-level entity in AgentMail that acts as a container for all your resources. When you sign up for AgentMail, an organization is automatically created for you. + +Your organization holds: +- **Inboxes**: All the email accounts your agents use +- **Domains**: Custom domains you've configured for sending emails +- **API Keys**: Credentials for programmatic access +- **Pods**: Groups of inboxes for organization + +## Usage Limits + +Each organization has configurable limits that control how many resources you can create: + +| Property | Description | +|----------|-------------| +| `inbox_count` | Current number of inboxes in your organization | +| `domain_count` | Current number of domains configured | +| `inbox_limit` | Maximum number of inboxes allowed | +| `domain_limit` | Maximum number of domains allowed | + + + Need higher limits? Contact us at [support@agentmail.cc](mailto:support@agentmail.cc) to discuss your requirements. + + +## Retrieving Your Organization + +You can retrieve your organization details to check your current usage and limits: + + + +```python +from agentmail import AgentMail + +# Initialize the client +client = AgentMail(api_key="YOUR_API_KEY") + +# Get your organization details +org = client.organizations.get() + +print(f"Organization ID: {org.organization_id}") +print(f"Inboxes: {org.inbox_count} / {org.inbox_limit or 'unlimited'}") +print(f"Domains: {org.domain_count} / {org.domain_limit or 'unlimited'}") +``` + +```typescript +import { AgentMailClient } from "agentmail"; + +// Initialize the client +const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" }); + +// Get your organization details +const org = await client.organizations.get(); + +console.log(`Organization ID: ${org.organizationId}`); +console.log(`Inboxes: ${org.inboxCount} / ${org.inboxLimit ?? "unlimited"}`); +console.log(`Domains: ${org.domainCount} / ${org.domainLimit ?? "unlimited"}`); +``` + + + +## Organization Response + +The `get` endpoint returns the following fields: + +| Field | Type | Description | +|-------|------|-------------| +| `organization_id` | string | Unique identifier for your organization | +| `inbox_count` | integer | Current number of inboxes | +| `domain_count` | integer | Current number of domains | +| `inbox_limit` | integer (optional) | Maximum inboxes allowed | +| `domain_limit` | integer (optional) | Maximum domains allowed | +| `created_at` | datetime | When the organization was created | +| `updated_at` | datetime | When the organization was last updated | From def46f9ccbab7afe28a790a3e0142be35c363241 Mon Sep 17 00:00:00 2001 From: duharry0915 <57567430+duharry0915@users.noreply.github.com> Date: Tue, 6 Jan 2026 16:43:30 -0500 Subject: [PATCH 3/3] update on documents --- fern/pages/core-concepts/organizations.mdx | 31 +++++----------------- 1 file changed, 7 insertions(+), 24 deletions(-) diff --git a/fern/pages/core-concepts/organizations.mdx b/fern/pages/core-concepts/organizations.mdx index 6d77463..50d78fd 100644 --- a/fern/pages/core-concepts/organizations.mdx +++ b/fern/pages/core-concepts/organizations.mdx @@ -15,24 +15,9 @@ Your organization holds: - **API Keys**: Credentials for programmatic access - **Pods**: Groups of inboxes for organization -## Usage Limits - -Each organization has configurable limits that control how many resources you can create: - -| Property | Description | -|----------|-------------| -| `inbox_count` | Current number of inboxes in your organization | -| `domain_count` | Current number of domains configured | -| `inbox_limit` | Maximum number of inboxes allowed | -| `domain_limit` | Maximum number of domains allowed | - - - Need higher limits? Contact us at [support@agentmail.cc](mailto:support@agentmail.cc) to discuss your requirements. - - ## Retrieving Your Organization -You can retrieve your organization details to check your current usage and limits: +You can retrieve your organization details programmatically: @@ -46,8 +31,7 @@ client = AgentMail(api_key="YOUR_API_KEY") org = client.organizations.get() print(f"Organization ID: {org.organization_id}") -print(f"Inboxes: {org.inbox_count} / {org.inbox_limit or 'unlimited'}") -print(f"Domains: {org.domain_count} / {org.domain_limit or 'unlimited'}") +print(f"Created at: {org.created_at}") ``` ```typescript @@ -60,8 +44,7 @@ const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" }); const org = await client.organizations.get(); console.log(`Organization ID: ${org.organizationId}`); -console.log(`Inboxes: ${org.inboxCount} / ${org.inboxLimit ?? "unlimited"}`); -console.log(`Domains: ${org.domainCount} / ${org.domainLimit ?? "unlimited"}`); +console.log(`Created at: ${org.createdAt}`); ``` @@ -73,9 +56,9 @@ The `get` endpoint returns the following fields: | Field | Type | Description | |-------|------|-------------| | `organization_id` | string | Unique identifier for your organization | -| `inbox_count` | integer | Current number of inboxes | -| `domain_count` | integer | Current number of domains | -| `inbox_limit` | integer (optional) | Maximum inboxes allowed | -| `domain_limit` | integer (optional) | Maximum domains allowed | | `created_at` | datetime | When the organization was created | | `updated_at` | datetime | When the organization was last updated | + + + We're actively building more organization-level features. Stay tuned for upcoming updates! +