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.
• 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 Outreach plan 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

Place a DFY email account order

cURL

curl --request POST \
  --url https://api.instantly.ai/api/v2/dfy-email-account-orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "domain": "example.com",
      "email_provider": 1,
      "forwarding_domain": "forward-to-this-domain.com",
      "accounts": []
    }
  ],
  "order_type": "dfy"
}
'

200

{
  "order_placed": true,
  "order_is_valid": true,
  "unavailable_domains": [
    "example.com"
  ],
  "blacklist_domains": [
    "example.com",
    "acme.com"
  ],
  "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": "[e-mail]",
      "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": 4,
  "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",
  "simulation": true,
  "order_items": [
    {
      "domain": "example.com",
      "accounts": [
        {
          "email_address_prefix": "john.doe",
          "first_name": "John",
          "last_name": "Doe"
        }
      ],
      "email_provider": 1,
      "domain_price": 100,
      "accounts_price": 20,
      "total_price": 100,
      "total_discount": 100,
      "forwarding_domain": "example.com",
      "domain_monthly_price": 20
    }
  ],
  "order_error": "unavailable_domains",
  "price_per_domain_per_month": 20
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

items · object[] · required

List of domains and accounts to order

Show child attributes

order_type · enum<string> · required

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

Available options: dfy, pre_warmed_up, extra_accounts

Example:

"dfy"

simulation · boolean · default: false

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:

false

Response

200

application/json

Default Response

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.

Example:

true

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.

Example:

true

unavailable_domains · string[] · required

The list of unavailable domains (if any)

blacklist_domains · string[] · required

The list of blacklisted domains (if any)

Example:

["example.com", "acme.com"]

invalid_domains · string[] · required

The list of invalid domains (if any)

Example:

["example.com", "acme.com"]

invalid_forwarding_domains · string[] · required

The list of invalid forwarding domains (if any)

Example:

["example.com", "acme.com"]

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 · enum<number>[] · required

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

Available options: 1, 2, 3

Example:

[2]

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.

Example:

["example.com", "acme.com"]

invalid_accounts · object[] · required

The list of invalid accounts (if any)

Show child attributes

free_domains · string[] · required

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

Example:

["example.com", "acme.com"]

number_of_domains_ordered · number · required

The number of domains ordered

Example:

1

number_of_accounts_ordered · number · required

The number of accounts ordered

Example:

1

price_per_account_per_month · number · required

The monthly price charged per mailbox. Applies to per-account providers (Google, AirMail). For Microsoft/Outlook orders mailboxes are NOT charged individually — see price_per_domain_per_month instead.

Example:

4

price_per_domain_per_year · number · required

The price per domain per year

Example:

100

total_domains_price_per_year · number · required

The total price per domain per year

Example:

100

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).

Example:

10

total_price_per_month · number · required

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

Example:

100

total_price_per_year · number · required

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

Example:

100

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.

Example:

100

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.

Example:

100

payment_method_last_4_digits · string · required

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

Example:

"1234"

payment_method_brand · string · required

The brand of the payment method used for the order

Example:

"Visa"

payment_method_name_on_card · string · required

The name on the card used for the order

Example:

"John Doe"

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).

Example:

true

order_items · object[] · required

The list of items that were ordered, with the pricing information for each item.

Show child attributes

order_error · enum<string>

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

Available options: 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

Example:

"unavailable_domains"

price_per_domain_per_month · null | number

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.

Example:

20