Sender identities

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

Console
API
CLI
Go

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.

Send POST /v1/identities:

{"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.

Save the JSON request from the API tab as request-1.json. Use your configured account and region.

basaltic email identity create --from-file request-1.json

Save the JSON request from the API tab as request-1.json. Configure credentials, account, and region through the SDK environment variables.

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

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

Get started

Products

Platform

Help

Sender identities

Create and verify a domain

Rotate DKIM

Custom MAIL FROM

BIMI

Inspect sending health

DNS record groups and alternatives

​Create and verify a domain

​Rotate DKIM

​Custom MAIL FROM

​BIMI

​Inspect sending health

​DNS record groups and alternatives

Create and verify a domain

Rotate DKIM

Custom MAIL FROM

BIMI

Inspect sending health

DNS record groups and alternatives