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, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace e gli strumenti per sviluppatori (Webhooks e Documentation, l'API di ricerca della documentazione). Domini di invio, email in entrata, contatti e audience hanno pagine nel reference senza voce nella barra laterale. Parti da Crea un dominio di invio, Crea un indirizzo in entrata, Crea un contatto e Crea un'audience, oppure dalle rispettive guide: Domini di invio, Ricezione email, Contatti e Audience. 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.

Per agenti di codifica

Indirizza un agente a queste fonti leggibili dalla macchina:

• Specifica OpenAPI: ogni endpoint pubblico, schema e codice di errore, disponibile anche come YAML. Gli SDK sono generati dallo stesso file.
• Indice API: le guide API, ogni reference di operazione e gli errori pubblici, raggruppati per prodotto e collegati alle rispettive pagine Markdown.
• Indice della documentazione: ogni pagina della documentazione in inglese pubblicata, raggruppata per sezione e prodotto.
• Indice del sito: prodotti, quickstart e strumenti per agenti su bird.com.
• MCP server: strumenti ospitati su mcp.bird.com che operano sul tuo spazio di lavoro dopo un accesso dal browser.
• Bird CLI: l'API da terminale. CLI for agents descrive il suo output JSON e i codici di uscita.
• Pagine Markdown: aggiungi .md a qualsiasi URL della documentazione, come in https://bird.com/docs/api.md, oppure invia Accept: text/markdown.

Mappa dei prodotti

Ogni tabella elenca le chiamate effettuate da un'integrazione, in ordine, con un link alla pagina di reference di ciascuna chiamata e alle guide del prodotto.

Email

SMS

Verify

Altri prodotti

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 e lascia invariati i campi omessi. 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