Deployments.ai Docs
Platform

Sending email

Send transactional email from verified domains through sending tenants.

Sending email delivers one-way transactional messages, such as notifications and sign-in links, from a domain you own. Each message goes out through a sending tenant that isolates its reputation from other tenants. Use it when your application sends mail. When an agent needs an address that receives mail and holds a conversation, use Agent email instead.

Availability

Sending email runs on the agent email runtime, which an installation from the customer root runs by default. Delivery needs SES production access in the installation's region.

How it differs from agent email

Sending emailAgent email
DirectionSend onlyReceive and send
Routes/v1/email/v1/agent-email
Message historyNone. The platform stores no message bodies.Messages, threads, and attachments
Capabilitiesemail:read, email:write, email:adminagent-email:read, agent-email:write, agent-email:admin

Agent email capabilities do not authorize /v1/email routes.

Resources

ResourceWhat it is
Sending tenantAn isolated sender with its own provider tenant and configuration set. status is active or paused. sendingStatus reports the provider state: provisioning, enabled, reinstated, or disabled.
Sending domainA domain that belongs to one tenant. Status is pending, provisioning, pending_dns, verified, failed, or revoked.

Every route is environment scoped and needs the x-deployments-environment header. Every mutation needs an Idempotency-Key header.

Verify a domain

Registering a domain returns the DNS records to publish in dnsRecords: an ownership TXT record, CNAME records for DKIM, and records for the custom MAIL FROM domain. Send-only domains never get an inbound MX record. Publish the records, then refresh the domain. It stays pending_dns until the records resolve and becomes verified when they do.

Sends require a verified domain, so revoking a domain stops sends from it.

Send a message

A send names a from mailbox on a verified domain of the same tenant, at least one to recipient, a subject, and a text body, an html body, or both.

RuleLimit
RecipientsAt most 50 across to, cc, and bcc
BodyAt least one non-empty body. text and html together at most 1 MiB of UTF-8.
SubjectAt most 998 characters, no control characters
MailboxesOne address each, display names allowed, no header injection

The API answers 202 with status: "accepted" and a providerMessageId once the provider accepts the message. Accepted does not mean delivered. Delivery to the recipient's mail server happens later, and this route does not report it.

StatusCodeMeaning
202The provider accepted the message
409email_domain_not_verifiedThe from domain is not verified in this tenant
409email_tenant_pausedThe tenant is paused
422email_send_rejectedThe provider rejected the message
429email_send_throttledThe provider's sending limit was reached
500ambiguous_write_outcomeThe platform cannot tell whether the provider accepted the message
503email_provider_unavailableThe provider is unavailable or misconfigured before the send

Do not resend after an ambiguous outcome

The platform calls the provider once per send and never retries it, because the provider has no idempotency token. After ambiguous_write_outcome, the idempotency key stays claimed, so repeating the request with the same key does not send again. The idempotency record lasts 24 hours. A retry after that, or with a new key, can deliver a duplicate.

Permissions

CapabilityAllows
email:readList and read tenants and domains
email:writeSend messages
email:adminCreate and update tenants, and create, refresh, and revoke domains. Includes email:read and email:write.

A human keeps email:admin only with the organization owner or admin role.

Use it

  1. Create a sending tenant:

    deployments email-tenant create --name "Product notifications"
  2. Register your domain and read the DNS records to publish:

    deployments email-domain create $EMAIL_TENANT_ID --domain mail.example.com
  3. After you publish the records, refresh until the status is verified:

    deployments email-domain refresh $EMAIL_DOMAIN_ID
  4. Send a message. --to takes a JSON array, and --text-file reads the body from a file:

    deployments email send $EMAIL_TENANT_ID --from "Example <notify@mail.example.com>" --to '["user@example.com"]' --subject "Your report is ready" --text-file body.txt

The same send through the SDK:

import { createClient, createConfig, sendEmail } from "@deployments-ai/sdk";

const client = createClient(
  createConfig({
    baseUrl: "https://api.example.com",
    headers: { authorization: `Bearer ${process.env.DEPLOYMENTS_API_KEY}` },
  }),
);

const { data, error } = await sendEmail({
  client,
  path: { tenantId: "etn_123" },
  headers: {
    "idempotency-key": crypto.randomUUID(),
    "x-deployments-environment": "env_123",
  },
  body: {
    from: "Example <notify@mail.example.com>",
    to: ["user@example.com"],
    subject: "Your report is ready",
    text: "Your weekly report is ready to view.",
  },
});

Reuse the same idempotency key for every attempt to send the same message.

In the management console, the Sending tenants tab under Connect › Email creates, pauses, and resumes tenants, adds and refreshes domains, and sends a message from a verified domain.

Reference

On this page