Bird (Platform API)
Bird's post-2024 platform API. Use this if your Bird access key starts with bk_. Single-field setup, region auto-detected from the key.
bk_<region>_...- Key starts with
bk_eu1_,bk_us1_,bk_apse1_etc. → this page (Bird Platform API) - Key starts with
live_ortest_→ use the MessageBird (Legacy REST) provider instead
Why Bird Platform API
The Bird platform API is Bird's current messaging product. It's the API used by accounts created after Bird's platform rebuild in 2024, and by anyone whose Bird dashboard has issued them a bk_... key:
- Simpler auth — a single bearer token instead of the multi-header MessageBird REST scheme
- Region auto-routed — the key contains its region (
bk_eu1_...) so EziLinks knows which Bird endpoint to hit without extra config - Same underlying network as MessageBird Legacy REST — delivery quality is identical, pricing is very close
- Modern, JSON-first API with cleaner error responses that include remediation text
When it's not the right choice:
- If you have a legacy
live_...key from an older MessageBird account, use the MessageBird Legacy REST provider — it's the same billing account, different API - For AU/NZ only, Kudosity is cheaper
- For US/CA, Twilio is better
Step 1 — Get a Bird account
1 Sign up
Go to bird.com. If you already had a MessageBird account, sign in with those credentials.
2 Complete business verification
Bird verifies your business before enabling paid sends. Documents you'll be asked for: company registration, tax ID, sample messages you plan to send, expected volume.
3 Add credit
Bird is pre-paid. Load credit via card or bank transfer in the dashboard.
Step 2 — Create a bk_ Access Key
1 Open the Bird dashboard
2 Navigate to Developers → Access keys
Click + Create access key. Give it a name like EziLinks. Bird will generate a key that looks like bk_eu1_XXXXXXXXXXXXXXXXXX.
3 Copy the key immediately
Keys are only shown once. Save to a password manager. If you lose the key, generate a new one and revoke the old.
eu1, us1, apse1, etc.) identifies which Bird data centre hosts your workspace. EziLinks reads this and automatically sends to the correct regional endpoint — no manual configuration needed.
Step 3 — Connect to EziLinks
1 Open SMS > Providers
Click + Connect provider and choose Bird (Platform API) from the Provider dropdown — not "MessageBird (Legacy REST)".
2 Paste the Access Key
Only one credential field: Access Key. It must start with bk_ or the adapter rejects it at send time. If you have a live_ or test_ key, use the Legacy REST provider instead. Optionally give the credential a Label.
3 Set default sender
Type the exact sender you'll be sending from. Whatever you type here must also be registered inside Bird under SMS senders — if it isn't, sends will fail with the E12056 error described below.
4 Enter rate (optional)
Set the Cost per SMS part and pick a currency from the dropdown (AUD / USD / GBP / NZD / EUR). Bird's per-country rates live in your Bird Dashboard. Used only for pre-send cost estimates on the composer — leave blank if you don't want estimates.
5 Click Connect, then Send test SMS
EziLinks saves your encrypted key. Card shows Not verified. Click Send test SMS, send to your own mobile — the pill flips to Verified once Bird accepts the send (assuming your sender is registered per step 3).
Register your sender in Bird (mandatory)
Bird enforces sender registration much more strictly than most providers. As of 2024, every sender you send from must be pre-registered under Dashboard → SMS senders. Sending from an unregistered value returns error E12056.
1 Bird Dashboard → SMS senders
Look for it in the left sidebar. May also be labelled Senders or listed under Numbers depending on your account.
2 Add sender
Click + Add sender. Choose either:
- Alphanumeric — enter a brand ID like
EZILINKS(up to 11 chars, letters/numbers only) - Phone number — pick from your purchased Bird numbers (Dashboard → Numbers first if you don't have one)
3 Register for destination countries
Some countries require per-country registration on top of the account-level sender. Instant-approval countries (Australia is typically same-day) work quickly; others (UK, Ireland, Poland, Belgium, France, and several APAC markets) take 1–5 business days.
4 Wait for approval
Status will move from Under review to Active. Bird emails you when approved. You cannot send from a sender still under review.
Delivery report webhook
Unlike the MessageBird Legacy REST API, Bird Platform doesn't accept a per-message webhook URL. You must configure the DLR webhook once at workspace level:
1 Bird Dashboard → Webhook subscriptions
Click + Add subscription or New webhook.
2 Event: SMS message events
Subscribe to message.updated or the equivalent SMS-related event on your Bird account.
3 URL
https://app.ezilinks.com/api/sms/webhook/dlr/bird
4 Save
Bird will now POST every SMS status update to EziLinks. Message history in EziLinks will update from queued → sent → delivered as Bird reports.
queued in EziLinks forever. This is different from MessageBird Legacy REST where the webhook is auto-configured per send.
Sending a test message
- Confirm your sender is Active (not "Under review") in Bird Dashboard
- Confirm your sender is registered for the country you're sending to
- On the EziLinks Providers tab, click Send test SMS on the Bird card
- Pick the country and enter your own mobile in local format, or type it with a leading
+. The line under the box shows the international number that will actually be sent. - Click Send test
- If the webhook is configured, watch History for status updates. If not, the send may succeed but stay
queued
What if my alphanumeric is still under review?
Options:
- Wait it out — most reviews clear within a business day. Bird emails you
- Email Bird support at
support@bird.comto request expedited review, include the review request ID - Buy a Bird virtual number instead — numbers auto-register as senders without review
- Use a different provider for the test — if all you want is proof that EziLinks is wired up correctly, send from Kudosity or ClickSend and revisit Bird when its sender clears
Common errors and fixes
| Error | What it means | How to fix |
|---|---|---|
BIRD_E12056 SMSSenderNotConfigured |
Sender ID isn't registered on your Bird account | Register it under Bird Dashboard → SMS senders, and register it for the destination country. Wait for status "Active". |
BIRD_UNAUTHORIZED |
Access key is wrong or revoked | Confirm the key starts with bk_. Rotate in Bird Dashboard → Developers → Access keys. |
BIRD_E01001 ValidationError |
Request body is missing or has extra fields | Usually a compatibility issue when Bird tweaks their schema. EziLinks includes only to, text, from, category. If you see this error, contact EziLinks support with the request_id from the error message. |
| "additional properties 'reference' not allowed" | Bird's schema changed | Shouldn't reach users — EziLinks handles this. If you see it, report to support. |
| category "notification" invalid | Bird only accepts 4 categories | EziLinks defaults to transactional. Valid values: transactional, marketing, authentication, service. |
Stuck at queued |
DLR webhook not configured | Add the webhook subscription in Bird Dashboard → Webhook subscriptions pointing to https://app.ezilinks.com/api/sms/webhook/dlr/bird. |
Pricing notes
Bird's platform pricing is very close to MessageBird Legacy REST since they run on the same underlying network. Rough guide:
- UK, Germany, France: ~€0.03–€0.08 per part
- India: ~€0.005 per part with DLT registration
- Indonesia, Thailand, Vietnam: ~€0.02–€0.06 per part
- Australia: ~€0.04–€0.06 per part — still more expensive than Kudosity for AU-only
- US: ~$0.03 USD per part — Twilio is cheaper
The "category" field
Bird's platform API requires every send to specify a category. EziLinks sets this to transactional by default because it's the safest bucket — no marketing consent triggers, no OTP-specific fraud checks. If you're sending marketing SMS, the composer will eventually expose an override so you can tag the send correctly for compliance reporting.
The four Bird-accepted values:
transactional— receipts, confirmations, general business SMS. Safe default.marketing— promotional; triggers consent and opt-out enforcement in regulated markets.authentication— OTP / 2FA codes. Best deliverability path for auth flows.service— customer service, delivery updates, alerts.