Schedule Buy

Create Plan

Create and LOCK a buying plan. PLACES REAL CREDIT HOLDS IMMEDIATELY.

Locking reserves credits for the WHOLE plan up front - one hold per batch, up to two hundred of them - even though the domains are bought a batch a day afterwards. The credits are gone from your spendable balance the moment this returns. total_credits_held in the response is the figure.

Org admins and owners only, and only for an org on a paid or pre-funded plan. 402 if the balance cannot cover the plan, 429 if the org has locked more than five plans this hour, 400 for an unsupported extension or an empty plan. With reuse_domains, 409 when a domain's mailbox count changed (or it filled up) while the plan was locking: nothing stays held, re-read the domains and lock again.

At least one persona_ids entry is required. Manual registrants / mailbox_aliases are not accepted for new plans. idle_mailboxes_snapshot is your own count, used to detect drift - the server recomputes it and returns its own as server_idle_mailboxes.

Send an Idempotency-Key header. A retried lock without one places a second full set of holds.

post/mailboxes/schedule-buy/plans

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/mailboxes/schedule-buy/plans
  • Auth: HTTP bearer

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

target_monthly_volumeinteger required

Contacts you intend to reach per month

idle_mailboxes_snapshotinteger required

Idle mailboxes you already hold, from /suggest

warmup_provider'warmy' | 'instantly' | 'smartlead'

Warmup engine the bought mailboxes are enrolled with

domain_tldstring

Extension to buy, e.g. '.com'

registrantsobject[]

Not accepted for new plans. Use persona_ids.

mailbox_aliasesobject[]

Not accepted for new plans. Use persona_ids.

persona_idsinteger[] nullable

Sender identity IDs. At least one is required to start a schedule.

workspace_uidstring nullable

Existing provisioning workspace to reuse

daily_send_capinteger

Sends per mailbox per day

sending_days_per_monthinteger

Sending days assumed per month

mailboxes_per_domaininteger

Mailboxes bought on each domain

domains_per_batchinteger

Domains bought per daily batch

reuse_domainsstring[] nullable

Adopt these owned domains instead of buying. Each must have fewer live mailboxes than mailboxes_per_domain; the plan tops it up and holds credits for exactly the missing ones

domain_namesstring[] nullable

Approved names to buy, in order

Response

Successful Response

dataMailboxDomainPayload required

An open envelope for one provider/deliverability result.

Open on purpose. These payloads are provider state and advisory reads whose contents grow with the product, and a dropped field reads as "nothing to report" rather than "we did not tell you". Every value passes through scrub_vendor_names on the way in.

Changes

No recorded changes to this operation across all 2 revisions of this API.