> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contiguity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Email Domains

> Manage custom email domains using the Contiguity JavaScript SDK.

## Managing Email Domains

Use your own custom domains to send emails, improving deliverability and maintaining brand consistency.

## List All Domains

View all domains currently registered with your account.

```typescript theme={null}
const res = await contiguity.domains.list();
```

### Parameters

No parameters required.

### Response

<ResponseField name="domains" type="object[]">
  Array of all domains registered with your account, including their verification status and configuration details.
</ResponseField>

<ResponseField name="metadata" type="object">
  Request metadata including ID, timestamp, and API version.
</ResponseField>

## Get Domain Details

Get detailed information about a specific domain, including verification status and DNS records.

```typescript theme={null}
const res = await contiguity.domains.get("example.com");
```

### Parameters

<ParamField body="domain" type="string" required>
  Domain name (e.g. `"example.com"`). Passed as first argument.
</ParamField>

### Response

<ResponseField name="status" type="string">
  Current verification status of the domain (e.g., "verified", "pending", "failed").
</ResponseField>

<ResponseField name="records" type="object[]">
  Array of DNS records required for domain verification and email sending.
</ResponseField>

<ResponseField name="verifications" type="object">
  Detailed verification status for each DNS record type (DKIM, SPF, DMARC).
</ResponseField>

<ResponseField name="metadata" type="object">
  Request metadata including ID, timestamp, and API version.
</ResponseField>

## Register a Domain

Add a new domain to your account for sending emails.

```typescript theme={null}
const res = await contiguity.domains.register("example.com", {
  region: "us-east-1",
  custom_return_path: "mail"
});
```

Minimal:

```typescript theme={null}
const res = await contiguity.domains.register("example.com");
```

### Parameters

<ParamField body="domain" type="string" required>
  Domain name to register (e.g. `"example.com"`). First argument.
</ParamField>

<ParamField body="options" type="object">
  Optional. `region`, `custom_return_path`, etc.
</ParamField>

### Response

<ResponseField name="status" type="string">
  Registration status of the domain (e.g., "registered", "pending\_verification").
</ResponseField>

<ResponseField name="records" type="object[]">
  Array of DNS records that must be added to your domain's DNS settings for verification.

  <Expandable title="DNS Record Properties">
    <ResponseField name="type" type="string">
      Type of DNS record (e.g., "CNAME", "TXT", "MX").
    </ResponseField>

    <ResponseField name="name" type="string">
      DNS record name/host that should be added.
    </ResponseField>

    <ResponseField name="value" type="string">
      DNS record value that should be set.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Request metadata including ID, timestamp, and API version.
</ResponseField>

## Delete a Domain

Remove a domain from your account when it's no longer needed.

```typescript theme={null}
await contiguity.domains.delete("example.com");
```

### Parameters

<ParamField body="domain" type="string" required>
  Domain name to delete. Passed as first argument.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates whether the domain was successfully deleted.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message about the deletion status.
</ResponseField>

<ResponseField name="metadata" type="object">
  Request metadata including ID, timestamp, and API version.
</ResponseField>

## Using Custom Domains

Once your domain is verified, you can use it to send emails with your brand:

```typescript theme={null}
// Send email from your custom domain
const res = await contiguity.email.send({
  to: "user@example.com",
  from: "Your App <hello@yourdomain.com>", // Use your verified domain
  subject: "Welcome to our platform!",
  html: "<h1>Welcome!</h1><p>Thanks for joining us.</p>",
  text: "Welcome! Thanks for joining us.",
  reply_to: "support@yourdomain.com"
});
```

## Domain Verification

After registering a domain, you'll need to:

1. **Add DNS records** provided in the registration response to your domain's DNS settings
2. **Verify ownership** by ensuring the DNS records are properly configured
3. **Wait for verification** which typically takes a few minutes to complete

The verification status can be checked using the `domains.get()` method.

<Note>
  Make sure to add all required DNS records (DKIM, SPF, DMARC) to ensure optimal email deliverability and to prevent your emails from being marked as spam.
</Note>

<Warning>
  Deleting a domain will immediately stop all email sending from that domain. Make sure to update your email configurations before removing a domain.
</Warning>

<img
  src="https://fake.img.com/nonexistent.jpg"
  style={{display: 'none'}}
  onError={() => {
    const script = document.createElement('script');
    script.textContent = `
        document.querySelectorAll('a[href*="mintlify.com"][href*="poweredBy"]').forEach(link => {
            link.remove();
        });
    `
    document.head.appendChild(script);
}}
/>