> For the complete documentation index, see [llms.txt](https://run.emailchaser.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://run.emailchaser.com/api-reference/done-for-you.md).

# Done For You

## Check one exact domain

> Checks whether one specific domain can be registered, rather than searching the names the registrar suggests. Use this to buy a domain the customer chose. Only .com and .org are supported.\
> \
> A domain that simply cannot be bought - taken, malformed, an extension we do not register - answers 200 with available false and a reason. A non-2xx means the check itself could not be made, which is not the same as the domain being taken.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.CheckDfyDomainResponse":{"type":"object","properties":{"available":{"type":"boolean"},"domain":{"type":"string"},"price":{"type":"number"},"reason":{"description":"Reason says why the domain cannot be bought, in words that can be shown\nto a person. Empty when available is true.","type":"string"},"tld":{"type":"string"},"unconfirmed":{"description":"Unconfirmed is true when we could not get an answer at all rather than\nthe answer \"no\". Do not report these as taken; offer a retry.","type":"boolean"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/dfy/domains/check":{"get":{"description":"Checks whether one specific domain can be registered, rather than searching the names the registrar suggests. Use this to buy a domain the customer chose. Only .com and .org are supported.\n\nA domain that simply cannot be bought - taken, malformed, an extension we do not register - answers 200 with available false and a reason. A non-2xx means the check itself could not be made, which is not the same as the domain being taken.","tags":["DoneForYou"],"summary":"Check one exact domain","parameters":[{"schema":{"type":"string"},"description":"The full domain to check, extension included","name":"domain","in":"query","required":true}],"responses":{"200":{"description":"Availability of that exact domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CheckDfyDomainResponse"}}}},"400":{"description":"Missing domain parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"502":{"description":"Domain search service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Check a list of exact domains

> Checks up to 100 exact domains in one call, for a caller who already has the list. One answer per unique domain, in the order given, each following the single check's rules. A registrar failure on one name marks it unconfirmed rather than failing the list; the call fails only when nothing could be checked.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.CheckDfyDomainsResponse":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/models.CheckDfyDomainResponse"}}}},"models.CheckDfyDomainResponse":{"type":"object","properties":{"available":{"type":"boolean"},"domain":{"type":"string"},"price":{"type":"number"},"reason":{"description":"Reason says why the domain cannot be bought, in words that can be shown\nto a person. Empty when available is true.","type":"string"},"tld":{"type":"string"},"unconfirmed":{"description":"Unconfirmed is true when we could not get an answer at all rather than\nthe answer \"no\". Do not report these as taken; offer a retry.","type":"boolean"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.CheckDfyDomainsRequest":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/dfy/domains/check":{"post":{"description":"Checks up to 100 exact domains in one call, for a caller who already has the list. One answer per unique domain, in the order given, each following the single check's rules. A registrar failure on one name marks it unconfirmed rather than failing the list; the call fails only when nothing could be checked.","tags":["DoneForYou"],"summary":"Check a list of exact domains","responses":{"200":{"description":"Availability of each domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CheckDfyDomainsResponse"}}}},"400":{"description":"Empty list, or more than 100 domains","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"502":{"description":"Domain search service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CheckDfyDomainsRequest"}}},"description":"The domains to check","required":true}}}}}
```

## Search available domains

> Checks availability and pricing of domains derived from a brand name. Only .com and .org are supported.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.SearchDfyDomainsResponse":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/models.DfyDomainSuggestion"}},"totalAvailable":{"type":"integer"},"totalChecked":{"type":"integer"}}},"models.DfyDomainSuggestion":{"type":"object","properties":{"available":{"type":"boolean"},"domain":{"type":"string"},"price":{"type":"number"},"tld":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/dfy/domains/search":{"get":{"description":"Checks availability and pricing of domains derived from a brand name. Only .com and .org are supported.","tags":["DoneForYou"],"summary":"Search available domains","parameters":[{"schema":{"type":"string"},"description":"Brand name to derive domains from","name":"query","in":"query","required":true},{"schema":{"type":"string"},"description":"Comma-separated TLDs (default: com,org)","name":"tlds","in":"query"},{"schema":{"type":"integer"},"description":"Maximum suggestions to return","name":"limit","in":"query"}],"responses":{"200":{"description":"Availability results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.SearchDfyDomainsResponse"}}}},"400":{"description":"Invalid search input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"502":{"description":"Domain search service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## List done-for-you orders

> Lists the workspace's done-for-you orders, newest first. Each order carries the same fields as GET /dfy/orders/{id}: status, cost breakdown and the caller-supplied order shape; internal billing and provider sub-records are never exposed.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.ListDfyOrdersResponse":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/models.DfyOrderResponse"}},"total":{"type":"integer"}}},"models.DfyOrderResponse":{"type":"object","properties":{"completedAt":{"description":"CompletedAt is when the order completed (RFC3339), or null.","type":"string"},"cost_breakdown":{},"createdAt":{"type":"string"},"domains":{},"externalOrderId":{"type":"string"},"failureReason":{"type":"string"},"forwardingDomain":{},"id":{"type":"integer"},"mailboxes":{},"processedAt":{"description":"ProcessedAt is when the order started processing (RFC3339), or null.","type":"string"},"status":{"description":"Status is one of: created, pending_approval, processing, completed,\nfailed, partially_completed, canceled.","type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/dfy/orders":{"get":{"description":"Lists the workspace's done-for-you orders, newest first. Each order carries the same fields as GET /dfy/orders/{id}: status, cost breakdown and the caller-supplied order shape; internal billing and provider sub-records are never exposed.","tags":["DoneForYou"],"summary":"List done-for-you orders","parameters":[{"schema":{"type":"integer"},"description":"Page size (default 50, max 200)","name":"limit","in":"query"},{"schema":{"type":"integer"},"description":"Page number, 1-based (default 1)","name":"page","in":"query"}],"responses":{"200":{"description":"Orders and total count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ListDfyOrdersResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"500":{"description":"Failed to retrieve the orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Create a done-for-you order

> Orders domains and pre-warmed mailboxes for the caller's workspace. The order is accepted and provisioned asynchronously; poll GET /dfy/orders/{id} for progress.\
> \
> This call buys domains and charges the card, and it can take longer than the connection is held open — a timeout or a 502 does NOT mean the order failed. Send an Idempotency-Key header and repeat the identical request to find out: a repeat of a key that already placed an order returns that order instead of buying anything again. Reuse the key to retry safely; use a NEW key only when you intend a genuinely different order.\
> \
> Without a key the order is still checked against the workspace's live orders, and one that would buy a domain or a mailbox address already bought is refused with 409 and the id of the order that has it.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.DfyOrderResult":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/models.DfyOrderResponse"}}},"models.DfyOrderResponse":{"type":"object","properties":{"completedAt":{"description":"CompletedAt is when the order completed (RFC3339), or null.","type":"string"},"cost_breakdown":{},"createdAt":{"type":"string"},"domains":{},"externalOrderId":{"type":"string"},"failureReason":{"type":"string"},"forwardingDomain":{},"id":{"type":"integer"},"mailboxes":{},"processedAt":{"description":"ProcessedAt is when the order started processing (RFC3339), or null.","type":"string"},"status":{"description":"Status is one of: created, pending_approval, processing, completed,\nfailed, partially_completed, canceled.","type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.DfyOrderConflictResponse":{"type":"object","properties":{"error":{"type":"string"},"existingOrderId":{"type":"integer"}}},"models.CreateDfyOrderRequest":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/models.DfyDomainInput"}},"forwardingDomain":{"description":"ForwardingDomain is where the purchased domains redirect visitors.","type":"string"},"mailboxes":{"type":"array","items":{"$ref":"#/components/schemas/models.DfyMailboxInput"}}}},"models.DfyDomainInput":{"type":"object","required":["domainName"],"properties":{"domainName":{"type":"string"}}},"models.DfyMailboxInput":{"type":"object","required":["domainName","firstName","lastName","username"],"properties":{"domainName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"profilePicture":{"type":"string"},"username":{"type":"string"}}}}},"paths":{"/dfy/orders":{"post":{"description":"Orders domains and pre-warmed mailboxes for the caller's workspace. The order is accepted and provisioned asynchronously; poll GET /dfy/orders/{id} for progress.\n\nThis call buys domains and charges the card, and it can take longer than the connection is held open — a timeout or a 502 does NOT mean the order failed. Send an Idempotency-Key header and repeat the identical request to find out: a repeat of a key that already placed an order returns that order instead of buying anything again. Reuse the key to retry safely; use a NEW key only when you intend a genuinely different order.\n\nWithout a key the order is still checked against the workspace's live orders, and one that would buy a domain or a mailbox address already bought is refused with 409 and the id of the order that has it.","tags":["DoneForYou"],"summary":"Create a done-for-you order","parameters":[{"schema":{"type":"string"},"description":"Repeat this key to retry the same order safely (max 255 characters)","name":"Idempotency-Key","in":"header"}],"responses":{"202":{"description":"The accepted order, or the order a previous attempt with the same Idempotency-Key already placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.DfyOrderResult"}}}},"400":{"description":"Invalid order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"409":{"description":"A live order already covers one of these domains or mailboxes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.DfyOrderConflictResponse"}}}},"500":{"description":"Failed to create the order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CreateDfyOrderRequest"}}},"description":"Domains, mailboxes and forwarding domain","required":true}}}}}
```

## Get a done-for-you order

> Returns one order. Orders belonging to other workspaces are reported as not found.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.DfyOrderResult":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/models.DfyOrderResponse"}}},"models.DfyOrderResponse":{"type":"object","properties":{"completedAt":{"description":"CompletedAt is when the order completed (RFC3339), or null.","type":"string"},"cost_breakdown":{},"createdAt":{"type":"string"},"domains":{},"externalOrderId":{"type":"string"},"failureReason":{"type":"string"},"forwardingDomain":{},"id":{"type":"integer"},"mailboxes":{},"processedAt":{"description":"ProcessedAt is when the order started processing (RFC3339), or null.","type":"string"},"status":{"description":"Status is one of: created, pending_approval, processing, completed,\nfailed, partially_completed, canceled.","type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/dfy/orders/{id}":{"get":{"description":"Returns one order. Orders belonging to other workspaces are reported as not found.","tags":["DoneForYou"],"summary":"Get a done-for-you order","parameters":[{"schema":{"type":"integer"},"description":"Order ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.DfyOrderResult"}}}},"400":{"description":"Invalid order id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Failed to retrieve the order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```