Introduzione

L'Bird API è un'REST API unificata per tutto ciò che la piattaforma fa. Questo reference documenta ogni endpoint pubblico, generato dalla stessa specifica OpenAPI che alimenta gli SDK ufficiali, quindi le strutture di richiesta e risposta qui riportate sono esattamente ciò che transita sul cavo.

La barra laterale del reference raggruppa le risorse più utilizzate per prodotto: Email, SMS, Voice, Realtime, Verify e gli strumenti per sviluppatori (Webhooks e Documentation, l'API di ricerca della documentazione). Altri endpoint pubblici, tra cui domini di invio, email in entrata, contatti e audience e WhatsApp, sono raggiungibili tramite la ricerca e i link diretti nelle rispettive guide. La sezione Voice include chiamate, log dei segmenti di chiamata, trunk, numeri, caller ID, destinazioni e credenziali di sessione SIP. Le statistiche Voice restano disponibili tramite la dashboard e CLI. Le impostazioni dello spazio di lavoro, le chiavi API e gli IP dedicati si gestiscono dalla dashboard anziché dall'API pubblica.

Le pagine delle risorse sono collegate tramite deep link dalle guide: quando una guida menziona un endpoint, il link porta alla relativa voce nel reference.

Convenzioni

Ogni endpoint segue le stesse convenzioni. Sono dichiarate una sola volta qui anziché ripetute su ogni pagina.

Percorso base: tutti gli endpoint risiedono sotto /v1 su un host regionale come https://us1.platform.bird.com. Vedi URL base e regioni.
Autenticazione: le richieste trasportano una chiave API come bearer token: Authorization: Bearer bk_us1_.... Vedi Autenticazione.
JSON, snake_case: i body di richiesta e risposta sono JSON con nomi di campo snake_case (created_at, workspace_id) e le richieste devono impostare Content-Type: application/json.
Timestamp: tutti i timestamp sono stringhe RFC 3339 in UTC, in campi con suffisso _at (created_at, delivered_at). I timestamp delle risorse come created_at sono assegnati dal server e in sola lettura; alcuni campi di richiesta, come scheduled_at, sono timestamp forniti da te.
ID risorsa tipizzati: ogni ID porta un prefisso di tipo: em_ per i messaggi email, dom_ per i domini di invio, whk_ per gli endpoint webhook, sup_ per le soppressioni, e così via. Il prefisso rende un ID autodescrittivo nei log e impedisce di passare l'ID di una risorsa dove è atteso quello di un'altra.
Gli aggiornamenti parziali usano PATCH: una richiesta PATCH modifica solo i campi che includi; i campi omessi restano invariati. Alcune sotto-risorse che indirizzi per nome nell'URL vengono scritte con PUT, che sostituisce quella sotto-risorsa per intero.
I parametri di query sono rigidi: una richiesta che contiene un parametro di query non documentato dall'endpoint viene rifiutata con 422 (E01029) anziché ignorata. Controlla l'ortografia rispetto alla lista dei parametri dell'endpoint.
Errori: ogni risposta di errore contiene la stessa struttura, con un type per la ramificazione generale, un code stabile, un message leggibile e il request_id da citare quando contatti il supporto. Vedi Risposte di errore.
Paginazione: gli endpoint di lista usano la paginazione basata su cursore con un set condiviso di parametri. Vedi Paginazione.
Idempotenza: gli endpoint mutanti accettano un header Idempotency-Key per rendere sicuri i nuovi tentativi. Vedi Header Idempotency-Key.
Deprecazioni: un campo rinominato continua a funzionare con il vecchio nome, e una risposta lo segnala con un header Deprecation. Vedi Deprecazioni.

Client consigliati

Puoi chiamare l'API con qualsiasi client HTTP, ma i client ufficiali gestiscono autenticazione, selezione della regione, nuovi tentativi e paginazione al posto tuo:

Gli SDK ufficiali per TypeScript, Go e Python: metodi tipizzati sulla superficie pubblica curata
La Bird CLI: l'API dal tuo terminale, adatta anche a script e agenti

Eseguilo in Postman

L'intera API è anche una collection Postman, convertita dalla stessa specifica, con un esempio di richiesta e risposta su ogni endpoint. Importa l'environment per la tua regione, imposta apiKey su una chiave API dello spazio di lavoro e invia qualsiasi richiesta.

Puoi anche scaricare direttamente la collection e un environment per us1 o eu1.

Letture successive

Autenticazione: come le richieste si autenticano a livello di protocollo
URL base e regioni: host regionali e modello delle regioni
Paginazione: cursori, dimensioni di pagina e ordinamento
Header Idempotency-Key: nuovi tentativi sicuri per le richieste mutanti
Risposte di errore: la risposta di errore e il catalogo completo degli errori
Deprecazioni: cosa fa ancora un campo sostituito e come migrare

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first email

Ottieni un brief di implementazione