Utwórz pierwszą skrzynkę pocztową agenta

Ten przewodnik prowadzi przez pełną dwukierunkową rozmowę: utwórz skrzynkę w inbox.ai, odbierz wiadomość do wątku, przeczytaj ją i odpowiedz. Nie musisz weryfikować domeny ani uruchamiać serwera pocztowego.

1. Utwórz klucz API

W panelu przejdź do Platform tools > API keys i utwórz klucz. W grupie Email włącz zakresy mailbox i mailbox_management. Klucze mają postać bk_us1_... lub bk_eu1_...; region w prefiksie wskazuje host API.

Przykład kodu

export BIRD_API_KEY="bk_us1_..."

Użyj name jako nazwy nadawcy widocznej dla odbiorców. Ustaw display_name, aby nadać skrzynce inną etykietę dla zespołu; w przeciwnym razie przyjmuje ona wartość name.

2. Utwórz skrzynkę pocztową

Utwórz skrzynkę pocztową we współdzielonej domenie inbox.ai. Jeśli pominiesz część lokalną, Bird wygeneruje dostępny adres. Zasada odbioru open przyjmuje pocztę, chyba że zablokuje ją reguła odbioru.

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"
  }'

Odpowiedź zawiera id skrzynki oraz przydzielony Ci address. Wyślij wiadomość na ten adres z dowolnego klienta poczty, aby w następnym kroku było co przeczytać.

3. Przeczytaj wątek

Poczta przychodząca trafia do skrzynki jako wątek. Wyświetl listę wątków, a następnie przeczytaj wiadomości w pierwszym z nich.

Wątek skrzynki pocztowej w panelu Bird z wiadomością przychodzącą i odpowiedzią w dwukierunkowej pętli konwersacji

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"

Następnie odczytaj wiadomości z tego wątku:

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"

Każda wiadomość zawiera swój kierunek (inbound) i swój id (odebrana wiadomość ma prefiks rem_). Dodaj include=extracted_text, aby dołączyć treść bez cytatów: nową zawartość bez cytowanej historii, którą agent musiałby inaczej usuwać sam.

Aby uniknąć odpytywania, zasubskrybuj webhook email_mailbox.message_received. Jest wywoływany, gdy wiadomość przychodząca trafi do skrzynki. Zobacz dokumentację zdarzeń.

4. Odpowiedz

Odpowiedz na odebraną wiadomość. Użyj jej identyfikatora rem_ z kroku 3. Odpowiedź pozostaje w tym samym wątku i jest wysyłana z adresu Twojej skrzynki:

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."
  }'

Możesz teraz zajmować skrzynkę, odbierać, czytać i odpowiadać. Aby rozpocząć konwersację zamiast na nią odpowiadać, utwórz nową wiadomość w skrzynce (POST /v1/email/mailboxes/{id}/messages), co otworzy nowy wątek.

Kolejne kroki

Skrzynki pocztowe agentów: jak działają wątki, reguły odbioru, wysyłanie i przechowywanie.
Serwer MCP: uruchom tę samą pętlę z poziomu agenta AI przez serwer MCP.
CLI: bird email mailboxes i bird email threads dla terminala.
Przewodniki SDK: instrukcje krok po kroku SDK dla Go, Pythona i TypeScriptu.

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.

Mailbox API

Uzyskaj brief wdrożeniowy