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

# Sender identities

> Verify a domain, publish its DNS records, rotate DKIM keys, and configure sender authentication.

Create one identity for each sending domain in each region. Verification in one
region does not verify the domain in another. A verified identity allows sender
addresses in that domain or its subdomains. Pending, failed, and suspended
identities cannot send.

## Create and verify a domain

<Tabs>
  <Tab title="Console">
    Open Email, then **Sender identities**. Click **Create identity**, enter the
    domain, and open the created identity. Publish the records shown in
    **DNS records**, then request verification from the identity page.
  </Tab>

  <Tab title="API">
    Send `POST /v1/identities`:

    ```json theme={null}
    {"name":"example.com","tags":{"environment":"production"}}
    ```

    Save `identity.id`. Publish the entries in `identity.dns_records`
    using their exact names, types, and values. Then call
    `POST /v1/identities/{identity_id}/verify` and inspect `identity.status`.
  </Tab>

  <Tab title="CLI">
    Save the JSON request from the API tab as `request-1.json`. Use your configured account and region.

    ```bash theme={null}
    basaltic email identity create --from-file request-1.json
    ```
  </Tab>

  <Tab title="Go">
    Save the JSON request from the API tab as `request-1.json`. Configure credentials, account, and region through the SDK environment variables.

    ```go theme={null}
    package main

    import (
    	"context"
    	"encoding/json"
    	"fmt"
    	"os"

    	basaltic "github.com/basaltic-sh/sdk-go"
    	"github.com/basaltic-sh/sdk-go/email"
    )

    func readJSON(path string, value any) error {
    	data, err := os.ReadFile(path)
    	if err != nil {
    		return err
    	}
    	return json.Unmarshal(data, value)
    }

    func run() error {
    	ctx := context.Background()
    	cfg, err := basaltic.NewConfig(ctx)
    	if err != nil {
    		return err
    	}
    	client := email.New(cfg)
    	var request1 email.CreateIdentityRequest
    	if err := readJSON("request-1.json", &request1); err != nil {
    		return err
    	}
    	result1, err := client.CreateIdentity(ctx, &request1)
    	if err != nil {
    		return err
    	}
    	fmt.Printf("%+v\n", result1)
    	return nil
    }

    func main() {
    	if err := run(); err != nil {
    		fmt.Fprintln(os.Stderr, err)
    		os.Exit(1)
    	}
    }
    ```
  </Tab>
</Tabs>

Records marked `required: true` establish ownership and DKIM signing. Advisory
SPF and DMARC records help receiving providers authenticate and evaluate mail.
Use the returned records rather than constructing regional DNS names yourself.
Keep verification and DKIM records published after verification. DNS changes
can take time to become visible to resolvers.

## Rotate DKIM

Start with `POST /v1/identities/{identity_id}/dkim/rotate`. Publish the newly
returned selector records while keeping the active selector in DNS. Call
`POST /v1/identities/{identity_id}/dkim/rotate/finalize` after the new records
resolve. The response exposes the old selector and `dkim_old_expires_at` during
the overlap period; keep the old DNS records until that timestamp has passed.

Cancel a pending rotation with `DELETE /v1/identities/{identity_id}/dkim/rotate`.
Cancellation discards the pending key and leaves the active selector in place.

## Custom MAIL FROM

A custom MAIL FROM domain controls the envelope sender used for bounce handling.
It must equal the verified identity domain or be a subdomain of it. It is
separate from the visible `From` header.

Set `domain` with `PATCH /v1/identities/{identity_id}/mail-from-domain`, publish the
returned DNS records, and call the corresponding `/verify` endpoint. To return
to the platform envelope domain, send `{"domain":null}`. The `domain` property
is optional; omission preserves the value and an empty string is invalid.

## BIMI

Configure BIMI with `PATCH /v1/identities/{identity_id}/bimi`. `logo_url` must point
to a publicly reachable HTTPS SVG Tiny PS logo. `vmc_url` is an optional HTTPS
certificate URL. Publish the BIMI DNS record and call the `/bimi/verify` endpoint
to validate the referenced assets. Verification does not guarantee that a mail
provider will display the logo.

Send `{"logo_url":null}` to clear BIMI. Omitting `vmc_url` preserves the certificate;
`vmc_url: null` removes only the certificate binding. A certificate cannot be set
without a logo.

## Inspect sending health

The identity's **Metrics** tab shows traffic, feedback, engagement, backlog,
SMTP latency, and reputation through [Telemetry](/email/metrics). Reputation
charts track the rolling 24-hour counts and rates used for sending restrictions.

Use **Settings** to manage receiving, DKIM rotation, MAIL FROM, and BIMI in
separate cards. **DNS records** separates sending records from receiving MX
records. Use **Recipient rules** to create incoming address rules and choose
Notifications topics by name. The identity details show message retention and the selected attachment bucket.
See [receiving email](/email/receiving) for MX records, routing, and limits.

Deleting an identity starts its teardown and removes its associated messages,
receiving configuration, and signing keys. Use its **Settings** tab and danger
zone only after stopping sends that depend on it.

## DNS record groups and alternatives

`dns_records` includes the records for both functions, distinguished by
`group: "sending"` and `group: "receiving"`. Values are ready to copy, including
MX priority. Custom MAIL FROM MX and SPF records belong to the sending group.

Records sharing an `alternative_group` are alternatives. Publish exactly one
alternative for a required group: a DKIM TXT record or its CNAME delegation.
They cannot coexist at the same DNS name. During rotation, keep the current
selector working while publishing one alternative for the pending selector.

Use `PATCH /v1/identities/{identity_id}` to replace tags. Omission preserves tags;
an empty tag object removes them. MAIL FROM and BIMI settings also use PATCH:
omission preserves each setting, while null clears it. Clearing the BIMI logo
also clears its certificate. Clearing only `vmc_url` keeps the logo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.