Ihr erstes Agent-Postfach einrichten

Diese Anleitung führt eine bidirektionale Konversation vollständig durch: Sie richten ein Postfach auf inbox.ai ein, empfangen eine Nachricht in einem Thread, lesen sie und antworten. Sie müssen dafür weder eine Domain verifizieren noch einen Mailserver betreiben.

1. Einen API-Schlüssel erstellen

Öffnen Sie im Dashboard Platform tools > API keys und erstellen Sie einen Schlüssel. Aktivieren Sie in der Gruppe Email die Scopes mailbox und mailbox_management. Schlüssel haben die Form bk_us1_... oder bk_eu1_...; die Region im Präfix legt den API-Host fest.

Codebeispiel

export BIRD_API_KEY="bk_us1_..."

Verwenden Sie name für den Absendernamen, den Empfänger sehen. Setzen Sie display_name, um Ihrem Team eine abweichende Postfachbezeichnung anzuzeigen; andernfalls übernimmt sie den Wert von name.

2. Ein Postfach einrichten

Erstellen Sie ein Postfach auf der gemeinsam genutzten Domain inbox.ai. Wenn Sie den lokalen Teil weglassen, erzeugt Bird eine verfügbare Adresse. Die Empfangsrichtlinie open nimmt E-Mails an, sofern keine Empfangsregel sie blockiert.

const mailbox = await bird.email.mailboxes.create({ name: "Support" });
console.log(mailbox.address); // "abc123@inbox.ai"

mailbox = client.email.mailboxes.create(name="Acme Support")
print(mailbox.id)

mailbox, err := client.Email.Mailboxes.Create(context.Background(), bird.EmailMailboxesCreateParams{
	Name: bird.Ptr("Support"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(mailbox.Id, *mailbox.Address)

$mailbox = $bird->email->mailboxes->create(
    (new MailboxCreate())
        ->setName('Acme Support'),
);
echo $mailbox->getId(), ' ', $mailbox->getAddress();

bird email mailboxes create --name 'My Agent' --receive-policy open

curl -X POST "https://us1.platform.bird.com/v1/email/mailboxes" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "receive_policy": "open"
  }'

Die Antwort enthält die id des Postfachs und die für Sie reservierte address. Senden Sie aus einem beliebigen Mailprogramm eine E-Mail an diese Adresse, damit der nächste Schritt etwas zu lesen hat.

3. Den Thread lesen

Eingehende E-Mails werden im Postfach zu einem Thread. Listen Sie die Threads auf und lesen Sie dann die Nachrichten im ersten Thread.

Ein Mailbox-Thread im Bird-Dashboard mit einer eingehenden Nachricht und einer Antwort in der bidirektionalen Konversation

for await (const thread of bird.email.threads.list({ mailbox_id: "mbx_01abc" })) {
  console.log(thread.id, thread.subject);
}

for thread in client.email.threads.list(mailbox_id="mbx_01krdgeqcxet5s7t44vh8rt9mg"):
    print(thread.id, thread.subject)

for thread, err := range client.Email.Threads.List(context.Background(), bird.EmailThreadsListParams{}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(thread.Id)
}

foreach ($bird->email->threads->list(['mailbox_id' => 'mbx_01krdgeqcxet5s7t44vh8rt9mg']) as $thread) {
    echo $thread->getId(), ' ', $thread->getSubject(), "\n";
}

bird email threads list

curl -X GET "https://{region}.platform.bird.com/v1/email/threads" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "labels=urgent" \
  --url-query "participant=billing@acme.com" \
  --url-query "subject=quarterly invoice" \
  --url-query "limit=25"

Lesen Sie anschließend die Nachrichten dieses Threads:

for await (const msg of bird.email.threads.messages.list("thr_01abc")) {
  console.log(msg.id, msg.direction);
}

for message in client.email.threads.messages.list("thr_01krdgeqcxet5s7t44vh8rt9mg"):
    print(message.id, message.subject)

for msg, err := range client.Email.Threads.Messages.List(context.Background(), "thr_123", bird.EmailThreadsMessagesListParams{}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, msg.Direction)
}

foreach ($bird->email->threads->messages->list('thr_01krdgeqcxet5s7t44vh8rt9mg') as $message) {
    echo $message->getId(), ' ', $message->getDirection(), "\n";
}

bird email threads messages list <thread-id>

curl -X GET "https://{region}.platform.bird.com/v1/email/threads/{thread_id}/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "label=unread" \
  --url-query "limit=25"

Jede Nachricht enthält ihre Richtung (inbound) und ihre id (eine empfangene Nachricht hat das Präfix rem_). Fügen Sie include=extracted_text hinzu, um den Text ohne Zitate direkt mitzuliefern: den neuen Inhalt ohne den zitierten Verlauf, den ein Agent sonst selbst entfernen müsste.

Wenn Sie nicht regelmäßig abfragen möchten, abonnieren Sie den Webhook email_mailbox.message_received. Er wird ausgelöst, sobald eine eingehende Nachricht das Postfach erreicht. Details finden Sie in der Referenz zu Events.

4. Antworten

Antworten Sie auf die empfangene Nachricht. Verwenden Sie dazu ihre rem_-ID aus Schritt 3. Die Antwort bleibt im selben Thread und wird von der Adresse Ihrer Mailbox gesendet:

const reply = await bird.email.threads.messages.reply("thr_01abc", "rem_01xyz", {
  text: "Thanks for reaching out!",
});
console.log(reply.id);

reply = client.email.threads.messages.reply(
    "thr_01krdgeqcxet5s7t44vh8rt9mg", "rem_01krdgeqcxet5s7t44vh8rt9mg",
    text="Thanks for reaching out!",
)
print(reply.id)

reply, err := client.Email.Threads.Messages.Reply(context.Background(), "thr_123", "rem_456", bird.EmailThreadsMessagesReplyParams{
	Text: bird.Ptr("Thanks for reaching out!"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(reply.Id)

$reply = $bird->email->threads->messages->reply(
    'thr_01krdgeqcxet5s7t44vh8rt9mg',
    'rem_01krdgeqcxet5s7t44vh8rt9mg',
    (new EmailThreadMessageReplyRequest())
        ->setText('Thanks, looking into it now.')
        ->setReplyAll(true),
);
echo $reply->getId();

bird email threads messages reply <thread-id> <message-id> \
  --text 'Thanks, confirming we received your request.'

curl -X POST "https://{region}.platform.bird.com/v1/email/threads/{thread_id}/messages/{message_id}/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Thanks, confirming we received your request."
  }'

Sie können jetzt eine Mailbox beanspruchen sowie Nachrichten empfangen, lesen und beantworten. Um selbst eine Konversation zu beginnen, statt auf eine zu antworten, verfassen Sie eine neue Nachricht in der Mailbox (POST /v1/email/mailboxes/{id}/messages). Dadurch entsteht ein neuer Thread.

Nächste Schritte

Agent-Mailboxen: So funktionieren Threads, Empfangsregeln, Versand und Aufbewahrung.
MCP-Server: Führen Sie denselben Ablauf über den MCP-Server aus einem KI-Agenten aus.
CLI: bird email mailboxes und bird email threads für das Terminal.
SDK-Quickstarts: Schritt-für-Schritt-Anleitungen zu SDK für Go, Python und TypeScript.

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Mailbox API

Implementierungs-Briefing erhalten