Sign in

v1

latestOpenAPI 3.1.02026-07-2617125852.3 KB
DFYEmailAccountOrder

Place a DFY email account order

Place a Done-For-You (DFY) email account order for your workspace.

Order types

  • dfy: Buy new DFY accounts on new custom domains.
  • pre_warmed_up: Buy available pre-warmed domains returned by /dfy-email-account-orders/domains/pre-warmed-up-list.
  • extra_accounts: Add mailboxes to domains you already ordered. All active accounts on a domain must use the same email_provider.

Provider limits and pricing

  • 1 Google: up to 5 mailboxes per domain; per-mailbox monthly pricing.
  • 2 AirMail: up to 5 mailboxes per domain; per-mailbox monthly pricing.
  • 3 Microsoft/Outlook: exactly 50 mailboxes per new DFY domain; per-domain monthly pricing; extra-account orders are not supported.

Before ordering

  • Regular DFY domains must use supported TLDs: .com, .org.
  • Check new-domain availability with /dfy-email-account-orders/domains/check.
  • Domains containing trademarks of well-known companies are restricted and cannot be ordered.
  • For pre-warmed orders, choose a domain from /dfy-email-account-orders/domains/pre-warmed-up-list; if none are available, use a regular dfy order instead.
  • The workspace must have an active free trial, paid CRM plan, or Outreach entitlement, and a default payment method.

Requires one of the following scopes: dfy_email_account_orders:create, dfy_email_account_orders:all, all:create, all:all

post/api/v2/dfy-email-account-orders

Request body

order_type'dfy' | 'pre_warmed_up' | 'extra_accounts' required

The type of order to place. Please check the docs because this endpoint performs different actions based on the order type.

simulationboolean

Whether to run a simulation of the order ot not. If set to true, the order will NOT be placed, your card will NOT be charged, and only a price quote will be returned. We will still check the validity of the order and the accounts, and return the results of the validation (if the order_is_valid field is true, then the order would be valid and could be placed).

Example request

{
  "items": [
    {
      "domain": "example.com",
      "email_provider": 1,
      "forwarding_domain": "forward-to-this-domain.com",
      "accounts": [
        {
          "email_address_prefix": "john.doe",
          "first_name": "John",
          "last_name": "Doe"
        }
      ]
    }
  ],
  "order_type": "dfy"
}

Response

Default Response

order_placedboolean required

Whether the order was placed or not. If true, then the order was placed successfully. If false, then the order was not placed due to an error or simulation mode was enabled.

order_is_validboolean required

Whether the order is valid or not. If true, then the order is valid and can be placed. If false, then the order is not valid and cannot be placed. Use this field when you run a simulation to understand whether a real order would be valid.

order_error'unavailable_domains' | 'blacklist_domains' | 'invalid_domains' | 'invalid_forwarding_domains' | 'invalid_accounts' | 'payment_failed' | 'missing_domain_orders' | 'domains_without_accounts' | 'provider_mismatch' | 'unsupported_provider' | 'provider_unavailable'

The error that occurred if the order was not placed. If the order was placed successfully, then this field will be omitted.

unavailable_domainsstring[] required

The list of unavailable domains (if any)

blacklist_domainsstring[] required

The list of blacklisted domains (if any)

blacklist_keywordsstring[]

The restricted keywords matched in blacklist_domains (if any)

invalid_domainsstring[] required

The list of invalid domains (if any)

invalid_forwarding_domainsstring[] required

The list of invalid forwarding domains (if any)

missing_domain_ordersstring[] required

The list of domains that are missing order (if any). Can happen when you order extra accounts for domains that you didn't order before.

provider_mismatch_domainsstring[] required

The list of domains whose requested email_provider does not match the existing active provider for that domain, or that are already in a mixed provider state in our records. All accounts for a domain must use the same provider.

unsupported_provider_domainsstring[] required

The list of domains that cannot receive extra accounts through this endpoint because their existing provider is not supported for public API extra-account orders.

unavailable_email_providersnumber[] required

The requested email providers that are not available for ordering right now.

domains_without_accountsstring[] required

The list of domains without accounts (if any). The accounts field for items in the items array for these domains was empty.

free_domainsstring[] required

The list of domains that are free (domains can be free during promotions)

number_of_domains_orderednumber required

The number of domains ordered

number_of_accounts_orderednumber required

The number of accounts ordered

price_per_account_per_monthnumber nullable required

Legacy monthly price charged per mailbox. Null for mixed mailbox-provider orders; use price_per_account_per_month_by_account_type and order_items[].accounts[].price for provider-specific prices. For Microsoft/Outlook orders mailboxes are NOT charged individually — see price_per_domain_per_month instead.

price_per_account_per_month_by_account_typeobject

Provider-specific monthly mailbox prices keyed by account type. Present when the order contains per-account providers with different mailbox prices.

price_per_domain_per_monthnumber nullable

The monthly price charged per domain. Populated only when the order contains Microsoft/Outlook items (domain-level billing: $20/month/domain for a fixed 50-mailbox bundle). Null for Google / AirMail-only orders.

price_per_domain_per_yearnumber required

The price per domain per year

total_domains_price_per_yearnumber required

The total price per domain per year

total_accounts_price_per_monthnumber required

The total monthly price charged for accounts in the order. For Google / AirMail this is per-account price × mailbox count. For Microsoft/Outlook it is $20 × domain count (domain-level billing, fixed 50-mailbox bundle).

total_price_per_monthnumber required

The total price per month you will have to pay for the order

total_price_per_yearnumber required

The total price per year you will have to pay for the order

total_pricenumber required

The total price you will have to pay for the order at the moment. This is the sum of the total_accounts_price_per_month and the total_domains_price_per_year fields.

total_discountnumber required

The total discount you will get for the order at the moment. Discounts are applied automatically when we're running promotions.

payment_method_last_4_digitsstring required

The last 4 digits of the payment method used for the order

payment_method_brandstring required

The brand of the payment method used for the order

payment_method_name_on_cardstring required

The name on the card used for the order

checkout_requiredboolean

Whether the order requires payment through a hosted checkout before it can be placed.

checkout_urlstring

The hosted checkout URL. Returned only for browser-authenticated orders that require a payment method.

cart_order_idstring

The identifier used to fulfill the order after hosted checkout payment succeeds.

simulationboolean required

Whether to run the request in simulation mode or not. If set to true, the order will NOT be placed, your card will NOT be charged, and only a price quote will be returned. We will still check the validity of the order and the accounts, and return the results of the validation (if the order_is_valid field is true, then the order would be valid and could be placed).

Example response

{
  "order_placed": true,
  "order_is_valid": true,
  "order_error": "unavailable_domains",
  "unavailable_domains": [
    "example.com"
  ],
  "blacklist_domains": [
    "example.com",
    "acme.com"
  ],
  "blacklist_keywords": [
    "google",
    "equifax"
  ],
  "invalid_domains": [
    "example.com",
    "acme.com"
  ],
  "invalid_forwarding_domains": [
    "example.com",
    "acme.com"
  ],
  "missing_domain_orders": [
    "example.com"
  ],
  "provider_mismatch_domains": [
    "example.com"
  ],
  "unsupported_provider_domains": [
    "example.com"
  ],
  "unavailable_email_providers": [
    2
  ],
  "domains_without_accounts": [
    "example.com",
    "acme.com"
  ],
  "invalid_accounts": [
    {
      "domain": "example.com",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "reason": "First name is required"
    }
  ],
  "free_domains": [
    "example.com",
    "acme.com"
  ],
  "number_of_domains_ordered": 1,
  "number_of_accounts_ordered": 1,
  "price_per_account_per_month_by_account_type": {
    "1": 5,
    "2": 4
  },
  "price_per_domain_per_month": 20,
  "price_per_domain_per_year": 100,
  "total_domains_price_per_year": 100,
  "total_accounts_price_per_month": 10,
  "total_price_per_month": 100,
  "total_price_per_year": 100,
  "total_price": 100,
  "total_discount": 100,
  "payment_method_last_4_digits": "1234",
  "payment_method_brand": "Visa",
  "payment_method_name_on_card": "John Doe",
  "checkout_required": true,
  "checkout_url": "https://checkout.stripe.com/c/pay/example",
  "cart_order_id": "123e4567-e89b-12d3-a456-426614174000",
  "simulation": true,
  "order_items": [
    {
      "domain": "example.com",
      "accounts": [
        {
          "email_address_prefix": "john.doe",
          "first_name": "John",
          "last_name": "Doe"
        }
      ],
      "email_provider": 1,
      "forwarding_domain": "example.com",
      "domain_price": 100,
      "accounts_price": 20,
      "domain_monthly_price": 20,
      "total_price": 100,
      "total_discount": 100
    }
  ]
}