Email API FAQ

Send to a sandbox address such as delivered@messagebird.dev. The outcome depends on the address you use, not your account state, so you can test sends, webhooks, and suppression before you verify a domain. Addresses like bounce@ and complaint@ simulate those outcomes through our real pipeline. Install an SDK and you can send to one in about five minutes.

Not right away. Sandbox addresses work as soon as you have an API key. Reaching a real recipient needs a verified domain: add the DNS records we give you, and you can register one sending domain on the Free plan, ten on Startup, and a thousand on Growth.

Transactional and marketing sending, templates, sending domains with DKIM/SPF/DMARC, dedicated IPs and pools, suppression, inbound, webhooks, and deliverability analytics, all on one API. SDKs cover TypeScript, Python, Go, PHP, Kotlin, and Swift, each documented against the same shapes as the REST API, and there is also a CLI, installed with brew install messagebird/tap/bird, plus a hosted MCP server if you are wiring up an agent rather than an app.

The Free plan gives you 1,000 emails a month at no cost and no card required. Paid plans start at $15 for 50K, and the per-message rate drops as you scale. Go over what your plan covers, and the extra is billed per 1,000 emails at a rate that falls as your tier rises: $0.90 per 1,000 on Startup and at the bottom of Growth, down to $0.50 per 1,000 at 2.5M a month. An enterprise agreement can lift that cap entirely.

Downgrading does not break anything: handles you have already claimed keep working, you just cannot claim new ones until you are back under the allowance. A mailbox on your own domain counts toward your overall mailbox quota like any other, and its local part never touches the custom-handle allowance.

$24.95 a month per dedicated IP on the Growth plan, up to five. There is no setup fee and no annual commitment.

Single sends and batches are limited separately, and the limits count requests rather than recipients, which is what makes batching the volume lever. A free-tier key gets 10 single sends and 5 batch calls a minute, and paid plans raise both. Do not hard-code those numbers: every response carries an IETF RateLimit header telling you what is left and when the window resets, so pace against that rather than waiting for a 429. One batch call carries up to 100 messages, and one message takes up to 50 addresses in each of to, cc and bcc.

20 MB on every plan, measured on the generated message: the HTML, the text part and every attachment after base64 encoding. Keep raw attachments at or below 15 MB to leave room for that. Recipients set their own limits too, so a message near the cap can be accepted by us and still bounce at the far end. We keep message data for 30 days, so pull anything you need for longer into your own store from the analytics API or from webhooks.

Scoped keys, audited writes, and category-aware suppressions: a marketing send cannot reach a suppressed recipient. Inbound floods are contained too, since blocked mail wakes no webhooks.

Yes, both go through the same send API. The only difference is the category field, which decides how suppressions and unsubscribes apply. Pick transactional for password resets and receipts, and marketing for campaigns.

Send an Idempotency-Key header with each logical send. If the first request succeeded but you never saw the response, replaying it with the same key gives you the original result back with an Idempotency-Replay header, rather than sending the email twice.

Set scheduled_at to any time between 30 seconds and 30 days ahead. The send comes back accepted straight away and stays scheduled until it goes out, so you can cancel it at any point before then.

Yes, as base64 in the attachments array. To show an image inline, give it a content_id and reference that from your HTML with cid:. Keep the raw files at or below 15 MB so the message still fits the 20 MB cap once it is encoded, and note that executable and script content types are refused before the send.

No. Work entirely through the API instead: send your HTML with the placeholders written inline and publish it, then reference the template by id or slug when you send. We pick the placeholders up automatically, so there is no separate list to declare. React Email works too: render your components to HTML and store the result as the body, leaving each placeholder as literal text in the JSX so it survives the render and gets filled in at send. There is no AI generation or drag-and-drop builder today.

You reference it by id or slug, so you send only the per-recipient values instead of the whole body every time, and the layout lives in one place rather than being rebuilt in your code on every call. Templates are versioned, and personalization renders on our side: conditionals, loops over arrays and per-field defaults all resolve per recipient, so a membership block can show only for members. Sending one uses the ordinary send call, with template set to the id or slug and the values in template.parameters.

Yes. Publishing freezes an immutable, numbered version, and editing always happens on the draft, so nothing live changes until you publish. Roll back to any earlier published version to make that the one sends use again, with no new version created. Rolling back also resets the draft to that version's content, so further editing starts from there.

Global. A contact is unique by email, and audiences just reference it, so moving a contact between audiences carries its attributes along automatically because they live on the contact, not the list. Custom fields live in the property registry, a closed, typed schema you define up front: declare each field's type (string, number, boolean, or datetime) with an optional fallback, and we reject unknown keys or wrong-typed values when you write them, so your data stays clean.

Drop a CSV or Excel file into the dashboard and Bird works out which column is which, up to 50,000 contacts at a time. Or batch-upsert up to 1,000 in one call, and join them to an audience in the same request, with no separate add step. Either way the upsert is idempotent on the identifiers each entry carries, so re-running an import updates rather than duplicates. A broadcast targets a single audience: build and maintain it here, then reference it by ID when you send.

Point it at a single audience. Audience is the one targeting concept, so you do not stack lists and segments on top of it.

Yes to both. Send immediately, or schedule it with an explicit timestamp from 30 seconds to 30 days out. Once it is scheduled, or already sending, you can cancel it: a broadcast can move to canceled from any non-terminal state.

The same one. Marketing and transactional email share one API, one set of keys, and one analytics surface. Broadcasts add the campaign lifecycle on top of the sending infrastructure you already use. You still decide how to separate their sending reputations.

Every send is authenticated with DKIM, SPF, and DMARC, your IPs are warmed automatically, and bounces and complaints suppress automatically so a bad address never burns your reputation twice. Blocklist monitoring flags a problem while you can still act on it. Unsubscribes and complaints also suppress the recipient automatically and reversibly, one-click List-Unsubscribe is built in, and a broadcast applies your marketing suppressions before it sends.

Delivery, opens, clicks, bounces, and complaints broken down by campaign, tag, and mailbox provider, with prefetched opens filtered out. Everything in the dashboard is also available through the stats API.

We generate the records for you: a DKIM TXT record to sign your mail, a return-path CNAME that aligns SPF (no apex SPF record required), and a DMARC TXT record. A tracking CNAME for branded open and click links is optional. Add the domain, paste the records at your DNS provider, and hit verify: most verifications resolve within minutes of DNS propagation, though it can occasionally take longer.

DMARC tells receiving servers what to do with mail that fails DKIM or SPF alignment, and where to send the aggregate reports that show who is sending as your domain. We require a DMARC record before a domain can send, and recommend starting at p=none, which monitors without affecting delivery. Once you have confirmed every legitimate source aligns, tighten the policy to p=quarantine or p=reject. If you already publish DMARC at your domain or a parent domain, we use it as is. Major inbox providers now expect bulk senders to publish a policy, so having one is increasingly part of reaching the inbox at volume.

Yes to both, and we recommend a dedicated subdomain, since it isolates your email reputation from your corporate mail. You can also run separate domains for transactional and marketing mail, or one per brand, each with its own authentication and reputation.

Once you are sending consistently high volume, roughly 100,000 emails a month or more. Below that, a shared pool gives better deliverability because reputation is pooled, and a dedicated IP only helps when you send enough to keep it warm. You do not have to warm it yourself: we warm a new dedicated IP automatically over roughly 30 days, ramping volume so mailbox providers build trust gradually, with overflow on the shared pool so you never drop volume.

Yes. Group IPs into pools and route each traffic type to its own pool, so a marketing send cannot affect the reputation that carries your password resets.

Deliverability is whether your email actually reaches the recipient's inbox rather than the spam folder or a hard rejection. It depends on authentication, sender reputation, list hygiene, and engagement, and we manage or surface each one for you.

We monitor the major blocklists for you. The stats API and dashboard also expose bounce codes, complaint types, and mailbox-provider breakdowns, so you can catch a downward trend early.

A hard bounce, a spam complaint, or an unsubscribe puts the address on your suppression list, and nothing you send afterwards goes to it. That is what stops one bad address from costing you reputation on every later send. Suppression is not permanent: you can take an address off the list yourself once you know it has recovered.

Hard bounces, spam complaints, and unsubscribes get suppressed automatically: once a recipient triggers one of these, we add them to your suppression list and skip them on future sends. Hard bounces and any address you suppress manually block every send, but complaints and unsubscribes only apply to marketing mail, so a transactional message like a password reset still reaches someone who opted out of your campaigns.

Yes to all three. Suppression is reversible, so if an address recovers, remove it from the list through the dashboard or API and resume mailing it. You can also add addresses yourself, for instance a known-bad list you are importing, and they are skipped just like an automatic entry. To test the behavior without burning a real address, send to the sandbox address suppressed@messagebird.dev: it behaves exactly as if the recipient were suppressed, rejected with recipient_suppressed, but nothing is written to your list, so you can use it again and again.

We track delivery, opens, clicks, bounces, complaints, and unsubscribes, summarized as KPIs and broken down by domain, ISP, IP, sending domain, recipient domain, tag, and broadcast, with bounce-code and complaint-type detail. Mailbox-provider and client breakdowns also show how Gmail, Yahoo, Outlook, Apple Mail, and others deliver, open, and bounce your messages.

Yes. Everything the dashboard charts is available through the stats API, at daily or hourly granularity, so you can backfill reports or stream metrics into your own tools. Engagement and delivery events also arrive in near real time via webhooks and roll up into the stats endpoints, so dashboards and queries reflect what just happened, not yesterday.

A real, addressable inbox your code owns. Mail sent to it lands in threads your agent can read, filter, reply to, and send from over the API, without running an IMAP server or parsing raw MIME. Plain inbound parsing only hands you raw messages. A mailbox adds the conversation layer: a claimed address, threads with labels, quote-stripped text, and replies that fold back in.

Yes. A mailbox lives on the shared inbox.ai domain or on your own domain, once you configure inbound forwarding there. Any local part not in its 30-day post-deletion quarantine is available. A generated handle is 20 random characters, always available and free. A custom handle is one you pick (goldcrest@inbox.ai), first-come first-served across all organizations, and it comes out of your plan's allowance.

If you only need mail parsed into a webhook, plain inbound email is enough. A mailbox earns its keep when the agent has to hold a conversation. To start, create an API key in the dashboard, claim an address, and reply to your first thread, all in a few minutes. The docs walk the whole loop, and the hosted MCP server gives an agent the same tools without any HTTP glue.

Both are on-prem MTAs you run yourself instead of sending through our managed API. Momentum MTA is built around customizable workflows and routing for high-volume sending. PowerMTA is built to run on your own servers or any public cloud, such as AWS or Azure.

Teams with infrastructure or compliance requirements that call for running their own MTA, and teams that want independent visibility into inbox placement and competitive benchmarking rather than relying on their own send metrics alone. The first group runs Momentum MTA or PowerMTA. The second group uses Inbox Tracker, which measures inbox placement and reputation from real mailbox data, or Competitive Tracker, which benchmarks your program against other brands, and neither of those requires you to self-host anything.

SparkPost is now Bird Email. We acquired SparkPost in 2021 to add the deliverability engine behind roughly 40% of the world's commercial email to a single platform for email, SMS, WhatsApp, and voice. Existing SparkPost customers keep their service and are not required to move. New projects build on the Bird Email API instead, which runs on the same deliverability engine and adds SMS, WhatsApp, and voice on one set of keys.

The deliverability engine is the same one SparkPost ran, but the interface is a modern email API with SDKs in every major runtime. Its docs cover sending, templates, sending domains, and webhooks.

Momentum is our on-premises email infrastructure platform for high-volume sending, with customizable workflows, routing, and delivery parameters set through its Policy Manager. It is built to scale with your sending volume while keeping performance stable, and it supports full Unicode (SMTPUTF8) so you can send to international character sets.

Adaptive Delivery is Momentum's automatic traffic shaping. It watches how each mailbox provider responds to your mail and adjusts in real time: throttling, deferring, or briefly pausing a stream to protect your reputation, then ramping back up once things clear. You reach the inbox without manually babysitting send rates for every provider. The Intelligence Router shows you this happening across all your data sources, with real-time alerts whenever it makes an adjustment.

Yes to both. Momentum runs on your own servers, on any major cloud, or split across the two, so you can match it to your infrastructure, cost, and compliance needs and change that mix over time. It also keeps shipping: recent releases keep it current with modern operating systems, TLS 1.3, and up-to-date security and SMTP standards, and expose message events through real-time APIs you can feed into your own reporting and automation.

Yes. PowerMTA can relay some traffic to the hosted Bird Email API while delivering the rest straight from your own servers, which is the simplest way to try the hosted platform or migrate gradually without moving everything at once. PowerMTA itself runs on infrastructure you own, so those IPs stay yours to manage. Traffic you relay to the hosted platform can use our IPs there, or your own dedicated IPs, while everything else stays entirely under your control.

Virtual MTAs let you run several independent sending streams inside one PowerMTA instance, each with its own IPs, reputation, and limits. Use them to keep transactional and marketing mail, or different customers, cleanly separated so one stream's problems never affect another.

Deliverability is whether your email reaches the inbox rather than the spam folder or a rejection. Inbox Tracker measures it per mailbox provider, in real time, and gives you a daily breakdown of where your mail actually landed: inbox, spam, or blocked.

Inbox Tracker flags placement dropping at a provider while it is happening, so you see it in a daily breakdown rather than in a fall in replies weeks later. It also flags spam trap hits, which usually mean a list problem worth fixing before it drags your reputation down, and alerts you when DMARC authentication starts failing.

Three sources: licensed mailbox data showing where your mail lands for real recipients, seed accounts that test placement in specific scenarios, and a direct Google Postmaster connection for Gmail's own view of your reputation. They answer different questions, since real mailbox data tells you the outcome, Postmaster tells you Gmail's reasoning, and seeds let you test a scenario on purpose. One source on its own leaves blind spots and raises false alarms.

We track millions of emails a day across more than 250,000 brands in over 100 industries. That data refreshes continuously, so the insights you see reflect current campaigns and trends, not a historical snapshot.

You can compare audience size, campaign frequency, messaging strategies, performance metrics, and engagement rates against other brands in your industry, down to individual competitor email journeys. That same view works for seasonal planning: watch how competitors shift their campaigns ahead of a season and see which strategies are working before you commit to your own.

Often, yes. Competitive Tracker can surface the sending platform or service behind a competitor's email, which is useful for competitive research and for sales teams sizing up how a prospect's rivals run their programs.

Providers treat that like address harvesting and will rate-limit or blocklist you for it, and the results are unreliable: a server can accept an address at the handshake that still will not deliver, and greylisting makes real addresses look invalid. Checking against delivery history avoids both the risk and the false answers.

For Neutral, it is your call: the address is well-formed, has a real mail server, and has never hard-bounced, but we have not yet seen a delivery or engagement event for it, so it carries low risk rather than suspicion. Send to it if you are growth-focused, or hold it until you see engagement if you would rather play safe. For Typo, show the suggested correction on a signup form so the person can fix it before submitting, which recovers a lead that would otherwise bounce; in a batch list, separate the typos out and confirm or drop them, but do not send to the misspelled address.

Yes. The API is HTTPS only. If you submit over SMTP instead, port 465 is encrypted from the first byte, and ports 587 and 2525 upgrade with STARTTLS: we refuse AUTH on those until the upgrade completes, so credentials never travel in the clear. Port 25 is not offered for submission at all. Your data stays in the region your organization is hosted in, either us1 or eu1, and your API key's prefix (bk_us1_…, bk_eu1_…) encodes that region so the SDKs and CLI pick the right endpoint automatically. Only authentication and account administration run on a region-independent host.

Only what you scope it to. A key carries a list of scopes such as emails, email_marketing, or domains, each at read or write, so a key that sends mail cannot manage your sending domains. Control-plane actions (members, workspace settings, issuing keys, IP pools) are dashboard-only, and no key can reach them. Each key also takes an allowlist of CIDR ranges, and requests from anywhere else are rejected.

Rotating issues the new key and leaves the old one working for a grace period, 24 hours by default, so you can roll it through your deploys. Pass zero to revoke the old key immediately instead. Rotation never extends a key's lifetime: a key already expiring sooner than the grace period keeps its original expiry.

Yes, over SAML 2.0 or OIDC, so Okta, Microsoft Entra ID and Google Workspace all work. It is set up per organization: your account team turns it on for you. Members who sign in with a password can turn on MFA themselves.

Yes. The audit log is a read-only, organization-wide record of every management action, with the actor, the workspace, the time and the outcome, and it exports to OCSF for your own SIEM. It covers configuration changes rather than the messages you send. Those live in the email log.

Certifications and security documentation live in the Trust Center at trust.bird.com. The data processing agreement, privacy statement and acceptable use policy are published at bird.com/legal, current versions alongside an archive of superseded ones. For a vendor questionnaire, your account team handles it.