# Update a sending domain (/docs/api-reference/domains/update-domain)

Shares one of the organization's own domains with its sub-accounts (they may then send from it, through the organization's reputation), or stops sharing it.

`PATCH https://api.coss.com/v1/domains/{id}`

Authenticate with your API key as a bearer token (`Authorization: Bearer coss_test_…`). Responses are JSON with snake_case fields; errors are `{ error: { type, code, message, param?, issues?, request_id } }` (https://coss.com/docs/api-reference/errors.md).

## Path parameters

- `id` (string, required): The domain's id.

## Request body

- `shared_with_subaccounts` (boolean, required): Let your sub-accounts send from this domain of yours (through your organization's reputation).

## Example request

TypeScript (the `coss` package):

```ts
import { Coss } from "coss";

const coss = new Coss({
  apiKey: process.env.COSS_API_KEY,
  baseUrl: "https://api.coss.com",
});

const { data, error } = await coss.domains.update("dom_01k7c8m4q2f3e9v6t5r1n0p8yz", {
  shared_with_subaccounts: true,
});
```

HTTP:

```sh
curl -X PATCH "https://api.coss.com/v1/domains/dom_01k7c8m4q2f3e9v6t5r1n0p8yz" \
  -H "Authorization: Bearer $COSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "shared_with_subaccounts": true
}'
```

Python:

```python
from coss import Coss

client = Coss()  # api_key= or COSS_API_KEY

client.domains.update(
    id="dom_01k7c8m4q2f3e9v6t5r1n0p8yz",
    shared_with_subaccounts=True,
)
```

Go:

```go
import (
	"context"

	coss "github.com/cosscom/coss-go"
	cossclient "github.com/cosscom/coss-go/client"
)

client := cossclient.NewClient() // option.WithAPIKey(…) or COSS_API_KEY

request := &coss.UpdateDomainRequest{
    ID: "dom_01k7c8m4q2f3e9v6t5r1n0p8yz",
    SharedWithSubaccounts: true,
}
client.Domains.Update(
    context.TODO(),
    request,
)
```

Ruby:

```ruby
require "coss"

client = Coss::Client.new # api_key: or COSS_API_KEY

client.domains.update(
  id: "dom_01k7c8m4q2f3e9v6t5r1n0p8yz",
  shared_with_subaccounts: true
)
```

PHP:

```php
<?php

use Coss\Coss;
use Coss\Domains\Requests\UpdateDomainRequest;

$client = new Coss(); // apiKey: or COSS_API_KEY

$client->domains->update(
    'dom_01k7c8m4q2f3e9v6t5r1n0p8yz',
    new UpdateDomainRequest([
        'sharedWithSubaccounts' => true,
    ]),
);
```

Java:

```java
import com.coss.Coss;
import com.coss.resources.domains.requests.UpdateDomainRequest;

Coss client = Coss.builder().build(); // .apiKey(…) or COSS_API_KEY

client.domains().update(
    "dom_01k7c8m4q2f3e9v6t5r1n0p8yz",
    UpdateDomainRequest
        .builder()
        .sharedWithSubaccounts(true)
        .build()
);
```

.NET:

```csharp
using Coss;

var client = new CossClient(); // apiKey: or COSS_API_KEY

await client.Domains.UpdateAsync(
    new UpdateDomainRequest { Id = "dom_01k7c8m4q2f3e9v6t5r1n0p8yz", SharedWithSubaccounts = true }
);
```

## Response 200

The domain.

- `object` ("domain", required)
- `id` (string, required)
- `name` (string, required): The domain, lower-cased.
- `status` ("pending" | "verified" | "temporary_failure" | "failed" | "deleting", required): `pending` while the records are being checked, `verified` once they are, `temporary_failure` after a transient DNS problem, and `failed` when verification gave up (72 hours) — restart it with the verify endpoint. `deleting` is a removal in progress.
- `can_send` (boolean, required): Whether live keys may send from this domain right now.
- `region` (string | null, required)
- `mail_from_domain` (string, required): The envelope sender subdomain bounces come back to.
- `mail_from_status` ("pending" | "success" | "temporary_failure" | "failed", required)
- `records` (object[], required): The DNS records to publish, with the result of the last check.
  - `purpose` ("dkim" | "mail_from_mx" | "mail_from_spf" | "dmarc", required): What the record is for: `dkim` signs messages, `mail_from_mx` and `mail_from_spf` set up the bounce subdomain, `dmarc` is recommended but not required.
  - `type` ("CNAME" | "MX" | "TXT", required)
  - `name` (string, required): The fully qualified record name to create.
  - `value` (string, required)
  - `priority` (integer | null, required): `MX` records only.
  - `required` (boolean, required): `false` for records that are only recommended.
  - `status` ("verified" | "missing" | "mismatch" | "not_checked", required): What the last DNS check saw. `not_checked` means DNS has not been consulted yet.
  - `found` (string[], required): What DNS returned when it did not match.
- `created_at` (string, required, date-time)
- `last_checked_at` (string | null, required, date-time)
- `verified_at` (string | null, required, date-time)
- `failed_at` (string | null, required, date-time)
- `tracking` (object | null, required): A domain's custom tracking domain: open pixels and click redirects of emails sent from the domain use it while it is `active`.
  - `hostname` (string, required): The tracking hostname, a subdomain of the domain.
  - `status` ("pending" | "active" | "temporary_failure" | "failed" | "deleting", required): `pending` until the CNAME points at coss.com and its certificate is issued, `active` once links and open pixels of emails sent from the domain use it, `temporary_failure` when an active hostname stopped working (emails fall back to the default tracking host meanwhile), `failed` when setup gave up (72 hours) — restart it with the domain's verify endpoint. `deleting` is a removal in progress.
  - `record` (object, required): The DNS record to publish, with the result of the last check.
    - `type` ("CNAME", required)
    - `name` (string, required): The fully qualified record name to create.
    - `value` (string, required): The host the record must point at.
    - `status` ("verified" | "missing" | "mismatch" | "not_checked", required): What the last DNS check saw. `not_checked` means DNS has not been consulted yet.
    - `found` (string[], required): What DNS returned when it did not match.
  - `message` (string | null, required): What is holding the hostname up, when the certificate provider said.
  - `created_at` (string, required, date-time)
  - `last_checked_at` (string | null, required, date-time)
  - `activated_at` (string | null, required, date-time)
  - `failed_at` (string | null, required, date-time)
- `receiving` (object | null, required): A domain's receiving hostname: email sent to any address at it becomes a received email of its environment.
  - `hostname` (string, required): The hostname that receives email: the domain itself or a subdomain of it.
  - `environment_id` (string, required): The environment its received emails are delivered to.
  - `record` (object, required): The MX record to publish, with the result of the last check. Mail for the hostname is received as soon as it reaches coss.com; the check only shows what DNS serves.
    - `type` ("MX", required)
    - `name` (string, required): The fully qualified record name to create.
    - `value` (string, required): The mail exchange the record must point at.
    - `priority` (integer, required)
    - `status` ("verified" | "missing" | "mismatch" | "not_checked", required): What the last DNS check saw: `verified` once the most preferred MX records point at coss.com. `not_checked` means DNS has not been consulted yet.
    - `found` (string[], required): What DNS returned when it did not match.
  - `created_at` (string, required, date-time)
  - `last_checked_at` (string | null, required, date-time)
- `bimi` (object, required): The result of the last BIMI check: whether mailbox providers can find the domain's brand logo and certificate. The record and the certificate are your own.
  - `status` ("not_checked" | "missing" | "invalid" | "configured", required): `configured` when the BIMI record is valid and DMARC is enforced, `invalid` when a record exists but something is wrong (see `issues`), `missing` when there is no record, and `not_checked` until DNS has been consulted. coss.com checks DNS only: mailbox providers still validate the logo and the certificate.
  - `name` (string, required): Where the BIMI record was found, or looked up when there is none: `default._bimi.<domain>`, or the organizational domain's when only it has one.
  - `record` (string | null, required): The `v=BIMI1` record found.
  - `logo_url` (string | null, required): The record's logo URL (`l=`).
  - `certificate_url` (string | null, required): The record's VMC or CMC certificate URL (`a=`).
  - `dmarc_policy` ("none" | "quarantine" | "reject" | null, required): The DMARC policy that applies to the domain (the organizational domain's `sp` when it has no record of its own), `null` without a DMARC record.
  - `issues` (object[], required): What keeps the domain's logo from showing, as far as DNS tells.
    - `code` ("dmarc_missing" | "dmarc_not_enforced" | "dmarc_partial" | "record_multiple" | "record_invalid" | "logo_missing" | "logo_not_https" | "certificate_missing" | "certificate_not_https", required)
    - `message` (string, required)
- `subaccount_id` (string | null, required): The sub-account the domain belongs to (only it sends from it, with its own reputation); `null` for the organization's own.
- `shared_with_subaccounts` (boolean, required): An organization's domain its sub-accounts may send from too.

Example:

```json
{
  "object": "domain",
  "id": "dom_01k7c8m4q2f3e9v6t5r1n0p8yz",
  "name": "acme.com",
  "status": "verified",
  "can_send": true,
  "region": "us-east-1",
  "mail_from_domain": "send.acme.com",
  "mail_from_status": "success",
  "records": [
    {
      "priority": null,
      "required": true,
      "status": "verified",
      "found": [],
      "purpose": "dkim",
      "type": "CNAME",
      "name": "x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e._domainkey.acme.com",
      "value": "x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e.dkim.amazonses.com"
    },
    {
      "priority": 10,
      "required": true,
      "status": "verified",
      "found": [],
      "purpose": "mail_from_mx",
      "type": "MX",
      "name": "send.acme.com",
      "value": "feedback-smtp.us-east-1.amazonses.com"
    },
    {
      "priority": null,
      "required": true,
      "status": "verified",
      "found": [],
      "purpose": "mail_from_spf",
      "type": "TXT",
      "name": "send.acme.com",
      "value": "v=spf1 include:amazonses.com ~all"
    },
    {
      "priority": null,
      "required": false,
      "status": "verified",
      "found": [],
      "purpose": "dmarc",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;"
    }
  ],
  "created_at": "2026-01-15T09:30:00.000Z",
  "last_checked_at": "2026-01-15T09:42:10.000Z",
  "verified_at": "2026-01-15T09:42:10.000Z",
  "failed_at": null,
  "tracking": {
    "hostname": "links.acme.com",
    "status": "active",
    "record": {
      "type": "CNAME",
      "name": "links.acme.com",
      "value": "track.cosslinks.com",
      "status": "verified",
      "found": []
    },
    "message": null,
    "created_at": "2026-01-15T09:45:00.000Z",
    "last_checked_at": "2026-01-15T09:52:00.000Z",
    "activated_at": "2026-01-15T09:52:00.000Z",
    "failed_at": null
  },
  "receiving": null,
  "bimi": {
    "status": "configured",
    "name": "default._bimi.acme.com",
    "record": "v=BIMI1; l=https://acme.com/brand/logo.svg; a=https://acme.com/brand/vmc.pem",
    "logo_url": "https://acme.com/brand/logo.svg",
    "certificate_url": "https://acme.com/brand/vmc.pem",
    "dmarc_policy": "reject",
    "issues": []
  },
  "subaccount_id": null,
  "shared_with_subaccounts": false
}
```

## Errors

- `400`: The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).
- `401`: The API key is missing, invalid, revoked or expired (`authentication_error`).
- `403`: The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).
- `404`: No domain with this id exists in this organization (`not_found`).
- `413`: The request body is larger than 5 MB (`payload_too_large`).
- `415`: The body is not sent as `application/json` (`unsupported_media_type`).
- `422`: The body failed validation (`validation_error`), or the domain is a sub-account's (`not_shareable`).
- `429`: Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).
- `500`: Unexpected server error (`api_error` / `internal_error`).
- `503`: The API key could not be verified right now; retry (`service_unavailable`).