Porkbun

Give a waiting mailbox (already paid for, or the free trial that comes with a domain registration) its address and password. Free. If none is waiting the result is `NO_PENDING_MAILBOX`: buy one with `create_mailbox` (with the user's OK on the price). Leave `password` out and Porkbun generates a strong one and returns it ONCE in `password`: give it to the user straight away, it is not shown again (it can be changed later with `set_email_password`). If you pass one, it needs 12-72 characters with an upper case letter, a lower case letter, a number and a special character. A mailbox needs Porkbun's MX records and SPF include at the domain apex (the same records as email forwarding), and the call puts them in place. **If that would delete MX records for another mail service or rewrite the domain's SPF record, it returns `DNS_CHANGE_CONFIRMATION_REQUIRED` with `dnsChanges` and changes (and charges) nothing: tell the user what will change, and only with their OK call again with `confirm_dns_changes: true`.** The answer includes `clientSettings` (IMAP/SMTP hosts and ports) for setting up a mail app. DKIM and DMARC are set up on the website. Needs a verified account email and phone. On this server a password Porkbun generates is not returned: it is saved in this server's outbox as `<address>.password` (owner and group only) and the answer's `password` says where, so the call needs the outbox. A password passed in the call goes through the conversation; leaving it out keeps it there only for whoever reads the file. Moves money or makes a legal document: the client asks the user to approve each call.

Release a held inbound transfer to the registry. Final step of the no-downtime sequence, and the only thing that releases a hold — nothing does it on a timer, so a held transfer waits indefinitely until you call this. Refuses with TRANSFER_ZONE_EMPTY if the zone has no records, which is the outage the hold exists to prevent; only pass force when the domain genuinely needs no DNS at Porkbun. Moves money or makes a legal document: the client asks the user to approve each call.

Send a `webhook.test` event to an endpoint to confirm it's reachable and that signature verification works. The endpoint must be ACTIVE. Delivery happens asynchronously (usually within a minute); check the endpoint's last_success_date via get_webhook afterward.

**Charges the user's saved payment method** (`amount_cents` is integer cents: 803 charges $8.03; tell the user the dollar figure first) and adds the money to their Porkbun account credit immediately. Use it when a purchase failed with INSUFFICIENT_FUNDS and the user wants to continue now — enabling auto top-up does not help in that moment, because it only fires on the next order. **Ask the user before calling, with the figure. This spends real money off a card, not credit they already bought.** Omit `amount_cents` and it charges what the account has configured (or $50 if it never has) — that is the right default, and `amount_source` in the response says which was used. Pass `amount_cents` only when the user wants a specific one-off figure, e.g. enough to cover a particular purchase; it does NOT change their saved setting, so prefer it over calling `configure_auto_topup` for a single charge. Fails with `NO_PAYMENT_METHOD` when nothing is saved to charge (the user has to save a card or buy credit on porkbun.com; the API cannot add one), `CARD_DECLINED` when the card refuses, and `TOPUP_LIMIT_EXCEEDED` when the month's dollars or the frequency run out — the account's monthly spend limit caps top-up dollars as well as domain spend, an account with no limit set gets $100/month, card, auto, MPP and USDC top-ups all count toward it, and there are 5/day and 20/month count caps. `get_auto_topup` reports `monthlyCeiling`, `ceilingSource` and `toppedUpThisMonth`, so check there before promising a user a top-up will go through. Every successful charge emails the account holder. A sandbox key grants simulated credit and charges nothing. Supports dry_run, which previews and charges nothing. On this server the account's monthly API caps are read first (get_api_settings), and a charge over what is left of them is refused with the figures (`over_limit`, carrying Porkbun's own code) before anything is sent. A dry run is not checked: Porkbun's dry run reports the cap itself. Moves…

Get a payment link that adds account credit when paid with the user's CARD over MPP (Machine Payments Protocol), using a Stripe Shared Payment Token from their agent wallet (Stripe's Link Agent Wallet). Use it to add credit when a purchase failed with INSUFFICIENT_FUNDS and no card is saved at Porkbun; to pay for just that one purchase, retry it with `pay_with_card: true` instead, which only charges if the purchase succeeds. Nothing is charged by this call. Pay the returned `payUrl` with an MPP-capable wallet tool, for example Stripe's Link CLI or its MCP server (`link-cli mpp pay <payUrl> -X POST --context "..."`). Newer Link CLI versions stop after creating the spend request: once the user approves in Link, run `link-cli mpp pay <payUrl> --spend-request-id <lsrq_id> -X POST` to complete it. Link rejects a `--context` shorter than 100 characters, and the payment fails without it: write one or two full sentences the user will read when approving, saying what it is for and the dollar amount (e.g. "Adding $20.00 of prepaid credit to my Porkbun account so my AI assistant can register the domains I asked for."). Word it freshly for each payment; Link can refuse a repeat of an identical request. The link answers 402 with the terms, the wallet asks the user to approve the amount, and the credit is added immediately (the response shows the new balance). Tell the user the dollar amount first. The link is single-use, valid 15 minutes. `amount_cents` is integer US cents, $5 to $500; same limits as card top-ups. Not available on sandbox keys (use `sandbox_topup`). If you cannot pay MPP links, `top_up_with_usdc` or the user adding credit at porkbun.com are the alternatives. Not offered on this server: `top_up_with_usdc` (adds credit in USDC on Base over x402, a crypto payment this server does not make). On this server the account's monthly API caps are read first (get_api_settings), and a charge over what is left of them is refused with the figures (`over_limit`, carrying Po…

**Spends account credit, or pays directly by card (`pay_with_card`).** Initiates a transfer of an external domain into Porkbun. Requires the auth/EPP code from the losing registrar, and `cost_cents` must match the current transfer price from `check_domain`. Poll with `get_transfer_status`. Most transfers finish well inside the five-day worst case — two thirds within 24 hours — so do not promise the user a week. .uk and a few TLDs do not support inbound API transfers. Idempotency-safe. **Set `hold_for_dns_setup` unless the user has no DNS to preserve.** A transfer carries only the delegation, so a domain that moves before its records exist at Porkbun goes dark. Holding charges the transfer but parks it until you release it: hold → prepare_transfer → import_dns_records → start_transfer. Nothing releases a held transfer on a timer. **How a purchase is paid.** From prepaid account credit by default; a card saved at Porkbun is never charged by a purchase itself. Or directly by card, for this one purchase: `pay_with_card: true` (the user's card from their Stripe Link agent wallet, held and charged only if the purchase succeeds). Paying in USDC over x402 is not offered on this server. If the credit is short, the call fails with `INSUFFICIENT_FUNDS` carrying `cost`, `balance`, `shortfall` and **`topUpAvailable`** (`dry_run: true` reports the same without charging). Ways forward, simplest first, always telling the user the dollar amount and getting their OK: (1) if they use Stripe Link, retry this exact call with `pay_with_card: true`; (2) when `topUpAvailable` is true a card is saved: `top_up_account_credit` (`amount_cents` at least `topUpAmountToCover`, or omit it for their configured amount), then retry; (3) add credit with `top_up_with_card_mpp` (Link), then retry; (4) the user adds credit at https://porkbun.com/account/credit. If a purchase fails with VERIFICATION_REQUIRED, the phone (`send_phone_verification_code` then `confirm_phone_verification`) and the email (`s…

Turn auto-renewal on or off for a domain in the authenticated account. When auto-renew is on, Porkbun automatically charges your account credit at expiration. When off, you must manually renew or the domain expires. Idempotent. Moves money or makes a legal document: the client asks the user to approve each call.

Edit a domain's contacts. Provide `contacts` keyed by role with ANY subset of registrant/admin/tech/billing (unspecified roles keep their current values), or a single `contact` applied to all four. Mirrors the website: pushes to the registry on thick TLDs, and a registrant change (name/organization/email) fires the same new-owner notice/verification email — no 60-day transfer lock. Supports `dry_run`. Note: a registrant name/organization change on a .au domain, or any registrant change on an address-validation TLD (.de/.nrw), is rejected with REGISTRANT_CHANGE_NOT_SUPPORTED — do those at porkbun.com; admin/tech/billing edits still work. Moves money or makes a legal document: the client asks the user to approve each call.

Update an existing DNS record by its numeric `record_id` (obtained from `list_dns_records`). All fields except `record_id` and `domain` are optional — pass only the ones you want to change. Idempotent: applying the same update twice is a no-op. **Check `warnings` in the response and pass it on.** Porkbun keeps a DNS zone for every domain in the account whether or not the domain is delegated to Porkbun's nameservers, so this write succeeds either way. If the domain points somewhere else, the response is still `SUCCESS` but carries a `warnings` string naming the nameservers that actually answer — the record exists and nothing resolves differently. Do not report plain success in that case: either make the change at the provider that runs those nameservers, or offer `update_nameservers` to point the domain at Porkbun. On this server a TXT record's content is checked before anything is sent: a DKIM key record (v=DKIM1, or p= under _domainkey) must hold a public key that parses (an RSA key of 1024 bits or more, or an ed25519 key), and an SPF record (v=spf1) must have no obvious mistake (an unknown mechanism, a bad address, a term after all, more than 10 lookups). One that fails is refused with what is wrong.

Update the IP addresses associated with an existing glue record. Replaces the full IP list — pass all IPs you want set, not just additions. Idempotent.

Replace the nameservers for a domain in the authenticated account. **This is a full replacement, not an append** — the supplied list becomes the complete set of nameservers. Most TLDs require 2-13 entries. Setting custom nameservers disables Porkbun's free DNS hosting for the domain. Idempotent: applying the same NS list twice is a no-op. The list is applied as a set — the registry may return it in a different order, so do not expect `get_nameservers` to echo your ordering back, and do not treat a reordering as drift. On this server each name is checked for syntax first (a fully qualified host name, no duplicates), and the answer adds nameservers: { before, after }, the set the registry had and the one sent.

Replace the authorization code on an inbound transfer that stalled because the code was wrong, and re-queue it — instead of cancelling, refunding and resubmitting. The new code is validated against the registry before being stored, so a bad one is rejected here rather than failing again days later. Only repairable transfers qualify; others return TRANSFER_NOT_REPAIRABLE. Note that a losing registrar's refusal also surfaces as a bad-auth-code status, so check for a denial notice before assuming the code is the problem.

Update a webhook endpoint. Only the supplied fields change. Set `status` to `DISABLED` to pause deliveries or `ACTIVE` to resume (resuming also clears the consecutive-failure counter). A replacement `url` must satisfy the same public-HTTPS rules as create_webhook. Idempotent. Calls the Porkbun Webhooks API (https://porkbun.com/llms/webhooks).