-
Notifications
You must be signed in to change notification settings - Fork 13
Knowledge base #99
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Knowledge base #99
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
63d0d80
draft for knowledge base
duharry0915 c091b63
adding 2/3 of knowledge base
duharry0915 4010d51
update on V1 of knowledge base
duharry0915 34f4c46
Merge branch 'main' into knowledgeBase
duharry0915 29292f8
update on the grammer fix
duharry0915 44d2231
update on grammer
duharry0915 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| --- | ||
| title: "How do I set up allowlists and blocklists?" | ||
| subtitle: Control who your AI agent can send to and receive from. | ||
| slug: knowledge-base/allowlists-blocklists | ||
| --- | ||
|
|
||
| Allowlists and blocklists let you control who your AI agent can communicate with. This is a critical safety feature for autonomous agents running in production with minimal human oversight. | ||
|
|
||
| ## How Lists work | ||
|
|
||
| AgentMail provides four list types based on two dimensions, **direction** (send or receive) and **type** (allow or block): | ||
|
|
||
| | List | What it does | | ||
| | --- | --- | | ||
| | Receive allow | Only accept emails from these addresses or domains | | ||
| | Receive block | Reject emails from these addresses or domains | | ||
| | Send allow | Only send emails to these addresses or domains | | ||
| | Send block | Prevent sending emails to these addresses or domains | | ||
|
|
||
| Each entry can be either a full email address (e.g., `partner@example.com`) or an entire domain (e.g., `example.com`). | ||
|
|
||
| ## Setting up lists via the SDK | ||
|
|
||
| ### Add an entry | ||
|
|
||
| ```python title="Python" | ||
| from agentmail import AgentMail | ||
|
|
||
| client = AgentMail() | ||
|
|
||
| # Allow receiving from a specific domain | ||
| client.lists.create("receive", "allow", entry="trusted-corp.com") | ||
|
|
||
| # Block a specific sender (with optional reason) | ||
| client.lists.create("receive", "block", entry="spam@example.com", reason="spam") | ||
|
|
||
| # Restrict sending to only certain addresses | ||
| client.lists.create("send", "allow", entry="verified-prospect@example.com") | ||
|
|
||
| # Prevent sending to a domain | ||
| client.lists.create("send", "block", entry="competitor.com") | ||
| ``` | ||
|
|
||
| ### List entries | ||
|
|
||
| ```python title="Python" | ||
| # View all entries in a list | ||
| entries = client.lists.list("receive", "allow") | ||
| ``` | ||
|
|
||
| ### Remove an entry | ||
|
|
||
| ```python title="Python" | ||
| client.lists.delete("receive", "block", entry="spam@example.com") | ||
| ``` | ||
|
|
||
| ## Common patterns for agents | ||
|
|
||
| **Outreach agent:** Use a send allowlist to restrict your agent to only email verified prospects. This prevents the agent from accidentally emailing the wrong people. | ||
|
|
||
| ```python title="Python" | ||
| # Only allow sending to verified prospects | ||
| for prospect in verified_prospects: | ||
| client.lists.create("send", "allow", entry=prospect.email) | ||
| ``` | ||
|
|
||
| **Personal Agent (Openclaw, Manus, etc.):** Use a receive allowlist to restrict your agent to only respond to emails from specific people or domains. | ||
|
|
||
| ```python title="Python" | ||
| # Only accept emails from your own address and trusted domains | ||
| client.lists.create("receive", "allow", entry="you@yourcompany.com") | ||
| client.lists.create("receive", "allow", entry="trusted-partner.com") | ||
| ``` | ||
|
|
||
| **Anti-spam:** Use a receive blocklist to filter out known spam senders or unwanted automated emails. | ||
|
|
||
| ```python title="Python" | ||
| # Block known spam domains | ||
| client.lists.create("receive", "block", entry="spam-domain.com", reason="spam") | ||
| ``` | ||
|
|
||
| ## Why this matters for agents | ||
|
|
||
| Without guardrails, an autonomous agent could email the wrong people, respond to phishing attempts, or get caught in infinite email loops with another bot. Lists are your safety rails. They are especially important for: | ||
|
|
||
| - **Production agents** operating with minimal human oversight | ||
| - **Outreach agents** that should only contact approved recipients | ||
| - **Support agents** that should only respond to known customers | ||
| - **Any agent** that needs protection from spam, phishing, or abuse | ||
|
|
||
| For more details on the Lists API, see the [Lists core concept](/lists) documentation. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,96 @@ | ||
| --- | ||
| title: "How do I create my first inbox?" | ||
| subtitle: Get up and running with your first AgentMail inbox. | ||
| slug: knowledge-base/creating-first-inbox | ||
| --- | ||
|
|
||
| Creating an inbox gives your AI agent its own email address. You can create inboxes on the default `@agentmail.to` domain or on your own custom domain. | ||
|
|
||
| ## Install the SDK | ||
|
|
||
| ```bash title="TypeScript" | ||
| npm install agentmail | ||
| ``` | ||
|
|
||
| ## Create an inbox | ||
|
|
||
| ```typescript title="TypeScript" | ||
| import { AgentMailClient } from "agentmail"; | ||
|
|
||
| const client = new AgentMailClient({ apiKey: "am_..." }); | ||
|
|
||
| // Create an inbox with a random address on agentmail.to | ||
| const inbox = await client.inboxes.create(); | ||
| console.log(`Inbox created: ${inbox.inboxId}`); | ||
| ``` | ||
|
|
||
| The inbox now has a unique email address (e.g., `randomname@agentmail.to`) and can send and receive emails immediately. | ||
|
|
||
| ## Customize your inbox | ||
|
|
||
| You can specify a username, domain, and display name: | ||
|
|
||
| ```typescript title="TypeScript" | ||
| const inbox = await client.inboxes.create({ | ||
| username: "support", | ||
| domain: "yourcompany.com", | ||
| displayName: "Support Agent", | ||
| }); | ||
|
|
||
| // inbox.inboxId will be support@yourcompany.com | ||
| console.log(`Inbox created: ${inbox.inboxId}`); | ||
| ``` | ||
|
|
||
| <Note> | ||
| Using a custom domain requires a verified domain. See the [Creating Custom Domains](/custom-domains) guide to set one up. If you don't specify a domain, AgentMail uses the default `@agentmail.to` domain. | ||
| </Note> | ||
|
|
||
| ## Use client_id for idempotency | ||
|
|
||
| If your agent creates inboxes programmatically (e.g., on startup), use `clientId` to prevent duplicates. If an inbox with the same `clientId` already exists, AgentMail returns the existing inbox instead of creating a new one: | ||
|
|
||
| ```typescript title="TypeScript" | ||
| const inbox = await client.inboxes.create({ | ||
| username: "my-agent", | ||
| clientId: "my-agent-inbox-v1", | ||
| displayName: "My Agent", | ||
| }); | ||
|
|
||
| // Safe to call multiple times: same inbox returned every time | ||
| ``` | ||
|
|
||
| ## Send your first email | ||
|
|
||
| Once the inbox is created, you can send an email: | ||
|
|
||
| ```typescript title="TypeScript" | ||
| await client.inboxes.messages.send(inbox.inboxId, { | ||
| to: "recipient@example.com", | ||
| subject: "Hello from my agent!", | ||
| text: "This is a plain text version.", | ||
| html: "<p>This is an <strong>HTML</strong> version.</p>", | ||
| }); | ||
| ``` | ||
|
|
||
| <Note> | ||
| Always provide both `text` and `html` when sending emails. This ensures readability across all email clients and improves deliverability. | ||
| </Note> | ||
|
|
||
| ## List your inboxes | ||
|
|
||
| ```typescript title="TypeScript" | ||
| const inboxes = await client.inboxes.list(); | ||
| console.log(`You have ${inboxes.count} inboxes.`); | ||
|
|
||
| for (const inbox of inboxes.inboxes) { | ||
| console.log(` ${inbox.inboxId}`); | ||
| } | ||
| ``` | ||
|
|
||
| ## Next steps | ||
|
|
||
| Now that you have an inbox, explore what you can do with it: | ||
|
|
||
| - [Send and receive emails](/sending-receiving-email) in a conversational loop | ||
| - [Set up webhooks](/webhook-setup) to get notified when emails arrive | ||
| - [Use labels](/labels) to track message state in your agent workflows |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2: These API layout entries are duplicated. Keeping them twice will repeat the same sections in the API reference navigation. Remove the second set of
api-keys,pods, andorganizations.Prompt for AI agents
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No it is correct. we want to put it there.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Got it—leaving those entries as-is.