Bird

View saved version →

---
name: bird-cli
description: Use when operating Bird through the bird CLI to preview or send messages, inspect or manage API resources, register or inspect Inbox Insights seed tests, or onboard an account; excludes client development.
---

# Bird CLI

`bird` is a single binary for the Bird API and local tools such as WhatsApp message previews. Account operations need credentials; local previews do not.

This skill requires the `bird` CLI. If `command -v bird` finds nothing, install it with `brew install messagebird/tap/bird`, or follow the [CLI installation instructions](https://bird.com/docs/cli#install) for other platforms.

## The path

**Step 0 — Authenticate for account operations.** For a WhatsApp preview, go directly to [Preview](references/whatsapp.md#preview); for public documentation questions, use [docs](references/docs.md). For account operations, confirm credentials first: [authenticate](references/authenticate.md). It is a no-op when `bird auth status` already reports `valid: true`. No account yet? Create one through [onboarding](references/onboarding.md); it ends by storing the same credential a login would.

**Step 1 — Run the operation the user asked for:**

- Send or inspect email messages (`bird email`, including `send-batch`) → [email](references/email.md)
- Author reusable email templates, submit a draft, or roll one back (`bird email templates`) → [email-templates](references/email-templates.md)
- Prepare, send, or inspect a marketing broadcast (`bird email broadcasts`) → [email-broadcasts](references/email-broadcasts.md)
- Send or inspect SMS messages, or browse SMS templates (`bird sms`) → [sms](references/sms.md)
- Draft the carrier verification a US toll-free number needs before it can send, read what the carrier asks for, or see why one was declined (`bird sms tfn verifications`) → [tfn-verifications](references/tfn-verifications.md)
- Claim an alphanumeric SMS sender, find out what a country requires of it, or register it for a country (`bird sms senders`) → [sms-senders](references/sms-senders.md)
- Reply to Apple Messages conversations or manage businesses and statistics (`bird amb`) → [Apple Messages](references/amb.md)
- Preview a WhatsApp message (`bird whatsapp preview`) → [Preview](references/whatsapp.md#preview) (local — skips Step 0)
- Send or inspect WhatsApp messages, receipts, reactions, senders, suppressions, keyword rules or statistics (`bird whatsapp`) → [WhatsApp operations](references/whatsapp.md)
- Browse WhatsApp templates, their versions, and each version's per-language content (`bird whatsapp templates`) → [whatsapp-templates](references/whatsapp-templates.md)
- Create and administer WhatsApp groups, hand out or rotate an invite link, decide join requests, pin messages, or remove a participant (`bird whatsapp groups`) → [whatsapp-groups](references/whatsapp-groups.md)
- Set up the WhatsApp Business Agent on a number — onboard it, give it FAQs, websites, files and skills, test it, then turn it on (`bird whatsapp agents`) → [whatsapp-agents](references/whatsapp-agents.md)
- Inspect voice calls, find out why one was refused, configure a SIP trunk or an inbound number, register or verify an outbound caller ID, enable or disable calling to a country, or place a test call (`bird voice`) → [voice](references/voice.md)
- Buy an eSIM, add data, deliver installation details, or manage recurring packages (`bird esim`) → [eSIM](references/esim.md)
- Provision Realtime apps and rotate the keys their clients connect with (`bird realtime`) → [realtime](references/realtime.md)
- Verify a recipient with a one-time passcode — send a code, then check what they submit (`bird verify verifications`) → [verify](references/verify.md)
- Find out about a recipient before you use it — grade an email address, or identify a phone number and its network (`bird lookup`) → [lookup](references/lookup.md)
- Manage contacts, audiences, and contact properties (`bird contacts`, `bird audiences`, `bird contact-pr

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 73 — file references are metadata, not package contents.

View saved version →

---
name: email-audit
description: Use when auditing a live domain's email authentication or spam-delivery problems involving DMARC, SPF, DKIM, BIMI, or MX; single-record drafts use bird validators.
---

# Email authentication audit

`bird email tools audit <domain>` resolves a domain's live email-authentication records — DMARC, SPF, DKIM, BIMI, MX — validates each, checks how they work _together_, and returns a graded report. Your job with this skill is to run it and then act as the consultant: read the findings, explain what each means in plain terms, and give the user a prioritized plan.

It is DNS-only and needs no auth. It sends no mail and inspects no message; it reads what the domain publishes.

```
bird email tools audit acme.com
bird email tools audit acme.com --selector s1   # also check a DKIM selector (see DKIM below)
```

MCP: `email_tools_audit` with `{ "domain": "acme.com", "selector": "s1" }`.

## When to use this vs the per-record validators

- **`audit <domain>`** — "how is _my domain_ set up?" Resolves live records and grades the whole posture. This is the one to reach for when someone describes a _symptom_ ("going to spam", "failing DMARC", "can people spoof us?").
- **`validate-dmarc` / `validate-bimi <record>`** — "is _this record I wrote_ correct?" Offline, parses a pasted string. Use when drafting a record before publishing, not when diagnosing a live domain.

If they give you a domain, audit it. If they paste a record, validate it.

## Reading the report

```jsonc
{
  "domain": "acme.com",
  "valid": false,                      // true only when there are NO problem-severity findings
  "records": [                         // what was found, per area
    { "area": "dmarc", "found": true,  "value": "v=DMARC1; p=none; rua=..." },
    { "area": "spf",   "found": true,  "value": "v=spf1 include:... ~all" },
    { "area": "dkim",  "found": false, "value": null },
    ...
  ],
  "findings": [                        // graded observations, most-severe first
    { "severity": "problem", "area": "spf", "message": "...", "fix": "..." },
    { "severity": "warning", "area": "dmarc", "message": "...", "fix": "..." }
  ],
  "recommendations": [ "...", "..." ]  // the fixes, problems first — the action list
}
```

Three severities, and what each means for the user:

- **`problem`** — delivery or spoofing protection is actually broken right now. Lead with these. (`valid` is `false` whenever any exist.)
- **`warning`** — works, but is weak, incomplete, or risky. Address after the problems.
- **`ok`** — a passing check. Use these to reassure ("DMARC is enforcing, good") so the report isn't only negatives.

The fastest way to advise: read `findings` top-to-bottom (already severity-ordered), then hand back `recommendations` as the to-do list. Don't just dump the JSON — translate it.

## What each area means and how to fix it

**DMARC** (`_dmarc.<domain>`) — the policy that ties SPF and DKIM together and tells receivers what to do with mail that fails. The journey is `p=none` → `p=quarantine` → `p=reject`:

- `p=none` is **monitor-only**: you get reports but spoofed mail still lands. It's the right _first_ step, never the destination. Recommend moving to `quarantine` then `reject` once legitimate mail is passing aligned (see Alignment).
- No record at all is a `problem` — the domain is spoofable and you're blind to abuse. Start at `p=none` with a `rua=` address to collect reports.
- No `rua=` means no visibility — add a reporting address before tightening the policy.
- An invalid record is treated by receivers as no record; fix it (validate-dmarc) before anything else.

**SPF** (`<domain>` TXT, `v=spf1 …`) — the list of servers allowed to send for the domain. Two things bite people:

- **The 10-lookup limit (RFC 7208).** Every `include:`, `redirect=`, `a`, `mx`, `ptr`, `exists` costs a DNS lookup, and `include:` chains recurse. Over 10 total, SPF returns _permerror_ and fails for **all** mail, including legitimate. The aud

Preview of the first 4,000 characters. Read full instructions →