feat(backend): add transactional email API

.changeset/quiet-mails-arrive.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add experimental methods for sending and retrieving internal transactional emails, including Clerk suppression state and reasons.

packages/backend/src/api/__tests__/EmailApi.test.ts

@@ -25,6 +25,7 @@ describe('EmailApi', () => {
  status: 'queued',
  data: null,
  delivered_by_clerk: true,
+ suppression_reason: null,
  };
 
  it('sends a transactional email and snake_cases the body', async () => {
@@ -59,6 +60,107 @@ describe('EmailApi', () => {
  expect(response.deliveredByClerk).toBe(true);
  });
 
+ it('sends an idempotency key without adding it to the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Idempotency-Key')).toBe('campaign-123-contact-456');
+ const body = await request.json();
+ expect(body).not.toHaveProperty('idempotency_key');
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ await apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ { idempotencyKey: 'campaign-123-contact-456' },
+ );
+ });
+
+ it.each([
+ ['an empty value', ''],
+ ['a null value', null],
+ ['a numeric value', 123],
+ ['unsupported characters', 'campaign:123'],
+ ['more than 255 characters', 'a'.repeat(256)],
+ ])('rejects idempotency keys with %s before sending a request', async (_, idempotencyKey) => {
+ let requestCount = 0;
+ server.use(
+ http.post('https://api.clerk.test/v1/email', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(
+ apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ // Exercise the runtime boundary that exists for JavaScript consumers.
+ { idempotencyKey: idempotencyKey as string },
+ ),
+ ).rejects.toThrow('Idempotency key must contain only ASCII letters, digits, underscores, and hyphens');
+ expect(requestCount).toBe(0);
+ });
+
+ it('gets the stored provider-acceptance status', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() => HttpResponse.json({ ...mockEmail, status: 'accepted' })),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.id).toBe('ema_123');
+ expect(response.status).toBe('accepted');
+ });
+
+ it('surfaces transactional suppression state', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() =>
+ HttpResponse.json({
+ ...mockEmail,
+ status: 'suppressed',
+ delivered_by_clerk: false,
+ suppression_reason: 'application_communication_lock',
+ }),
+ ),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.status).toBe('suppressed');
+ expect(response.deliveredByClerk).toBe(false);
+ expect(response.suppressionReason).toBe('application_communication_lock');
+ });
+
+ it('rejects an empty email ID before sending a request', async () => {
+ let requestCount = 0;
+ server.use(
+ http.get('https://api.clerk.test/v1/email/:emailId', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(apiClient.emails.get('')).rejects.toThrow('A valid resource ID is required.');
+ expect(requestCount).toBe(0);
+ });
+
  it('sends a transactional email with a text body', async () => {
  server.use(
  http.post(

packages/backend/src/api/endpoints/EmailApi.ts

@@ -2,21 +2,14 @@ import type { Email } from '../resources/Email';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/email';
+const idempotencyKeyPattern = /^[a-zA-Z0-9_-]{1,255}$/;
 
 /**
- * A subset of mailbox object as specified in RFC 5322 §3.4. Specifically, a
- * `name-addr` with an optional `display-name` and a required `addr-spec`.
+ * A mailbox address as specified by RFC 5322's `addr-spec`.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc5322#section-3.4}
  */
 type Mailbox = {
- /**
- * (Optional) Display name for the mailbox. Currently accepted by the API but
- * not yet rendered server-side, so it has no effect on the delivered email
- * for now.
- */
- name?: string;
-
  /**
  * The `addr-spec` of the mailbox, i.e. the email address itself.
  */
@@ -27,7 +20,7 @@ type Mailbox = {
  * The recipient of the email. Provide exactly one of the two mutually exclusive
  * forms:
  *
- * - a literal mailbox: an `address` (plus an optional `name`), or
+ * - a literal mailbox: an `address`, or
  * - a `userId`: the ID of a Clerk user whose primary email address Clerk
  * resolves server-side, from the instance the secret key belongs to.
  */
@@ -37,11 +30,6 @@ type EmailRecipient =
  * The `addr-spec` of the recipient mailbox, i.e. the email address itself.
  */
  address: string;
- /**
- * (Optional) Display name for the recipient mailbox. Currently accepted
- * by the API but not yet rendered server-side.
- */
- name?: string;
  userId?: never;
  }
  | {
@@ -52,13 +40,13 @@ type EmailRecipient =
  */
  userId: string;
  address?: never;
- name?: never;
  };
 
 /**
  * The body of the email. At least one of `html` and `text` must be provided; if
- * both are provided, the `html` version takes precedence. Encoded as a union so
- * that omitting both is a compile-time error rather than a server-side one.
+ * both are provided, the `html` version takes precedence. Their combined UTF-8
+ * encoding is limited to 50,000 bytes. Encoded as a union so that omitting both
+ * is a compile-time error rather than a server-side one.
  */
 type EmailContent =
  | {
@@ -87,38 +75,81 @@ type EmailContent =
 export type CreateEmailParams = {
  /**
  * The recipient of the email. Currently only a single recipient is supported.
- * Provide either an `address` (with an optional `name`) or the `userId` of a
+ * Provide either an `address` or the `userId` of a
  * Clerk user; the two forms are mutually exclusive.
  */
  to: EmailRecipient;
 
  /**
- * The sender of the email. See {@link Mailbox} for the accepted format. Note
- * that the API does not yet render the `name` field of the `from` mailbox.
+ * The sender of the email. Its domain must exactly match the instance's
+ * verified production sending domain.
  */
  from: Mailbox;
 
  /**
- * (Optional) The mailbox to include in the `reply-to` header of the email.
+ * (Optional) The mailbox to include in the `reply-to` header. Its domain must
+ * exactly match the same verified production domain as `from`.
  */
  replyTo?: Mailbox;
 
+ /** Maximum 998 characters. */
  subject: string;
 } & EmailContent;
 
+export type CreateEmailOptions = {
+ /**
+ * Deduplicates retries of the same logical send. Reuse a key only when the
+ * recipient and content are identical; use one stable key per recipient when
+ * fanning out a batch. Clerk durably returns the original email for the same
+ * key and request, and returns a conflict if the key is reused with different
+ * parameters. Without a key, each call is a distinct send and the SDK does
+ * not retry an ambiguous POST. Keys may contain only ASCII letters, digits,
+ * underscores, and hyphens, up to 255 characters.
+ */
+ idempotencyKey?: string;
+};
+
 export class EmailApi extends AbstractAPI {
  /**
  * @experimental This method calls an internal, not-yet-public endpoint and is
  * subject to change. It is advised to [pin](https://clerk.com/docs/pinning)
  * the SDK version to avoid breaking changes.
  *
  * Sends a transactional email.
+ *
+ * @param params - The recipient, sender, subject, and content of the email.
+ * @param options - Optional request settings, including an idempotency key.
+ * @returns The stored email and its current send status.
+ * @throws If the idempotency key does not match the supported format.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.create(
+ * {
+ * to: { address: 'customer@example.com' },
+ * from: { address: 'support@example.com' },
+ * subject: 'Your receipt',
+ * html: '<p>Thanks for your order.</p>',
+ * },
+ * { idempotencyKey: 'order_123_receipt' },
+ * );
+ * ```
  */
- public async create(params: CreateEmailParams) {
+ public async create(params: CreateEmailParams, options: CreateEmailOptions = {}): Promise<Email> {
+ const { idempotencyKey } = options;
+ if (
+ idempotencyKey !== undefined &&
+ (typeof idempotencyKey !== 'string' || !idempotencyKeyPattern.test(idempotencyKey))
+ ) {
+ throw new Error(
+ 'Idempotency key must contain only ASCII letters, digits, underscores, and hyphens and cannot exceed 255 characters.',
+ );
+ }
+
  return this.request<Email>({
  method: 'POST',
  path: basePath,
  bodyParams: params,
+ ...(idempotencyKey !== undefined ? { headerParams: { 'Idempotency-Key': idempotencyKey } } : {}),
  options: {
  // Snakecase nested keys too, so a `to: { userId }` recipient is sent as
  // `to: { user_id }` on the wire (the default only snakecases top-level
@@ -127,4 +158,24 @@ export class EmailApi extends AbstractAPI {
  },
  });
  }
+
+ /**
+ * Returns Clerk's stored send state for a transactional email. `accepted`
+ * means the provider accepted the request; it does not prove delivery.
+ *
+ * @param emailId - The ID returned when the email was created.
+ * @returns The stored email and its current send status.
+ * @throws If `emailId` is empty.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.get('ema_123');
+ * ```
+ */
+ public async get(emailId: string): Promise<Email> {
+ this.requireId(emailId);
+ return this.request<Email>({
+ method: 'GET',
+ path: `${basePath}/${emailId}`,
+ });
+ }
 }

packages/backend/src/api/resources/Email.ts

@@ -14,6 +14,7 @@ export class Email {
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
  readonly userId?: string | null,
+ readonly suppressionReason?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -30,6 +31,7 @@ export class Email {
  data.data,
  data.delivered_by_clerk,
  data.user_id,
+ data.suppression_reason,
  );
  }
 }

packages/backend/src/api/resources/JSON.ts

@@ -197,6 +197,7 @@ export interface EmailJSON extends ClerkResourceJSON {
  status?: string;
  data?: Record<string, any> | null;
  delivered_by_clerk: boolean;
+ suppression_reason?: string | null;
 }
 
 export interface EmailAddressJSON extends ClerkResourceJSON {

.changeset/quiet-mails-arrive.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add experimental methods for sending and retrieving internal transactional emails, including Clerk suppression state and reasons.

packages/backend/src/api/__tests__/EmailApi.test.ts

@@ -25,6 +25,7 @@ describe('EmailApi', () => {
  status: 'queued',
  data: null,
  delivered_by_clerk: true,
+ suppression_reason: null,
  };
 
  it('sends a transactional email and snake_cases the body', async () => {
@@ -59,6 +60,107 @@ describe('EmailApi', () => {
  expect(response.deliveredByClerk).toBe(true);
  });
 
+ it('sends an idempotency key without adding it to the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Idempotency-Key')).toBe('campaign-123-contact-456');
+ const body = await request.json();
+ expect(body).not.toHaveProperty('idempotency_key');
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ await apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ { idempotencyKey: 'campaign-123-contact-456' },
+ );
+ });
+
+ it.each([
+ ['an empty value', ''],
+ ['a null value', null],
+ ['a numeric value', 123],
+ ['unsupported characters', 'campaign:123'],
+ ['more than 255 characters', 'a'.repeat(256)],
+ ])('rejects idempotency keys with %s before sending a request', async (_, idempotencyKey) => {
+ let requestCount = 0;
+ server.use(
+ http.post('https://api.clerk.test/v1/email', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(
+ apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ // Exercise the runtime boundary that exists for JavaScript consumers.
+ { idempotencyKey: idempotencyKey as string },
+ ),
+ ).rejects.toThrow('Idempotency key must contain only ASCII letters, digits, underscores, and hyphens');
+ expect(requestCount).toBe(0);
+ });
+
+ it('gets the stored provider-acceptance status', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() => HttpResponse.json({ ...mockEmail, status: 'accepted' })),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.id).toBe('ema_123');
+ expect(response.status).toBe('accepted');
+ });
+
+ it('surfaces transactional suppression state', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() =>
+ HttpResponse.json({
+ ...mockEmail,
+ status: 'suppressed',
+ delivered_by_clerk: false,
+ suppression_reason: 'application_communication_lock',
+ }),
+ ),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.status).toBe('suppressed');
+ expect(response.deliveredByClerk).toBe(false);
+ expect(response.suppressionReason).toBe('application_communication_lock');
+ });
+
+ it('rejects an empty email ID before sending a request', async () => {
+ let requestCount = 0;
+ server.use(
+ http.get('https://api.clerk.test/v1/email/:emailId', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(apiClient.emails.get('')).rejects.toThrow('A valid resource ID is required.');
+ expect(requestCount).toBe(0);
+ });
+
  it('sends a transactional email with a text body', async () => {
  server.use(
  http.post(

packages/backend/src/api/endpoints/EmailApi.ts

@@ -2,21 +2,14 @@ import type { Email } from '../resources/Email';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/email';
+const idempotencyKeyPattern = /^[a-zA-Z0-9_-]{1,255}$/;
 
 /**
- * A subset of mailbox object as specified in RFC 5322 §3.4. Specifically, a
- * `name-addr` with an optional `display-name` and a required `addr-spec`.
+ * A mailbox address as specified by RFC 5322's `addr-spec`.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc5322#section-3.4}
  */
 type Mailbox = {
- /**
- * (Optional) Display name for the mailbox. Currently accepted by the API but
- * not yet rendered server-side, so it has no effect on the delivered email
- * for now.
- */
- name?: string;
-
  /**
  * The `addr-spec` of the mailbox, i.e. the email address itself.
  */
@@ -27,7 +20,7 @@ type Mailbox = {
  * The recipient of the email. Provide exactly one of the two mutually exclusive
  * forms:
  *
- * - a literal mailbox: an `address` (plus an optional `name`), or
+ * - a literal mailbox: an `address`, or
  * - a `userId`: the ID of a Clerk user whose primary email address Clerk
  * resolves server-side, from the instance the secret key belongs to.
  */
@@ -37,11 +30,6 @@ type EmailRecipient =
  * The `addr-spec` of the recipient mailbox, i.e. the email address itself.
  */
  address: string;
- /**
- * (Optional) Display name for the recipient mailbox. Currently accepted
- * by the API but not yet rendered server-side.
- */
- name?: string;
  userId?: never;
  }
  | {
@@ -52,13 +40,13 @@ type EmailRecipient =
  */
  userId: string;
  address?: never;
- name?: never;
  };
 
 /**
  * The body of the email. At least one of `html` and `text` must be provided; if
- * both are provided, the `html` version takes precedence. Encoded as a union so
- * that omitting both is a compile-time error rather than a server-side one.
+ * both are provided, the `html` version takes precedence. Their combined UTF-8
+ * encoding is limited to 50,000 bytes. Encoded as a union so that omitting both
+ * is a compile-time error rather than a server-side one.
  */
 type EmailContent =
  | {
@@ -87,38 +75,81 @@ type EmailContent =
 export type CreateEmailParams = {
  /**
  * The recipient of the email. Currently only a single recipient is supported.
- * Provide either an `address` (with an optional `name`) or the `userId` of a
+ * Provide either an `address` or the `userId` of a
  * Clerk user; the two forms are mutually exclusive.
  */
  to: EmailRecipient;
 
  /**
- * The sender of the email. See {@link Mailbox} for the accepted format. Note
- * that the API does not yet render the `name` field of the `from` mailbox.
+ * The sender of the email. Its domain must exactly match the instance's
+ * verified production sending domain.
  */
  from: Mailbox;
 
  /**
- * (Optional) The mailbox to include in the `reply-to` header of the email.
+ * (Optional) The mailbox to include in the `reply-to` header. Its domain must
+ * exactly match the same verified production domain as `from`.
  */
  replyTo?: Mailbox;
 
+ /** Maximum 998 characters. */
  subject: string;
 } & EmailContent;
 
+export type CreateEmailOptions = {
+ /**
+ * Deduplicates retries of the same logical send. Reuse a key only when the
+ * recipient and content are identical; use one stable key per recipient when
+ * fanning out a batch. Clerk durably returns the original email for the same
+ * key and request, and returns a conflict if the key is reused with different
+ * parameters. Without a key, each call is a distinct send and the SDK does
+ * not retry an ambiguous POST. Keys may contain only ASCII letters, digits,
+ * underscores, and hyphens, up to 255 characters.
+ */
+ idempotencyKey?: string;
+};
+
 export class EmailApi extends AbstractAPI {
  /**
  * @experimental This method calls an internal, not-yet-public endpoint and is
  * subject to change. It is advised to [pin](https://clerk.com/docs/pinning)
  * the SDK version to avoid breaking changes.
  *
  * Sends a transactional email.
+ *
+ * @param params - The recipient, sender, subject, and content of the email.
+ * @param options - Optional request settings, including an idempotency key.
+ * @returns The stored email and its current send status.
+ * @throws If the idempotency key does not match the supported format.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.create(
+ * {
+ * to: { address: 'customer@example.com' },
+ * from: { address: 'support@example.com' },
+ * subject: 'Your receipt',
+ * html: '<p>Thanks for your order.</p>',
+ * },
+ * { idempotencyKey: 'order_123_receipt' },
+ * );
+ * ```
  */
- public async create(params: CreateEmailParams) {
+ public async create(params: CreateEmailParams, options: CreateEmailOptions = {}): Promise<Email> {
+ const { idempotencyKey } = options;
+ if (
+ idempotencyKey !== undefined &&
+ (typeof idempotencyKey !== 'string' || !idempotencyKeyPattern.test(idempotencyKey))
+ ) {
+ throw new Error(
+ 'Idempotency key must contain only ASCII letters, digits, underscores, and hyphens and cannot exceed 255 characters.',
+ );
+ }
+
  return this.request<Email>({
  method: 'POST',
  path: basePath,
  bodyParams: params,
+ ...(idempotencyKey !== undefined ? { headerParams: { 'Idempotency-Key': idempotencyKey } } : {}),
  options: {
  // Snakecase nested keys too, so a `to: { userId }` recipient is sent as
  // `to: { user_id }` on the wire (the default only snakecases top-level
@@ -127,4 +158,24 @@ export class EmailApi extends AbstractAPI {
  },
  });
  }
+
+ /**
+ * Returns Clerk's stored send state for a transactional email. `accepted`
+ * means the provider accepted the request; it does not prove delivery.
+ *
+ * @param emailId - The ID returned when the email was created.
+ * @returns The stored email and its current send status.
+ * @throws If `emailId` is empty.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.get('ema_123');
+ * ```
+ */
+ public async get(emailId: string): Promise<Email> {
+ this.requireId(emailId);
+ return this.request<Email>({
+ method: 'GET',
+ path: `${basePath}/${emailId}`,
+ });
+ }
 }

packages/backend/src/api/resources/Email.ts

@@ -14,6 +14,7 @@ export class Email {
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
  readonly userId?: string | null,
+ readonly suppressionReason?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -30,6 +31,7 @@ export class Email {
  data.data,
  data.delivered_by_clerk,
  data.user_id,
+ data.suppression_reason,
  );
  }
 }

packages/backend/src/api/resources/JSON.ts

@@ -197,6 +197,7 @@ export interface EmailJSON extends ClerkResourceJSON {
  status?: string;
  data?: Record<string, any> | null;
  delivered_by_clerk: boolean;
+ suppression_reason?: string | null;
 }
 
 export interface EmailAddressJSON extends ClerkResourceJSON {

.changeset/quiet-mails-arrive.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add experimental methods for sending and retrieving internal transactional emails, including Clerk suppression state and reasons.

packages/backend/src/api/__tests__/EmailApi.test.ts

@@ -25,6 +25,7 @@ describe('EmailApi', () => {
  status: 'queued',
  data: null,
  delivered_by_clerk: true,
+ suppression_reason: null,
  };
 
  it('sends a transactional email and snake_cases the body', async () => {
@@ -59,6 +60,107 @@ describe('EmailApi', () => {
  expect(response.deliveredByClerk).toBe(true);
  });
 
+ it('sends an idempotency key without adding it to the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Idempotency-Key')).toBe('campaign-123-contact-456');
+ const body = await request.json();
+ expect(body).not.toHaveProperty('idempotency_key');
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ await apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ { idempotencyKey: 'campaign-123-contact-456' },
+ );
+ });
+
+ it.each([
+ ['an empty value', ''],
+ ['a null value', null],
+ ['a numeric value', 123],
+ ['unsupported characters', 'campaign:123'],
+ ['more than 255 characters', 'a'.repeat(256)],
+ ])('rejects idempotency keys with %s before sending a request', async (_, idempotencyKey) => {
+ let requestCount = 0;
+ server.use(
+ http.post('https://api.clerk.test/v1/email', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(
+ apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ // Exercise the runtime boundary that exists for JavaScript consumers.
+ { idempotencyKey: idempotencyKey as string },
+ ),
+ ).rejects.toThrow('Idempotency key must contain only ASCII letters, digits, underscores, and hyphens');
+ expect(requestCount).toBe(0);
+ });
+
+ it('gets the stored provider-acceptance status', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() => HttpResponse.json({ ...mockEmail, status: 'accepted' })),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.id).toBe('ema_123');
+ expect(response.status).toBe('accepted');
+ });
+
+ it('surfaces transactional suppression state', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() =>
+ HttpResponse.json({
+ ...mockEmail,
+ status: 'suppressed',
+ delivered_by_clerk: false,
+ suppression_reason: 'application_communication_lock',
+ }),
+ ),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.status).toBe('suppressed');
+ expect(response.deliveredByClerk).toBe(false);
+ expect(response.suppressionReason).toBe('application_communication_lock');
+ });
+
+ it('rejects an empty email ID before sending a request', async () => {
+ let requestCount = 0;
+ server.use(
+ http.get('https://api.clerk.test/v1/email/:emailId', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(apiClient.emails.get('')).rejects.toThrow('A valid resource ID is required.');
+ expect(requestCount).toBe(0);
+ });
+
  it('sends a transactional email with a text body', async () => {
  server.use(
  http.post(

packages/backend/src/api/endpoints/EmailApi.ts

@@ -2,21 +2,14 @@ import type { Email } from '../resources/Email';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/email';
+const idempotencyKeyPattern = /^[a-zA-Z0-9_-]{1,255}$/;
 
 /**
- * A subset of mailbox object as specified in RFC 5322 §3.4. Specifically, a
- * `name-addr` with an optional `display-name` and a required `addr-spec`.
+ * A mailbox address as specified by RFC 5322's `addr-spec`.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc5322#section-3.4}
  */
 type Mailbox = {
- /**
- * (Optional) Display name for the mailbox. Currently accepted by the API but
- * not yet rendered server-side, so it has no effect on the delivered email
- * for now.
- */
- name?: string;
-
  /**
  * The `addr-spec` of the mailbox, i.e. the email address itself.
  */
@@ -27,7 +20,7 @@ type Mailbox = {
  * The recipient of the email. Provide exactly one of the two mutually exclusive
  * forms:
  *
- * - a literal mailbox: an `address` (plus an optional `name`), or
+ * - a literal mailbox: an `address`, or
  * - a `userId`: the ID of a Clerk user whose primary email address Clerk
  * resolves server-side, from the instance the secret key belongs to.
  */
@@ -37,11 +30,6 @@ type EmailRecipient =
  * The `addr-spec` of the recipient mailbox, i.e. the email address itself.
  */
  address: string;
- /**
- * (Optional) Display name for the recipient mailbox. Currently accepted
- * by the API but not yet rendered server-side.
- */
- name?: string;
  userId?: never;
  }
  | {
@@ -52,13 +40,13 @@ type EmailRecipient =
  */
  userId: string;
  address?: never;
- name?: never;
  };
 
 /**
  * The body of the email. At least one of `html` and `text` must be provided; if
- * both are provided, the `html` version takes precedence. Encoded as a union so
- * that omitting both is a compile-time error rather than a server-side one.
+ * both are provided, the `html` version takes precedence. Their combined UTF-8
+ * encoding is limited to 50,000 bytes. Encoded as a union so that omitting both
+ * is a compile-time error rather than a server-side one.
  */
 type EmailContent =
  | {
@@ -87,38 +75,81 @@ type EmailContent =
 export type CreateEmailParams = {
  /**
  * The recipient of the email. Currently only a single recipient is supported.
- * Provide either an `address` (with an optional `name`) or the `userId` of a
+ * Provide either an `address` or the `userId` of a
  * Clerk user; the two forms are mutually exclusive.
  */
  to: EmailRecipient;
 
  /**
- * The sender of the email. See {@link Mailbox} for the accepted format. Note
- * that the API does not yet render the `name` field of the `from` mailbox.
+ * The sender of the email. Its domain must exactly match the instance's
+ * verified production sending domain.
  */
  from: Mailbox;
 
  /**
- * (Optional) The mailbox to include in the `reply-to` header of the email.
+ * (Optional) The mailbox to include in the `reply-to` header. Its domain must
+ * exactly match the same verified production domain as `from`.
  */
  replyTo?: Mailbox;
 
+ /** Maximum 998 characters. */
  subject: string;
 } & EmailContent;
 
+export type CreateEmailOptions = {
+ /**
+ * Deduplicates retries of the same logical send. Reuse a key only when the
+ * recipient and content are identical; use one stable key per recipient when
+ * fanning out a batch. Clerk durably returns the original email for the same
+ * key and request, and returns a conflict if the key is reused with different
+ * parameters. Without a key, each call is a distinct send and the SDK does
+ * not retry an ambiguous POST. Keys may contain only ASCII letters, digits,
+ * underscores, and hyphens, up to 255 characters.
+ */
+ idempotencyKey?: string;
+};
+
 export class EmailApi extends AbstractAPI {
  /**
  * @experimental This method calls an internal, not-yet-public endpoint and is
  * subject to change. It is advised to [pin](https://clerk.com/docs/pinning)
  * the SDK version to avoid breaking changes.
  *
  * Sends a transactional email.
+ *
+ * @param params - The recipient, sender, subject, and content of the email.
+ * @param options - Optional request settings, including an idempotency key.
+ * @returns The stored email and its current send status.
+ * @throws If the idempotency key does not match the supported format.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.create(
+ * {
+ * to: { address: 'customer@example.com' },
+ * from: { address: 'support@example.com' },
+ * subject: 'Your receipt',
+ * html: '<p>Thanks for your order.</p>',
+ * },
+ * { idempotencyKey: 'order_123_receipt' },
+ * );
+ * ```
  */
- public async create(params: CreateEmailParams) {
+ public async create(params: CreateEmailParams, options: CreateEmailOptions = {}): Promise<Email> {
+ const { idempotencyKey } = options;
+ if (
+ idempotencyKey !== undefined &&
+ (typeof idempotencyKey !== 'string' || !idempotencyKeyPattern.test(idempotencyKey))
+ ) {
+ throw new Error(
+ 'Idempotency key must contain only ASCII letters, digits, underscores, and hyphens and cannot exceed 255 characters.',
+ );
+ }
+
  return this.request<Email>({
  method: 'POST',
  path: basePath,
  bodyParams: params,
+ ...(idempotencyKey !== undefined ? { headerParams: { 'Idempotency-Key': idempotencyKey } } : {}),
  options: {
  // Snakecase nested keys too, so a `to: { userId }` recipient is sent as
  // `to: { user_id }` on the wire (the default only snakecases top-level
@@ -127,4 +158,24 @@ export class EmailApi extends AbstractAPI {
  },
  });
  }
+
+ /**
+ * Returns Clerk's stored send state for a transactional email. `accepted`
+ * means the provider accepted the request; it does not prove delivery.
+ *
+ * @param emailId - The ID returned when the email was created.
+ * @returns The stored email and its current send status.
+ * @throws If `emailId` is empty.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.get('ema_123');
+ * ```
+ */
+ public async get(emailId: string): Promise<Email> {
+ this.requireId(emailId);
+ return this.request<Email>({
+ method: 'GET',
+ path: `${basePath}/${emailId}`,
+ });
+ }
 }

packages/backend/src/api/resources/Email.ts

@@ -14,6 +14,7 @@ export class Email {
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
  readonly userId?: string | null,
+ readonly suppressionReason?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -30,6 +31,7 @@ export class Email {
  data.data,
  data.delivered_by_clerk,
  data.user_id,
+ data.suppression_reason,
  );
  }
 }

packages/backend/src/api/resources/JSON.ts

@@ -197,6 +197,7 @@ export interface EmailJSON extends ClerkResourceJSON {
  status?: string;
  data?: Record<string, any> | null;
  delivered_by_clerk: boolean;
+ suppression_reason?: string | null;
 }
 
 export interface EmailAddressJSON extends ClerkResourceJSON {

.changeset/quiet-mails-arrive.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add experimental methods for sending and retrieving internal transactional emails, including Clerk suppression state and reasons.

packages/backend/src/api/__tests__/EmailApi.test.ts

@@ -25,6 +25,7 @@ describe('EmailApi', () => {
  status: 'queued',
  data: null,
  delivered_by_clerk: true,
+ suppression_reason: null,
  };
 
  it('sends a transactional email and snake_cases the body', async () => {
@@ -59,6 +60,107 @@ describe('EmailApi', () => {
  expect(response.deliveredByClerk).toBe(true);
  });
 
+ it('sends an idempotency key without adding it to the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Idempotency-Key')).toBe('campaign-123-contact-456');
+ const body = await request.json();
+ expect(body).not.toHaveProperty('idempotency_key');
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ await apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ { idempotencyKey: 'campaign-123-contact-456' },
+ );
+ });
+
+ it.each([
+ ['an empty value', ''],
+ ['a null value', null],
+ ['a numeric value', 123],
+ ['unsupported characters', 'campaign:123'],
+ ['more than 255 characters', 'a'.repeat(256)],
+ ])('rejects idempotency keys with %s before sending a request', async (_, idempotencyKey) => {
+ let requestCount = 0;
+ server.use(
+ http.post('https://api.clerk.test/v1/email', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(
+ apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ // Exercise the runtime boundary that exists for JavaScript consumers.
+ { idempotencyKey: idempotencyKey as string },
+ ),
+ ).rejects.toThrow('Idempotency key must contain only ASCII letters, digits, underscores, and hyphens');
+ expect(requestCount).toBe(0);
+ });
+
+ it('gets the stored provider-acceptance status', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() => HttpResponse.json({ ...mockEmail, status: 'accepted' })),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.id).toBe('ema_123');
+ expect(response.status).toBe('accepted');
+ });
+
+ it('surfaces transactional suppression state', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() =>
+ HttpResponse.json({
+ ...mockEmail,
+ status: 'suppressed',
+ delivered_by_clerk: false,
+ suppression_reason: 'application_communication_lock',
+ }),
+ ),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.status).toBe('suppressed');
+ expect(response.deliveredByClerk).toBe(false);
+ expect(response.suppressionReason).toBe('application_communication_lock');
+ });
+
+ it('rejects an empty email ID before sending a request', async () => {
+ let requestCount = 0;
+ server.use(
+ http.get('https://api.clerk.test/v1/email/:emailId', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(apiClient.emails.get('')).rejects.toThrow('A valid resource ID is required.');
+ expect(requestCount).toBe(0);
+ });
+
  it('sends a transactional email with a text body', async () => {
  server.use(
  http.post(

packages/backend/src/api/endpoints/EmailApi.ts

@@ -2,21 +2,14 @@ import type { Email } from '../resources/Email';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/email';
+const idempotencyKeyPattern = /^[a-zA-Z0-9_-]{1,255}$/;
 
 /**
- * A subset of mailbox object as specified in RFC 5322 §3.4. Specifically, a
- * `name-addr` with an optional `display-name` and a required `addr-spec`.
+ * A mailbox address as specified by RFC 5322's `addr-spec`.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc5322#section-3.4}
  */
 type Mailbox = {
- /**
- * (Optional) Display name for the mailbox. Currently accepted by the API but
- * not yet rendered server-side, so it has no effect on the delivered email
- * for now.
- */
- name?: string;
-
  /**
  * The `addr-spec` of the mailbox, i.e. the email address itself.
  */
@@ -27,7 +20,7 @@ type Mailbox = {
  * The recipient of the email. Provide exactly one of the two mutually exclusive
  * forms:
  *
- * - a literal mailbox: an `address` (plus an optional `name`), or
+ * - a literal mailbox: an `address`, or
  * - a `userId`: the ID of a Clerk user whose primary email address Clerk
  * resolves server-side, from the instance the secret key belongs to.
  */
@@ -37,11 +30,6 @@ type EmailRecipient =
  * The `addr-spec` of the recipient mailbox, i.e. the email address itself.
  */
  address: string;
- /**
- * (Optional) Display name for the recipient mailbox. Currently accepted
- * by the API but not yet rendered server-side.
- */
- name?: string;
  userId?: never;
  }
  | {
@@ -52,13 +40,13 @@ type EmailRecipient =
  */
  userId: string;
  address?: never;
- name?: never;
  };
 
 /**
  * The body of the email. At least one of `html` and `text` must be provided; if
- * both are provided, the `html` version takes precedence. Encoded as a union so
- * that omitting both is a compile-time error rather than a server-side one.
+ * both are provided, the `html` version takes precedence. Their combined UTF-8
+ * encoding is limited to 50,000 bytes. Encoded as a union so that omitting both
+ * is a compile-time error rather than a server-side one.
  */
 type EmailContent =
  | {
@@ -87,38 +75,81 @@ type EmailContent =
 export type CreateEmailParams = {
  /**
  * The recipient of the email. Currently only a single recipient is supported.
- * Provide either an `address` (with an optional `name`) or the `userId` of a
+ * Provide either an `address` or the `userId` of a
  * Clerk user; the two forms are mutually exclusive.
  */
  to: EmailRecipient;
 
  /**
- * The sender of the email. See {@link Mailbox} for the accepted format. Note
- * that the API does not yet render the `name` field of the `from` mailbox.
+ * The sender of the email. Its domain must exactly match the instance's
+ * verified production sending domain.
  */
  from: Mailbox;
 
  /**
- * (Optional) The mailbox to include in the `reply-to` header of the email.
+ * (Optional) The mailbox to include in the `reply-to` header. Its domain must
+ * exactly match the same verified production domain as `from`.
  */
  replyTo?: Mailbox;
 
+ /** Maximum 998 characters. */
  subject: string;
 } & EmailContent;
 
+export type CreateEmailOptions = {
+ /**
+ * Deduplicates retries of the same logical send. Reuse a key only when the
+ * recipient and content are identical; use one stable key per recipient when
+ * fanning out a batch. Clerk durably returns the original email for the same
+ * key and request, and returns a conflict if the key is reused with different
+ * parameters. Without a key, each call is a distinct send and the SDK does
+ * not retry an ambiguous POST. Keys may contain only ASCII letters, digits,
+ * underscores, and hyphens, up to 255 characters.
+ */
+ idempotencyKey?: string;
+};
+
 export class EmailApi extends AbstractAPI {
  /**
  * @experimental This method calls an internal, not-yet-public endpoint and is
  * subject to change. It is advised to [pin](https://clerk.com/docs/pinning)
  * the SDK version to avoid breaking changes.
  *
  * Sends a transactional email.
+ *
+ * @param params - The recipient, sender, subject, and content of the email.
+ * @param options - Optional request settings, including an idempotency key.
+ * @returns The stored email and its current send status.
+ * @throws If the idempotency key does not match the supported format.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.create(
+ * {
+ * to: { address: 'customer@example.com' },
+ * from: { address: 'support@example.com' },
+ * subject: 'Your receipt',
+ * html: '<p>Thanks for your order.</p>',
+ * },
+ * { idempotencyKey: 'order_123_receipt' },
+ * );
+ * ```
  */
- public async create(params: CreateEmailParams) {
+ public async create(params: CreateEmailParams, options: CreateEmailOptions = {}): Promise<Email> {
+ const { idempotencyKey } = options;
+ if (
+ idempotencyKey !== undefined &&
+ (typeof idempotencyKey !== 'string' || !idempotencyKeyPattern.test(idempotencyKey))
+ ) {
+ throw new Error(
+ 'Idempotency key must contain only ASCII letters, digits, underscores, and hyphens and cannot exceed 255 characters.',
+ );
+ }
+
  return this.request<Email>({
  method: 'POST',
  path: basePath,
  bodyParams: params,
+ ...(idempotencyKey !== undefined ? { headerParams: { 'Idempotency-Key': idempotencyKey } } : {}),
  options: {
  // Snakecase nested keys too, so a `to: { userId }` recipient is sent as
  // `to: { user_id }` on the wire (the default only snakecases top-level
@@ -127,4 +158,24 @@ export class EmailApi extends AbstractAPI {
  },
  });
  }
+
+ /**
+ * Returns Clerk's stored send state for a transactional email. `accepted`
+ * means the provider accepted the request; it does not prove delivery.
+ *
+ * @param emailId - The ID returned when the email was created.
+ * @returns The stored email and its current send status.
+ * @throws If `emailId` is empty.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.get('ema_123');
+ * ```
+ */
+ public async get(emailId: string): Promise<Email> {
+ this.requireId(emailId);
+ return this.request<Email>({
+ method: 'GET',
+ path: `${basePath}/${emailId}`,
+ });
+ }
 }

packages/backend/src/api/resources/Email.ts

@@ -14,6 +14,7 @@ export class Email {
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
  readonly userId?: string | null,
+ readonly suppressionReason?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -30,6 +31,7 @@ export class Email {
  data.data,
  data.delivered_by_clerk,
  data.user_id,
+ data.suppression_reason,
  );
  }
 }

packages/backend/src/api/resources/JSON.ts

@@ -197,6 +197,7 @@ export interface EmailJSON extends ClerkResourceJSON {
  status?: string;
  data?: Record<string, any> | null;
  delivered_by_clerk: boolean;
+ suppression_reason?: string | null;
 }
 
 export interface EmailAddressJSON extends ClerkResourceJSON {

.changeset/quiet-mails-arrive.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add experimental methods for sending and retrieving internal transactional emails, including Clerk suppression state and reasons.

packages/backend/src/api/__tests__/EmailApi.test.ts

@@ -25,6 +25,7 @@ describe('EmailApi', () => {
  status: 'queued',
  data: null,
  delivered_by_clerk: true,
+ suppression_reason: null,
  };
 
  it('sends a transactional email and snake_cases the body', async () => {
@@ -59,6 +60,107 @@ describe('EmailApi', () => {
  expect(response.deliveredByClerk).toBe(true);
  });
 
+ it('sends an idempotency key without adding it to the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Idempotency-Key')).toBe('campaign-123-contact-456');
+ const body = await request.json();
+ expect(body).not.toHaveProperty('idempotency_key');
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ await apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ { idempotencyKey: 'campaign-123-contact-456' },
+ );
+ });
+
+ it.each([
+ ['an empty value', ''],
+ ['a null value', null],
+ ['a numeric value', 123],
+ ['unsupported characters', 'campaign:123'],
+ ['more than 255 characters', 'a'.repeat(256)],
+ ])('rejects idempotency keys with %s before sending a request', async (_, idempotencyKey) => {
+ let requestCount = 0;
+ server.use(
+ http.post('https://api.clerk.test/v1/email', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(
+ apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ // Exercise the runtime boundary that exists for JavaScript consumers.
+ { idempotencyKey: idempotencyKey as string },
+ ),
+ ).rejects.toThrow('Idempotency key must contain only ASCII letters, digits, underscores, and hyphens');
+ expect(requestCount).toBe(0);
+ });
+
+ it('gets the stored provider-acceptance status', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() => HttpResponse.json({ ...mockEmail, status: 'accepted' })),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.id).toBe('ema_123');
+ expect(response.status).toBe('accepted');
+ });
+
+ it('surfaces transactional suppression state', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() =>
+ HttpResponse.json({
+ ...mockEmail,
+ status: 'suppressed',
+ delivered_by_clerk: false,
+ suppression_reason: 'application_communication_lock',
+ }),
+ ),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.status).toBe('suppressed');
+ expect(response.deliveredByClerk).toBe(false);
+ expect(response.suppressionReason).toBe('application_communication_lock');
+ });
+
+ it('rejects an empty email ID before sending a request', async () => {
+ let requestCount = 0;
+ server.use(
+ http.get('https://api.clerk.test/v1/email/:emailId', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(apiClient.emails.get('')).rejects.toThrow('A valid resource ID is required.');
+ expect(requestCount).toBe(0);
+ });
+
  it('sends a transactional email with a text body', async () => {
  server.use(
  http.post(

packages/backend/src/api/endpoints/EmailApi.ts

@@ -2,21 +2,14 @@ import type { Email } from '../resources/Email';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/email';
+const idempotencyKeyPattern = /^[a-zA-Z0-9_-]{1,255}$/;
 
 /**
- * A subset of mailbox object as specified in RFC 5322 §3.4. Specifically, a
- * `name-addr` with an optional `display-name` and a required `addr-spec`.
+ * A mailbox address as specified by RFC 5322's `addr-spec`.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc5322#section-3.4}
  */
 type Mailbox = {
- /**
- * (Optional) Display name for the mailbox. Currently accepted by the API but
- * not yet rendered server-side, so it has no effect on the delivered email
- * for now.
- */
- name?: string;
-
  /**
  * The `addr-spec` of the mailbox, i.e. the email address itself.
  */
@@ -27,7 +20,7 @@ type Mailbox = {
  * The recipient of the email. Provide exactly one of the two mutually exclusive
  * forms:
  *
- * - a literal mailbox: an `address` (plus an optional `name`), or
+ * - a literal mailbox: an `address`, or
  * - a `userId`: the ID of a Clerk user whose primary email address Clerk
  * resolves server-side, from the instance the secret key belongs to.
  */
@@ -37,11 +30,6 @@ type EmailRecipient =
  * The `addr-spec` of the recipient mailbox, i.e. the email address itself.
  */
  address: string;
- /**
- * (Optional) Display name for the recipient mailbox. Currently accepted
- * by the API but not yet rendered server-side.
- */
- name?: string;
  userId?: never;
  }
  | {
@@ -52,13 +40,13 @@ type EmailRecipient =
  */
  userId: string;
  address?: never;
- name?: never;
  };
 
 /**
  * The body of the email. At least one of `html` and `text` must be provided; if
- * both are provided, the `html` version takes precedence. Encoded as a union so
- * that omitting both is a compile-time error rather than a server-side one.
+ * both are provided, the `html` version takes precedence. Their combined UTF-8
+ * encoding is limited to 50,000 bytes. Encoded as a union so that omitting both
+ * is a compile-time error rather than a server-side one.
  */
 type EmailContent =
  | {
@@ -87,38 +75,81 @@ type EmailContent =
 export type CreateEmailParams = {
  /**
  * The recipient of the email. Currently only a single recipient is supported.
- * Provide either an `address` (with an optional `name`) or the `userId` of a
+ * Provide either an `address` or the `userId` of a
  * Clerk user; the two forms are mutually exclusive.
  */
  to: EmailRecipient;
 
  /**
- * The sender of the email. See {@link Mailbox} for the accepted format. Note
- * that the API does not yet render the `name` field of the `from` mailbox.
+ * The sender of the email. Its domain must exactly match the instance's
+ * verified production sending domain.
  */
  from: Mailbox;
 
  /**
- * (Optional) The mailbox to include in the `reply-to` header of the email.
+ * (Optional) The mailbox to include in the `reply-to` header. Its domain must
+ * exactly match the same verified production domain as `from`.
  */
  replyTo?: Mailbox;
 
+ /** Maximum 998 characters. */
  subject: string;
 } & EmailContent;
 
+export type CreateEmailOptions = {
+ /**
+ * Deduplicates retries of the same logical send. Reuse a key only when the
+ * recipient and content are identical; use one stable key per recipient when
+ * fanning out a batch. Clerk durably returns the original email for the same
+ * key and request, and returns a conflict if the key is reused with different
+ * parameters. Without a key, each call is a distinct send and the SDK does
+ * not retry an ambiguous POST. Keys may contain only ASCII letters, digits,
+ * underscores, and hyphens, up to 255 characters.
+ */
+ idempotencyKey?: string;
+};
+
 export class EmailApi extends AbstractAPI {
  /**
  * @experimental This method calls an internal, not-yet-public endpoint and is
  * subject to change. It is advised to [pin](https://clerk.com/docs/pinning)
  * the SDK version to avoid breaking changes.
  *
  * Sends a transactional email.
+ *
+ * @param params - The recipient, sender, subject, and content of the email.
+ * @param options - Optional request settings, including an idempotency key.
+ * @returns The stored email and its current send status.
+ * @throws If the idempotency key does not match the supported format.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.create(
+ * {
+ * to: { address: 'customer@example.com' },
+ * from: { address: 'support@example.com' },
+ * subject: 'Your receipt',
+ * html: '<p>Thanks for your order.</p>',
+ * },
+ * { idempotencyKey: 'order_123_receipt' },
+ * );
+ * ```
  */
- public async create(params: CreateEmailParams) {
+ public async create(params: CreateEmailParams, options: CreateEmailOptions = {}): Promise<Email> {
+ const { idempotencyKey } = options;
+ if (
+ idempotencyKey !== undefined &&
+ (typeof idempotencyKey !== 'string' || !idempotencyKeyPattern.test(idempotencyKey))
+ ) {
+ throw new Error(
+ 'Idempotency key must contain only ASCII letters, digits, underscores, and hyphens and cannot exceed 255 characters.',
+ );
+ }
+
  return this.request<Email>({
  method: 'POST',
  path: basePath,
  bodyParams: params,
+ ...(idempotencyKey !== undefined ? { headerParams: { 'Idempotency-Key': idempotencyKey } } : {}),
  options: {
  // Snakecase nested keys too, so a `to: { userId }` recipient is sent as
  // `to: { user_id }` on the wire (the default only snakecases top-level
@@ -127,4 +158,24 @@ export class EmailApi extends AbstractAPI {
  },
  });
  }
+
+ /**
+ * Returns Clerk's stored send state for a transactional email. `accepted`
+ * means the provider accepted the request; it does not prove delivery.
+ *
+ * @param emailId - The ID returned when the email was created.
+ * @returns The stored email and its current send status.
+ * @throws If `emailId` is empty.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.get('ema_123');
+ * ```
+ */
+ public async get(emailId: string): Promise<Email> {
+ this.requireId(emailId);
+ return this.request<Email>({
+ method: 'GET',
+ path: `${basePath}/${emailId}`,
+ });
+ }
 }

packages/backend/src/api/resources/Email.ts

@@ -14,6 +14,7 @@ export class Email {
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
  readonly userId?: string | null,
+ readonly suppressionReason?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -30,6 +31,7 @@ export class Email {
  data.data,
  data.delivered_by_clerk,
  data.user_id,
+ data.suppression_reason,
  );
  }
 }

packages/backend/src/api/resources/JSON.ts

@@ -197,6 +197,7 @@ export interface EmailJSON extends ClerkResourceJSON {
  status?: string;
  data?: Record<string, any> | null;
  delivered_by_clerk: boolean;
+ suppression_reason?: string | null;
 }
 
 export interface EmailAddressJSON extends ClerkResourceJSON {

.changeset/quiet-mails-arrive.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add experimental methods for sending and retrieving internal transactional emails, including Clerk suppression state and reasons.

packages/backend/src/api/__tests__/EmailApi.test.ts

@@ -25,6 +25,7 @@ describe('EmailApi', () => {
  status: 'queued',
  data: null,
  delivered_by_clerk: true,
+ suppression_reason: null,
  };
 
  it('sends a transactional email and snake_cases the body', async () => {
@@ -59,6 +60,107 @@ describe('EmailApi', () => {
  expect(response.deliveredByClerk).toBe(true);
  });
 
+ it('sends an idempotency key without adding it to the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Idempotency-Key')).toBe('campaign-123-contact-456');
+ const body = await request.json();
+ expect(body).not.toHaveProperty('idempotency_key');
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ await apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ { idempotencyKey: 'campaign-123-contact-456' },
+ );
+ });
+
+ it.each([
+ ['an empty value', ''],
+ ['a null value', null],
+ ['a numeric value', 123],
+ ['unsupported characters', 'campaign:123'],
+ ['more than 255 characters', 'a'.repeat(256)],
+ ])('rejects idempotency keys with %s before sending a request', async (_, idempotencyKey) => {
+ let requestCount = 0;
+ server.use(
+ http.post('https://api.clerk.test/v1/email', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(
+ apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ // Exercise the runtime boundary that exists for JavaScript consumers.
+ { idempotencyKey: idempotencyKey as string },
+ ),
+ ).rejects.toThrow('Idempotency key must contain only ASCII letters, digits, underscores, and hyphens');
+ expect(requestCount).toBe(0);
+ });
+
+ it('gets the stored provider-acceptance status', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() => HttpResponse.json({ ...mockEmail, status: 'accepted' })),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.id).toBe('ema_123');
+ expect(response.status).toBe('accepted');
+ });
+
+ it('surfaces transactional suppression state', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() =>
+ HttpResponse.json({
+ ...mockEmail,
+ status: 'suppressed',
+ delivered_by_clerk: false,
+ suppression_reason: 'application_communication_lock',
+ }),
+ ),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.status).toBe('suppressed');
+ expect(response.deliveredByClerk).toBe(false);
+ expect(response.suppressionReason).toBe('application_communication_lock');
+ });
+
+ it('rejects an empty email ID before sending a request', async () => {
+ let requestCount = 0;
+ server.use(
+ http.get('https://api.clerk.test/v1/email/:emailId', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(apiClient.emails.get('')).rejects.toThrow('A valid resource ID is required.');
+ expect(requestCount).toBe(0);
+ });
+
  it('sends a transactional email with a text body', async () => {
  server.use(
  http.post(

packages/backend/src/api/endpoints/EmailApi.ts

@@ -2,21 +2,14 @@ import type { Email } from '../resources/Email';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/email';
+const idempotencyKeyPattern = /^[a-zA-Z0-9_-]{1,255}$/;
 
 /**
- * A subset of mailbox object as specified in RFC 5322 §3.4. Specifically, a
- * `name-addr` with an optional `display-name` and a required `addr-spec`.
+ * A mailbox address as specified by RFC 5322's `addr-spec`.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc5322#section-3.4}
  */
 type Mailbox = {
- /**
- * (Optional) Display name for the mailbox. Currently accepted by the API but
- * not yet rendered server-side, so it has no effect on the delivered email
- * for now.
- */
- name?: string;
-
  /**
  * The `addr-spec` of the mailbox, i.e. the email address itself.
  */
@@ -27,7 +20,7 @@ type Mailbox = {
  * The recipient of the email. Provide exactly one of the two mutually exclusive
  * forms:
  *
- * - a literal mailbox: an `address` (plus an optional `name`), or
+ * - a literal mailbox: an `address`, or
  * - a `userId`: the ID of a Clerk user whose primary email address Clerk
  * resolves server-side, from the instance the secret key belongs to.
  */
@@ -37,11 +30,6 @@ type EmailRecipient =
  * The `addr-spec` of the recipient mailbox, i.e. the email address itself.
  */
  address: string;
- /**
- * (Optional) Display name for the recipient mailbox. Currently accepted
- * by the API but not yet rendered server-side.
- */
- name?: string;
  userId?: never;
  }
  | {
@@ -52,13 +40,13 @@ type EmailRecipient =
  */
  userId: string;
  address?: never;
- name?: never;
  };
 
 /**
  * The body of the email. At least one of `html` and `text` must be provided; if
- * both are provided, the `html` version takes precedence. Encoded as a union so
- * that omitting both is a compile-time error rather than a server-side one.
+ * both are provided, the `html` version takes precedence. Their combined UTF-8
+ * encoding is limited to 50,000 bytes. Encoded as a union so that omitting both
+ * is a compile-time error rather than a server-side one.
  */
 type EmailContent =
  | {
@@ -87,38 +75,81 @@ type EmailContent =
 export type CreateEmailParams = {
  /**
  * The recipient of the email. Currently only a single recipient is supported.
- * Provide either an `address` (with an optional `name`) or the `userId` of a
+ * Provide either an `address` or the `userId` of a
  * Clerk user; the two forms are mutually exclusive.
  */
  to: EmailRecipient;
 
  /**
- * The sender of the email. See {@link Mailbox} for the accepted format. Note
- * that the API does not yet render the `name` field of the `from` mailbox.
+ * The sender of the email. Its domain must exactly match the instance's
+ * verified production sending domain.
  */
  from: Mailbox;
 
  /**
- * (Optional) The mailbox to include in the `reply-to` header of the email.
+ * (Optional) The mailbox to include in the `reply-to` header. Its domain must
+ * exactly match the same verified production domain as `from`.
  */
  replyTo?: Mailbox;
 
+ /** Maximum 998 characters. */
  subject: string;
 } & EmailContent;
 
+export type CreateEmailOptions = {
+ /**
+ * Deduplicates retries of the same logical send. Reuse a key only when the
+ * recipient and content are identical; use one stable key per recipient when
+ * fanning out a batch. Clerk durably returns the original email for the same
+ * key and request, and returns a conflict if the key is reused with different
+ * parameters. Without a key, each call is a distinct send and the SDK does
+ * not retry an ambiguous POST. Keys may contain only ASCII letters, digits,
+ * underscores, and hyphens, up to 255 characters.
+ */
+ idempotencyKey?: string;
+};
+
 export class EmailApi extends AbstractAPI {
  /**
  * @experimental This method calls an internal, not-yet-public endpoint and is
  * subject to change. It is advised to [pin](https://clerk.com/docs/pinning)
  * the SDK version to avoid breaking changes.
  *
  * Sends a transactional email.
+ *
+ * @param params - The recipient, sender, subject, and content of the email.
+ * @param options - Optional request settings, including an idempotency key.
+ * @returns The stored email and its current send status.
+ * @throws If the idempotency key does not match the supported format.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.create(
+ * {
+ * to: { address: 'customer@example.com' },
+ * from: { address: 'support@example.com' },
+ * subject: 'Your receipt',
+ * html: '<p>Thanks for your order.</p>',
+ * },
+ * { idempotencyKey: 'order_123_receipt' },
+ * );
+ * ```
  */
- public async create(params: CreateEmailParams) {
+ public async create(params: CreateEmailParams, options: CreateEmailOptions = {}): Promise<Email> {
+ const { idempotencyKey } = options;
+ if (
+ idempotencyKey !== undefined &&
+ (typeof idempotencyKey !== 'string' || !idempotencyKeyPattern.test(idempotencyKey))
+ ) {
+ throw new Error(
+ 'Idempotency key must contain only ASCII letters, digits, underscores, and hyphens and cannot exceed 255 characters.',
+ );
+ }
+
  return this.request<Email>({
  method: 'POST',
  path: basePath,
  bodyParams: params,
+ ...(idempotencyKey !== undefined ? { headerParams: { 'Idempotency-Key': idempotencyKey } } : {}),
  options: {
  // Snakecase nested keys too, so a `to: { userId }` recipient is sent as
  // `to: { user_id }` on the wire (the default only snakecases top-level
@@ -127,4 +158,24 @@ export class EmailApi extends AbstractAPI {
  },
  });
  }
+
+ /**
+ * Returns Clerk's stored send state for a transactional email. `accepted`
+ * means the provider accepted the request; it does not prove delivery.
+ *
+ * @param emailId - The ID returned when the email was created.
+ * @returns The stored email and its current send status.
+ * @throws If `emailId` is empty.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.get('ema_123');
+ * ```
+ */
+ public async get(emailId: string): Promise<Email> {
+ this.requireId(emailId);
+ return this.request<Email>({
+ method: 'GET',
+ path: `${basePath}/${emailId}`,
+ });
+ }
 }

packages/backend/src/api/resources/Email.ts

@@ -14,6 +14,7 @@ export class Email {
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
  readonly userId?: string | null,
+ readonly suppressionReason?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -30,6 +31,7 @@ export class Email {
  data.data,
  data.delivered_by_clerk,
  data.user_id,
+ data.suppression_reason,
  );
  }
 }

packages/backend/src/api/resources/JSON.ts

@@ -197,6 +197,7 @@ export interface EmailJSON extends ClerkResourceJSON {
  status?: string;
  data?: Record<string, any> | null;
  delivered_by_clerk: boolean;
+ suppression_reason?: string | null;
 }
 
 export interface EmailAddressJSON extends ClerkResourceJSON {

.changeset/quiet-mails-arrive.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add experimental methods for sending and retrieving internal transactional emails, including Clerk suppression state and reasons.

packages/backend/src/api/__tests__/EmailApi.test.ts

@@ -25,6 +25,7 @@ describe('EmailApi', () => {
  status: 'queued',
  data: null,
  delivered_by_clerk: true,
+ suppression_reason: null,
  };
 
  it('sends a transactional email and snake_cases the body', async () => {
@@ -59,6 +60,107 @@ describe('EmailApi', () => {
  expect(response.deliveredByClerk).toBe(true);
  });
 
+ it('sends an idempotency key without adding it to the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Idempotency-Key')).toBe('campaign-123-contact-456');
+ const body = await request.json();
+ expect(body).not.toHaveProperty('idempotency_key');
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ await apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ { idempotencyKey: 'campaign-123-contact-456' },
+ );
+ });
+
+ it.each([
+ ['an empty value', ''],
+ ['a null value', null],
+ ['a numeric value', 123],
+ ['unsupported characters', 'campaign:123'],
+ ['more than 255 characters', 'a'.repeat(256)],
+ ])('rejects idempotency keys with %s before sending a request', async (_, idempotencyKey) => {
+ let requestCount = 0;
+ server.use(
+ http.post('https://api.clerk.test/v1/email', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(
+ apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ // Exercise the runtime boundary that exists for JavaScript consumers.
+ { idempotencyKey: idempotencyKey as string },
+ ),
+ ).rejects.toThrow('Idempotency key must contain only ASCII letters, digits, underscores, and hyphens');
+ expect(requestCount).toBe(0);
+ });
+
+ it('gets the stored provider-acceptance status', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() => HttpResponse.json({ ...mockEmail, status: 'accepted' })),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.id).toBe('ema_123');
+ expect(response.status).toBe('accepted');
+ });
+
+ it('surfaces transactional suppression state', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() =>
+ HttpResponse.json({
+ ...mockEmail,
+ status: 'suppressed',
+ delivered_by_clerk: false,
+ suppression_reason: 'application_communication_lock',
+ }),
+ ),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.status).toBe('suppressed');
+ expect(response.deliveredByClerk).toBe(false);
+ expect(response.suppressionReason).toBe('application_communication_lock');
+ });
+
+ it('rejects an empty email ID before sending a request', async () => {
+ let requestCount = 0;
+ server.use(
+ http.get('https://api.clerk.test/v1/email/:emailId', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(apiClient.emails.get('')).rejects.toThrow('A valid resource ID is required.');
+ expect(requestCount).toBe(0);
+ });
+
  it('sends a transactional email with a text body', async () => {
  server.use(
  http.post(

packages/backend/src/api/endpoints/EmailApi.ts

@@ -2,21 +2,14 @@ import type { Email } from '../resources/Email';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/email';
+const idempotencyKeyPattern = /^[a-zA-Z0-9_-]{1,255}$/;
 
 /**
- * A subset of mailbox object as specified in RFC 5322 §3.4. Specifically, a
- * `name-addr` with an optional `display-name` and a required `addr-spec`.
+ * A mailbox address as specified by RFC 5322's `addr-spec`.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc5322#section-3.4}
  */
 type Mailbox = {
- /**
- * (Optional) Display name for the mailbox. Currently accepted by the API but
- * not yet rendered server-side, so it has no effect on the delivered email
- * for now.
- */
- name?: string;
-
  /**
  * The `addr-spec` of the mailbox, i.e. the email address itself.
  */
@@ -27,7 +20,7 @@ type Mailbox = {
  * The recipient of the email. Provide exactly one of the two mutually exclusive
  * forms:
  *
- * - a literal mailbox: an `address` (plus an optional `name`), or
+ * - a literal mailbox: an `address`, or
  * - a `userId`: the ID of a Clerk user whose primary email address Clerk
  * resolves server-side, from the instance the secret key belongs to.
  */
@@ -37,11 +30,6 @@ type EmailRecipient =
  * The `addr-spec` of the recipient mailbox, i.e. the email address itself.
  */
  address: string;
- /**
- * (Optional) Display name for the recipient mailbox. Currently accepted
- * by the API but not yet rendered server-side.
- */
- name?: string;
  userId?: never;
  }
  | {
@@ -52,13 +40,13 @@ type EmailRecipient =
  */
  userId: string;
  address?: never;
- name?: never;
  };
 
 /**
  * The body of the email. At least one of `html` and `text` must be provided; if
- * both are provided, the `html` version takes precedence. Encoded as a union so
- * that omitting both is a compile-time error rather than a server-side one.
+ * both are provided, the `html` version takes precedence. Their combined UTF-8
+ * encoding is limited to 50,000 bytes. Encoded as a union so that omitting both
+ * is a compile-time error rather than a server-side one.
  */
 type EmailContent =
  | {
@@ -87,38 +75,81 @@ type EmailContent =
 export type CreateEmailParams = {
  /**
  * The recipient of the email. Currently only a single recipient is supported.
- * Provide either an `address` (with an optional `name`) or the `userId` of a
+ * Provide either an `address` or the `userId` of a
  * Clerk user; the two forms are mutually exclusive.
  */
  to: EmailRecipient;
 
  /**
- * The sender of the email. See {@link Mailbox} for the accepted format. Note
- * that the API does not yet render the `name` field of the `from` mailbox.
+ * The sender of the email. Its domain must exactly match the instance's
+ * verified production sending domain.
  */
  from: Mailbox;
 
  /**
- * (Optional) The mailbox to include in the `reply-to` header of the email.
+ * (Optional) The mailbox to include in the `reply-to` header. Its domain must
+ * exactly match the same verified production domain as `from`.
  */
  replyTo?: Mailbox;
 
+ /** Maximum 998 characters. */
  subject: string;
 } & EmailContent;
 
+export type CreateEmailOptions = {
+ /**
+ * Deduplicates retries of the same logical send. Reuse a key only when the
+ * recipient and content are identical; use one stable key per recipient when
+ * fanning out a batch. Clerk durably returns the original email for the same
+ * key and request, and returns a conflict if the key is reused with different
+ * parameters. Without a key, each call is a distinct send and the SDK does
+ * not retry an ambiguous POST. Keys may contain only ASCII letters, digits,
+ * underscores, and hyphens, up to 255 characters.
+ */
+ idempotencyKey?: string;
+};
+
 export class EmailApi extends AbstractAPI {
  /**
  * @experimental This method calls an internal, not-yet-public endpoint and is
  * subject to change. It is advised to [pin](https://clerk.com/docs/pinning)
  * the SDK version to avoid breaking changes.
  *
  * Sends a transactional email.
+ *
+ * @param params - The recipient, sender, subject, and content of the email.
+ * @param options - Optional request settings, including an idempotency key.
+ * @returns The stored email and its current send status.
+ * @throws If the idempotency key does not match the supported format.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.create(
+ * {
+ * to: { address: 'customer@example.com' },
+ * from: { address: 'support@example.com' },
+ * subject: 'Your receipt',
+ * html: '<p>Thanks for your order.</p>',
+ * },
+ * { idempotencyKey: 'order_123_receipt' },
+ * );
+ * ```
  */
- public async create(params: CreateEmailParams) {
+ public async create(params: CreateEmailParams, options: CreateEmailOptions = {}): Promise<Email> {
+ const { idempotencyKey } = options;
+ if (
+ idempotencyKey !== undefined &&
+ (typeof idempotencyKey !== 'string' || !idempotencyKeyPattern.test(idempotencyKey))
+ ) {
+ throw new Error(
+ 'Idempotency key must contain only ASCII letters, digits, underscores, and hyphens and cannot exceed 255 characters.',
+ );
+ }
+
  return this.request<Email>({
  method: 'POST',
  path: basePath,
  bodyParams: params,
+ ...(idempotencyKey !== undefined ? { headerParams: { 'Idempotency-Key': idempotencyKey } } : {}),
  options: {
  // Snakecase nested keys too, so a `to: { userId }` recipient is sent as
  // `to: { user_id }` on the wire (the default only snakecases top-level
@@ -127,4 +158,24 @@ export class EmailApi extends AbstractAPI {
  },
  });
  }
+
+ /**
+ * Returns Clerk's stored send state for a transactional email. `accepted`
+ * means the provider accepted the request; it does not prove delivery.
+ *
+ * @param emailId - The ID returned when the email was created.
+ * @returns The stored email and its current send status.
+ * @throws If `emailId` is empty.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.get('ema_123');
+ * ```
+ */
+ public async get(emailId: string): Promise<Email> {
+ this.requireId(emailId);
+ return this.request<Email>({
+ method: 'GET',
+ path: `${basePath}/${emailId}`,
+ });
+ }
 }

packages/backend/src/api/resources/Email.ts

@@ -14,6 +14,7 @@ export class Email {
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
  readonly userId?: string | null,
+ readonly suppressionReason?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -30,6 +31,7 @@ export class Email {
  data.data,
  data.delivered_by_clerk,
  data.user_id,
+ data.suppression_reason,
  );
  }
 }

packages/backend/src/api/resources/JSON.ts

@@ -197,6 +197,7 @@ export interface EmailJSON extends ClerkResourceJSON {
  status?: string;
  data?: Record<string, any> | null;
  delivered_by_clerk: boolean;
+ suppression_reason?: string | null;
 }
 
 export interface EmailAddressJSON extends ClerkResourceJSON {

.changeset/quiet-mails-arrive.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add experimental methods for sending and retrieving internal transactional emails, including Clerk suppression state and reasons.

packages/backend/src/api/__tests__/EmailApi.test.ts

@@ -25,6 +25,7 @@ describe('EmailApi', () => {
  status: 'queued',
  data: null,
  delivered_by_clerk: true,
+ suppression_reason: null,
  };
 
  it('sends a transactional email and snake_cases the body', async () => {
@@ -59,6 +60,107 @@ describe('EmailApi', () => {
  expect(response.deliveredByClerk).toBe(true);
  });
 
+ it('sends an idempotency key without adding it to the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Idempotency-Key')).toBe('campaign-123-contact-456');
+ const body = await request.json();
+ expect(body).not.toHaveProperty('idempotency_key');
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ await apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ { idempotencyKey: 'campaign-123-contact-456' },
+ );
+ });
+
+ it.each([
+ ['an empty value', ''],
+ ['a null value', null],
+ ['a numeric value', 123],
+ ['unsupported characters', 'campaign:123'],
+ ['more than 255 characters', 'a'.repeat(256)],
+ ])('rejects idempotency keys with %s before sending a request', async (_, idempotencyKey) => {
+ let requestCount = 0;
+ server.use(
+ http.post('https://api.clerk.test/v1/email', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(
+ apiClient.emails.create(
+ {
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ },
+ // Exercise the runtime boundary that exists for JavaScript consumers.
+ { idempotencyKey: idempotencyKey as string },
+ ),
+ ).rejects.toThrow('Idempotency key must contain only ASCII letters, digits, underscores, and hyphens');
+ expect(requestCount).toBe(0);
+ });
+
+ it('gets the stored provider-acceptance status', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() => HttpResponse.json({ ...mockEmail, status: 'accepted' })),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.id).toBe('ema_123');
+ expect(response.status).toBe('accepted');
+ });
+
+ it('surfaces transactional suppression state', async () => {
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/email/ema_123',
+ validateHeaders(() =>
+ HttpResponse.json({
+ ...mockEmail,
+ status: 'suppressed',
+ delivered_by_clerk: false,
+ suppression_reason: 'application_communication_lock',
+ }),
+ ),
+ ),
+ );
+
+ const response = await apiClient.emails.get('ema_123');
+ expect(response.status).toBe('suppressed');
+ expect(response.deliveredByClerk).toBe(false);
+ expect(response.suppressionReason).toBe('application_communication_lock');
+ });
+
+ it('rejects an empty email ID before sending a request', async () => {
+ let requestCount = 0;
+ server.use(
+ http.get('https://api.clerk.test/v1/email/:emailId', () => {
+ requestCount += 1;
+ return HttpResponse.json(mockEmail);
+ }),
+ );
+
+ await expect(apiClient.emails.get('')).rejects.toThrow('A valid resource ID is required.');
+ expect(requestCount).toBe(0);
+ });
+
  it('sends a transactional email with a text body', async () => {
  server.use(
  http.post(

packages/backend/src/api/endpoints/EmailApi.ts

@@ -2,21 +2,14 @@ import type { Email } from '../resources/Email';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/email';
+const idempotencyKeyPattern = /^[a-zA-Z0-9_-]{1,255}$/;
 
 /**
- * A subset of mailbox object as specified in RFC 5322 §3.4. Specifically, a
- * `name-addr` with an optional `display-name` and a required `addr-spec`.
+ * A mailbox address as specified by RFC 5322's `addr-spec`.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc5322#section-3.4}
  */
 type Mailbox = {
- /**
- * (Optional) Display name for the mailbox. Currently accepted by the API but
- * not yet rendered server-side, so it has no effect on the delivered email
- * for now.
- */
- name?: string;
-
  /**
  * The `addr-spec` of the mailbox, i.e. the email address itself.
  */
@@ -27,7 +20,7 @@ type Mailbox = {
  * The recipient of the email. Provide exactly one of the two mutually exclusive
  * forms:
  *
- * - a literal mailbox: an `address` (plus an optional `name`), or
+ * - a literal mailbox: an `address`, or
  * - a `userId`: the ID of a Clerk user whose primary email address Clerk
  * resolves server-side, from the instance the secret key belongs to.
  */
@@ -37,11 +30,6 @@ type EmailRecipient =
  * The `addr-spec` of the recipient mailbox, i.e. the email address itself.
  */
  address: string;
- /**
- * (Optional) Display name for the recipient mailbox. Currently accepted
- * by the API but not yet rendered server-side.
- */
- name?: string;
  userId?: never;
  }
  | {
@@ -52,13 +40,13 @@ type EmailRecipient =
  */
  userId: string;
  address?: never;
- name?: never;
  };
 
 /**
  * The body of the email. At least one of `html` and `text` must be provided; if
- * both are provided, the `html` version takes precedence. Encoded as a union so
- * that omitting both is a compile-time error rather than a server-side one.
+ * both are provided, the `html` version takes precedence. Their combined UTF-8
+ * encoding is limited to 50,000 bytes. Encoded as a union so that omitting both
+ * is a compile-time error rather than a server-side one.
  */
 type EmailContent =
  | {
@@ -87,38 +75,81 @@ type EmailContent =
 export type CreateEmailParams = {
  /**
  * The recipient of the email. Currently only a single recipient is supported.
- * Provide either an `address` (with an optional `name`) or the `userId` of a
+ * Provide either an `address` or the `userId` of a
  * Clerk user; the two forms are mutually exclusive.
  */
  to: EmailRecipient;
 
  /**
- * The sender of the email. See {@link Mailbox} for the accepted format. Note
- * that the API does not yet render the `name` field of the `from` mailbox.
+ * The sender of the email. Its domain must exactly match the instance's
+ * verified production sending domain.
  */
  from: Mailbox;
 
  /**
- * (Optional) The mailbox to include in the `reply-to` header of the email.
+ * (Optional) The mailbox to include in the `reply-to` header. Its domain must
+ * exactly match the same verified production domain as `from`.
  */
  replyTo?: Mailbox;
 
+ /** Maximum 998 characters. */
  subject: string;
 } & EmailContent;
 
+export type CreateEmailOptions = {
+ /**
+ * Deduplicates retries of the same logical send. Reuse a key only when the
+ * recipient and content are identical; use one stable key per recipient when
+ * fanning out a batch. Clerk durably returns the original email for the same
+ * key and request, and returns a conflict if the key is reused with different
+ * parameters. Without a key, each call is a distinct send and the SDK does
+ * not retry an ambiguous POST. Keys may contain only ASCII letters, digits,
+ * underscores, and hyphens, up to 255 characters.
+ */
+ idempotencyKey?: string;
+};
+
 export class EmailApi extends AbstractAPI {
  /**
  * @experimental This method calls an internal, not-yet-public endpoint and is
  * subject to change. It is advised to [pin](https://clerk.com/docs/pinning)
  * the SDK version to avoid breaking changes.
  *
  * Sends a transactional email.
+ *
+ * @param params - The recipient, sender, subject, and content of the email.
+ * @param options - Optional request settings, including an idempotency key.
+ * @returns The stored email and its current send status.
+ * @throws If the idempotency key does not match the supported format.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.create(
+ * {
+ * to: { address: 'customer@example.com' },
+ * from: { address: 'support@example.com' },
+ * subject: 'Your receipt',
+ * html: '<p>Thanks for your order.</p>',
+ * },
+ * { idempotencyKey: 'order_123_receipt' },
+ * );
+ * ```
  */
- public async create(params: CreateEmailParams) {
+ public async create(params: CreateEmailParams, options: CreateEmailOptions = {}): Promise<Email> {
+ const { idempotencyKey } = options;
+ if (
+ idempotencyKey !== undefined &&
+ (typeof idempotencyKey !== 'string' || !idempotencyKeyPattern.test(idempotencyKey))
+ ) {
+ throw new Error(
+ 'Idempotency key must contain only ASCII letters, digits, underscores, and hyphens and cannot exceed 255 characters.',
+ );
+ }
+
  return this.request<Email>({
  method: 'POST',
  path: basePath,
  bodyParams: params,
+ ...(idempotencyKey !== undefined ? { headerParams: { 'Idempotency-Key': idempotencyKey } } : {}),
  options: {
  // Snakecase nested keys too, so a `to: { userId }` recipient is sent as
  // `to: { user_id }` on the wire (the default only snakecases top-level
@@ -127,4 +158,24 @@ export class EmailApi extends AbstractAPI {
  },
  });
  }
+
+ /**
+ * Returns Clerk's stored send state for a transactional email. `accepted`
+ * means the provider accepted the request; it does not prove delivery.
+ *
+ * @param emailId - The ID returned when the email was created.
+ * @returns The stored email and its current send status.
+ * @throws If `emailId` is empty.
+ * @example
+ * ```ts
+ * const email = await clerkClient.emails.get('ema_123');
+ * ```
+ */
+ public async get(emailId: string): Promise<Email> {
+ this.requireId(emailId);
+ return this.request<Email>({
+ method: 'GET',
+ path: `${basePath}/${emailId}`,
+ });
+ }
 }

packages/backend/src/api/resources/Email.ts

@@ -14,6 +14,7 @@ export class Email {
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
  readonly userId?: string | null,
+ readonly suppressionReason?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -30,6 +31,7 @@ export class Email {
  data.data,
  data.delivered_by_clerk,
  data.user_id,
+ data.suppression_reason,
  );
  }
 }

packages/backend/src/api/resources/JSON.ts

@@ -197,6 +197,7 @@ export interface EmailJSON extends ClerkResourceJSON {
  status?: string;
  data?: Record<string, any> | null;
  delivered_by_clerk: boolean;
+ suppression_reason?: string | null;
 }
 
 export interface EmailAddressJSON extends ClerkResourceJSON {