AgentMail — E-Mail für KI-Agenten
AgentMail gibt KI-Agenten echte E-Mail-Adressen (@theagentmail.net) mit einer REST-API. Agenten können E-Mails senden und empfangen, sich für Dienste (GitHub, AWS, Slack, usw.) registrieren und Verifizierungscodes erhalten. Ein Karma-System verhindert Spam und hält den Ruf der gemeinsamen Domain hoch.
Basis-URL: https://api.theagentmail.net
Wann verwenden
- Ein KI-Agent benötigt ein echtes Postfach für Registrierungen, Verifizierungsabläufe oder transaktionale Kommunikation.
- Sie müssen AgentMail-Konten bereitstellen, Nachrichten senden, Posteingänge lesen oder eingehende Webhooks registrieren.
- Sie müssen die Karma-Nutzung überwachen oder E-Mail-Ereignisse in die Agentenautomatisierung einbinden.
Schnellstart
Alle Anfragen benötigen den Header Authorization: Bearer am_... (API-Schlüssel aus dem Dashboard).
E-Mail-Konto erstellen (-10 Karma)
curl -X POST https://api.theagentmail.net/v1/accounts \
-H "Authorization: Bearer am_..." \
-H "Content-Type: application/json" \
-d '{"address": "[email protected]"}'
Antwort: {"data": {"id": "...", "address": "[email protected]", "displayName": null, "createdAt": 123}}
E-Mail senden (-1 Karma)
curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/messages \
-H "Authorization: Bearer am_..." \
-H "Content-Type: application/json" \
-d '{
"to": ["[email protected]"],
"subject": "Hallo von meinem Agenten",
"text": "Nur-Text-Nachricht",
"html": "<p>Optionaler HTML-Inhalt</p>"
}'
Optionale Felder: cc, bcc (String-Arrays), inReplyTo, references (Strings für Threading), attachments (Array von {filename, contentType, content}, wobei content base64-codiert ist).
Posteingang lesen
# Nachrichten auflisten
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages \
-H "Authorization: Bearer am_..."
# Vollständige Nachricht abrufen (mit Inhalt und Anhängen)
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId} \
-H "Authorization: Bearer am_..."
Karma prüfen
curl https://api.theagentmail.net/v1/karma \
-H "Authorization: Bearer am_..."
Antwort: {"data": {"balance": 90, "events": [...]}}
Webhook registrieren (Echtzeit-Eingang)
curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/webhooks \
-H "Authorization: Bearer am_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://my-agent.example.com/inbox"}'
Webhook-Zustellungen enthalten zwei Sicherheits-Header:
X-AgentMail-Signature– HMAC-SHA256-Hex-Digest des Anfragekörpers, signiert mit dem Webhook-GeheimnisX-AgentMail-Timestamp– Millisekunden-Zeitstempel der Zustellung
Überprüfen Sie die Signatur und lehnen Sie Anfragen mit Zeitstempeln älter als 5 Minuten ab, um Replay-Angriffe zu verhindern:
import { createHmac } from "crypto";
const verifyWebhook = (body: string, signature: string, timestamp: string, secret: string) => {
if (Date.now() - Number(timestamp) > 5 * 60 * 1000) return false;
return createHmac("sha256", secret).update(body).digest("hex") === signature;
};
Anhang herunterladen
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId} \
-H "Authorization: Bearer am_..."
Antwort: {"data": {"url": "https://signed-download-url..."}}
Vollständige API-Referenz
| Methode | Pfad | Beschreibung | Karma |
|---|---|---|---|
| POST | /v1/accounts | E-Mail-Konto erstellen | -10 |
| GET | /v1/accounts | Alle Konten auflisten | |
| GET | /v1/accounts/:id | Kontodetails abrufen | |
| DELETE | /v1/accounts/:id | Konto löschen | +10 |
| POST | /v1/accounts/:id/messages | E-Mail senden | -1 |
| GET | /v1/accounts/:id/messages | Nachrichten auflisten | |
| GET | /v1/accounts/:id/messages/:msgId | Vollständige Nachricht abrufen | |
| GET | /v1/accounts/:id/messages/:msgId/attachments/:attId | Anhang-URL abrufen | |
| POST | /v1/accounts/:id/webhooks | Webhook registrieren | |
| GET | /v1/accounts/:id/webhooks | Webhooks auflisten | |
| DELETE | /v1/accounts/:id/webhooks/:whId | Webhook löschen | |
| GET | /v1/karma | Guthaben + Ereignisse abrufen |
Karma-System
Jede Aktion hat einen Karma-Preis oder eine Belohnung:
| Ereignis | Karma | Warum |
|---|---|---|
money_paid | +100 | Guthaben kaufen |
email_received | +2 | Jemand von einer vertrauenswürdigen Domain hat geantwortet |
account_deleted | +10 | Karma-Erstattung beim Löschen einer Adresse |
email_sent | -1 | Senden kostet Karma |
account_created | -10 | Erstellen von Adressen kostet Karma |
Wichtige Regeln:
- Karma wird nur für eingehende E-Mails von vertrauenswürdigen Anbietern vergeben (Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, Hey, usw.). E-Mails von unbekannten/Wegwerf-Domains bringen kein Karma.
- Sie erhalten Karma nur einmal pro Absender, bis der Agent antwortet. Wenn Absender X Ihnen 5 Mal ohne Antwort schreibt, wird nur die erste E-Mail belohnt. Antworten Sie X, dann bringt die nächste E-Mail von X wieder Karma.
- Das Löschen eines Kontos erstattet die 10 Karma, die die Erstellung gekostet hat.
Wenn das Karma 0 erreicht, geben Senden und Kontoerstellung HTTP 402 zurück. Überprüfen Sie immer den Kontostand, bevor Sie Aktionen ausführen, die Karma kosten.
TypeScript SDK
import { createClient } from "@agentmail/sdk";
const mail = createClient({ apiKey: "am_..." });
// Konto erstellen
const account = await mail.accounts.create({
address: "[email protected]",
});
// E-Mail senden
await mail.messages.send(account.id, {
to: ["[email protected]"],
subject: "Hallo",
text: "Gesendet von einem KI-Agenten.",
});
// Posteingang lesen
const messages = await mail.messages.list(account.id);
const detail = await mail.messages.get(account.id, messages[0].id);
// Anhänge
const att = await mail.attachments.getUrl(accountId, messageId, attachmentId);
// att.url ist eine signierte Download-URL
// Webhooks
await mail.webhooks.create(account.id, {
url: "https://my-agent.example.com/inbox",
});
// Karma
const karma = await mail.karma.getBalance();
console.log(karma.balance);
Fehlerbehandlung
import { AgentMailError } from "@agentmail/sdk";
try {
await mail.messages.send(accountId, { to: ["[email protected]"], subject: "Hi", text: "Hey" });
} catch (e) {
if (e instanceof AgentMailError) {
console.log(e.status); // 402, 404, 401, usw.
console.log(e.code); // "INSUFFICIENT_KARMA", "NOT_FOUND", usw.
console.log(e.message);
}
}
Häufige Muster
Für einen Dienst registrieren und die Verifizierungs-E-Mail lesen
const account = await mail.accounts.create({
address: "[email protected]",
});
// Mit der Adresse registrieren (Browser-Automation, API, usw.)
// Auf Verifizierungs-E-Mail warten
for (let i = 0; i < 30; i++) {
const messages = await mail.messages.list(account.id);
const verification = messages.find(m =>
m.subject.toLowerCase().includes("verify") ||
m.subject.toLowerCase().includes("confirm")
);
if (verification) {
const detail = await mail.messages.get(account.id, verification.id);
// Verifizierungslink/-code aus detail.bodyText oder detail.bodyHtml parsen
break;
}
await new Promise(r => setTimeout(r, 2000));
}
E-Mail senden und auf Antwort warten
const sent = await mail.messages.send(account.id, {
to: ["[email protected]"],
subject: "Frage zu Bestellung #12345",
text: "Können Sie den Status prüfen?",
});
for (let i = 0; i < 60; i++) {
const messages = await mail.messages.list(account.id);
const reply = messages.find(m =>
m.direction === "inbound" && m.timestamp > sent.timestamp
);
if (reply) {
const detail = await mail.messages.get(account.id, reply.id);
// Antwort verarbeiten
break;
}
await new Promise(r => setTimeout(r, 5000));
}
Typen
type Account = { id: string; address: string; displayName: string | null; createdAt: number };
type Message = { id: string; from: string; to: string[]; subject: string; direction: "inbound" | "outbound"; status: string; timestamp: number };
type MessageDetail = Message & { cc: string[] | null; bcc: string[] | null; bodyText: string | null; bodyHtml: string | null; inReplyTo: string | null; references: string | null; attachments: AttachmentMeta[] };
type AttachmentMeta = { id: string; filename: string; contentType: string; size: number };
type KarmaBalance = { balance: number; events: KarmaEvent[] };
type KarmaEvent = { id: string; type: string; amount: number; timestamp: number; metadata?: Record<string, unknown> };
Einschränkungen
- Verwenden Sie dieses Skill nur, wenn die Aufgabe eindeutig mit dem oben beschriebenen Umfang übereinstimmt.
- Behandeln Sie die Ausgabe nicht als Ersatz für umgebungsspezifische Validierung, Tests oder fachkundige Überprüfung.
- Fragen Sie nach, wenn erforderliche Eingaben, Berechtigungen, Sicherheitsgrenzen oder Erfolgskriterien fehlen.