---
title: "Place a DFY email account order"
method: POST
path: "/api/v2/dfy-email-account-orders"
tags: ["DFYEmailAccountOrder"]
---

# Place a DFY email account order

`POST /api/v2/dfy-email-account-orders`

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`

## Request body

- object
  - `items` object[], required — List of domains and accounts to order
    - `domain` string, required — The domain to use for the email accounts.For regular DFY accounts the only allowed domain extensions (tlds) are .com and .org.For regular DFY accounts - you can check the domain availability using the /dfy-email-account-orders/domains/check endpoint before placing an order.For pre-warmed up domains - use the /dfy-email-account-orders/domains endpoint to get a list of available domains.Domains containing trademarks of well-known companies are restricted and cannot be ordered.
    - `email_provider` 1 | 2 | 3 — The mailbox product to order. Defaults to Google when omitted. Options: - 1: Google. Up to 5 mailboxes per domain; priced per mailbox monthly. - 2: AirMail. Up to 5 mailboxes per domain; priced per mailbox monthly. - 3: Microsoft/Outlook. Exactly 50 mailboxes per new DFY domain; priced per domain monthly.
    - `forwarding_domain` string — An optional domain to forward emails to. This domain must be different from the main domain.
    - `accounts` object[] — List of email accounts to create (only if `pre_warmed_up` field is false). For pre-warmed up domains this field will be ignored because the accounts are already created and can't be changed. Please provide minimum 1 and maximum 5 accounts per domain for Google or AirMail, or exactly 50 for Microsoft/Outlook.
      - `email_address_prefix` string, required — The prefix for the email address (the part before the @). For instance, if the email address is "john.doe@example.com", then the email_address_prefix is "john.doe".
      - `first_name` string, required — The first name of the account owner
      - `last_name` string, required — The last name of the account owner
  - `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.
  - `simulation` boolean — 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).

## Response `200`

Default Response

- object
  - `order_placed` boolean, 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_valid` boolean, 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_domains` string[], required — The list of unavailable domains (if any)
  - `blacklist_domains` string[], required — The list of blacklisted domains (if any)
  - `blacklist_keywords` string[] — The restricted keywords matched in `blacklist_domains` (if any)
  - `invalid_domains` string[], required — The list of invalid domains (if any)
  - `invalid_forwarding_domains` string[], required — The list of invalid forwarding domains (if any)
  - `missing_domain_orders` string[], 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_domains` string[], 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_domains` string[], 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_providers` number[], required — The requested email providers that are not available for ordering right now.
  - `domains_without_accounts` string[], required — The list of domains without accounts (if any). The `accounts` field for items in the `items` array for these domains was empty.
  - `invalid_accounts` object[], required — The list of invalid accounts (if any)
    - `domain` string, required — The domain
    - `first_name` string, required — The account first name
    - `last_name` string, required — The account last name
    - `email` string, required — The account email
    - `reason` string, required — The reason why the account is invalid
  - `free_domains` string[], required — The list of domains that are free (domains can be free during promotions)
  - `number_of_domains_ordered` number, required — The number of domains ordered
  - `number_of_accounts_ordered` number, required — The number of accounts ordered
  - `price_per_account_per_month` number, 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_type` object — 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_month` number, 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_year` number, required — The price per domain per year
  - `total_domains_price_per_year` number, required — The total price per domain per year
  - `total_accounts_price_per_month` number, 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_month` number, required — The total price per month you will have to pay for the order
  - `total_price_per_year` number, required — The total price per year you will have to pay for the order
  - `total_price` number, 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_discount` number, 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_digits` string, required — The last 4 digits of the payment method used for the order
  - `payment_method_brand` string, required — The brand of the payment method used for the order
  - `payment_method_name_on_card` string, required — The name on the card used for the order
  - `checkout_required` boolean — Whether the order requires payment through a hosted checkout before it can be placed.
  - `checkout_url` string — The hosted checkout URL. Returned only for browser-authenticated orders that require a payment method.
  - `cart_order_id` string — The identifier used to fulfill the order after hosted checkout payment succeeds.
  - `simulation` boolean, 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).
  - `order_items` object[], required — The list of items that were ordered, with the pricing information for each item.
    - `domain` string, required — The domain to use for the email accounts.
    - `accounts` object[], required — The list of accounts that were ordered for the domain.
      - `email_address_prefix` string, required — The email address prefix of the account.
      - `first_name` string, required — The account first name.
      - `last_name` string, required — The account last name.
    - `email_provider` 1 | 2 | 3, required — The mailbox product to order. Defaults to Google when omitted. Options: - 1: Google. Up to 5 mailboxes per domain; priced per mailbox monthly. - 2: AirMail. Up to 5 mailboxes per domain; priced per mailbox monthly. - 3: Microsoft/Outlook. Exactly 50 mailboxes per new DFY domain; priced per domain monthly.
    - `forwarding_domain` string — The forwarding domain to use for the domain.
    - `domain_price` number, required — The price for the domain.
    - `accounts_price` number, required — The total price for the accounts in the item. For Google / AirMail this is `per-account price × mailbox count`. For Microsoft/Outlook it is the flat `$20` per-domain bundle.
    - `domain_monthly_price` number, nullable — The monthly price for the domain bundle. Populated only for providers whose billing is domain-level (Microsoft/Outlook — $20/month/domain, 50 mailboxes). Null for per-account providers.
    - `total_price` number, required — The total price for the item.
    - `total_discount` number, required — The total discount for the item.

## Other responses

- `401` — This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
- `402` — This request cannot be fulfilled because the workspace does not have an active paid plan
- `404` — The requested resource was not found
- `429` — You have exceeded the rate limit. Please check the rate limit docs for more information.

---

[API](https://skmtc.net/instantly/apis/api-explorer.md) · [All operations](https://skmtc.net/instantly/apis/api-explorer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/instantly/api-explorer/versions/378d1e253fe7/schema)