Sign inGet Started

Wyślij pierwszą wiadomość e-mail

Utwórz klucz API, wyślij wiadomość przez współdzieloną domenę startową Bird i sprawdź wynik. W tym przewodniku nie musisz weryfikować domeny nadawczej ani publikować rekordów DNS. Zanim zaczniesz wysyłać wiadomości do klientów, zweryfikuj własną domenę.

1. Utwórz klucz API

W panelu przejdź do Platform tools > API keys i utwórz klucz. Klucze są przypisane do regionu i wyglądają jak bk_us1_... lub bk_eu1_.... Region w prefiksie wskazuje, którego hosta API należy wywołać: https://us1.platform.bird.com lub https://eu1.platform.bird.com.

Strona API Keys w panelu Bird z listą kluczy, ich zamaskowanymi prefiksami, zakresami uprawnień i czasem ostatniego użycia

Pełny klucz jest wyświetlany tylko raz, podczas tworzenia. Skopiuj go w bezpieczne miejsce, a następnie wyeksportuj, aby fragmenty kodu z kroku 2 mogły go odczytać:

Przykład kodu
export BIRD_API_KEY="bk_us1_..."

2. Wyślij wiadomość e-mail

Wyślij wiadomość z adresu onboarding@messagebird.dev we współdzielonej domenie startowej Bird, dostępnej w Twoim obszarze roboczym bez konfiguracji. Zaadresuj ją do delivered@messagebird.dev, odbiorcy w piaskownicy, do którego wiadomość jest zawsze dostarczana. Dzięki temu wynik jest przewidywalny bez prawdziwej skrzynki pocztowej.

Wywołanie cURL używa hosta w USA. Jeśli Twój klucz zaczyna się od bk_eu1_, wywołaj zamiast niego https://eu1.platform.bird.com. SDK odczytuje region z klucza i wybiera hosta. Karta TypeScript wymaga npm install @messagebird/sdk.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});

console.log(msg.id, msg.status);

Pełne instrukcje instalacji i uruchomienia dla każdego języka lub frameworka znajdziesz w przewodnikach szybkiego startu SDK.

3. Sprawdź wynik

API odpowiada kodem 202: Bird przyjął wysyłkę do asynchronicznego przetwarzania. Status dostarczenia sprawdź osobno. Pola *_count śledzą, w którym stanie dostarczenia są odbiorcy. W początkowej odpowiedzi jeden odbiorca jest przyjęty, a żaden nie jest dostarczony.

Przykład kodu
{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "onboarding@messagebird.dev" },
  "to": [{ "email": "delivered@messagebird.dev" }],
  "subject": "Hello from Bird",
  "accepted_count": 1,
  "processed_count": 0,
  "delivered_count": 0,
  "deferred_count": 0,
  "bounced_count": 0,
  "complained_count": 0,
  "rejected_count": 0,
  "open_count": 0,
  "click_count": 0,
  "track_opens": true,
  "track_clicks": true,
  "created_at": "2026-07-23T13:58:20.866Z"
}

Pobierz wiadomość według jej identyfikatora em_, aby zobaczyć jej bieżący stan. Wiadomość przechodzi ze stanu accepted przez processed do delivered. Odpytuj, dopóki wiadomość w piaskownicy nie osiągnie stanu delivered:

const msg = await bird.email.get("em_abc123");
msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
msg.delivered_count;
msg.bounced_count;
console.log(msg.subject, msg.subject_recipient_id);

Na karcie cURL zastąp {region} i {message_id}, a zamiast $TOKEN użyj $BIRD_API_KEY.

Odczyt pokazuje teraz status: "delivered", delivered_count: 1 oraz znacznik czasu delivered_at. Z przewodnika po zdarzeniach dowiesz się, co delivered potwierdza w przypadku prawdziwego odbiorcy.

Ponieważ wysłano wiadomość na adres delivered@messagebird.dev, wynik jest gwarantowany: wiadomość przechodzi przez prawdziwy potok dostarczania Bird, łącznie z produkcyjnym formatem zdarzeń i webhooków, ale nigdy nie trafia do prawdziwej skrzynki. Aby przetestować odbicie, wyślij wiadomość na adres bounce@messagebird.dev. Przewodnik po piaskownicy testowej zawiera listę wszystkich adresów piaskownicy i symulowanych dla nich wyników.

Domena wdrożeniowa

Współdzielony nadawca onboarding@messagebird.dev jest dostępny na potrzeby wdrożenia i ma następujące ograniczenia:

  • Poza adresami piaskownicy @messagebird.dev dostarcza wiadomości tylko do zweryfikowanych członków Twojego obszaru roboczego; każdy inny odbiorca jest odrzucany z kodem 422.
  • Wysyłki są ograniczone do 50 odbiorców na organizację na dobę UTC, przy czym liczy się każdy adres w polach to, cc i bcc, łącznie z odbiorcami z piaskownicy. Po przekroczeniu limitu API zwraca 429.

Gdy zechcesz wysyłać e-maile do prawdziwych klientów, zweryfikuj własną domenę wysyłkową i wpisz własny adres w polu from; reszta żądania pozostaje bez zmian.

Dalsze kroki

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