feat(backend): transactional email send with user_id recipient

.changeset/clerk-email-send.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+Add an experimental `clerkClient.emails.create()` method for sending transactional emails. It accepts address- or user-based recipients, supports optional `replyTo`, `subject`, and HTML and/or text content, and returns the created `Email` resource.
+
+This method is marked `@experimental` and may change in a future release.

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

@@ -0,0 +1,130 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('EmailApi', () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ secretKey: 'deadbeef',
+ });
+
+ const mockEmail = {
+ object: 'email',
+ id: 'ema_123',
+ slug: null,
+ from_email_name: 'noreply',
+ reply_to_email_name: null,
+ to_email_address: 'admin@acme.com',
+ email_address_id: null,
+ user_id: null,
+ subject: 'Hello',
+ body: '<p>hi</p>',
+ body_plain: null,
+ status: 'queued',
+ data: null,
+ delivered_by_clerk: true,
+ };
+
+ it('sends a transactional email and snake_cases the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ reply_to: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ replyTo: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.toEmailAddress).toBe('admin@acme.com');
+ expect(response.status).toBe('queued');
+ expect(response.deliveredByClerk).toBe(true);
+ });
+
+ it('sends a transactional email with a text body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ body: null,
+ body_plain: 'hi',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.body).toBeNull();
+ expect(response.bodyPlain).toBe('hi');
+ expect(response.status).toBe('queued');
+ });
+
+ it('sends a transactional email addressed by userId', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ // The nested `userId` must be snake_cased to `user_id` on the wire.
+ expect(body).toEqual({
+ to: { user_id: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ to_email_address: 'member@acme.com',
+ email_address_id: 'idn_123',
+ user_id: 'user_123',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { userId: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.toEmailAddress).toBe('member@acme.com');
+ expect(response.emailAddressId).toBe('idn_123');
+ expect(response.userId).toBe('user_123');
+ });
+});

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

@@ -0,0 +1,130 @@
+import type { Email } from '../resources/Email';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/email';
+
+/**
+ * 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`.
+ *
+ * @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.
+ */
+ address: string;
+};
+
+/**
+ * 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 `userId`: the ID of a Clerk user whose primary email address Clerk
+ * resolves server-side, from the instance the secret key belongs to.
+ */
+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;
+ }
+ | {
+ /**
+ * The ID of the Clerk user to send to. Clerk resolves the user's primary
+ * email address from the instance context. Mutually exclusive with
+ * `address`.
+ */
+ 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.
+ */
+type EmailContent =
+ | {
+ /**
+ * The HTML body of the email. Takes precedence over `text` when both are
+ * provided.
+ */
+ html: string;
+ /**
+ * (Optional) The plain text body of the email.
+ */
+ text?: string;
+ }
+ | {
+ /**
+ * (Optional) The HTML body of the email. Takes precedence over `text`
+ * when both are provided.
+ */
+ html?: string;
+ /**
+ * The plain text body of the email.
+ */
+ text: string;
+ };
+
+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
+ * 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.
+ */
+ from: Mailbox;
+
+ /**
+ * (Optional) The mailbox to include in the `reply-to` header of the email.
+ */
+ replyTo?: Mailbox;
+
+ subject: string;
+} & EmailContent;
+
+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.
+ */
+ public async create(params: CreateEmailParams) {
+ return this.request<Email>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ 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
+ // keys, which would leave the nested `userId` untouched).
+ deepSnakecaseBodyParamKeys: true,
+ },
+ });
+ }
+}

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

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EmailApi';
 export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EmailApi,
  EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
@@ -71,6 +72,12 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ /**
+ * @experimental This calls an internal, not-yet-public endpoint for sending
+ * transactional emails and is subject to change. It is advised to
+ * [pin](https://clerk.com/docs/pinning) the SDK version to avoid breaking changes.
+ */
+ emails: new EmailApi(request),
  enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({

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

@@ -13,6 +13,7 @@ export class Email {
  readonly slug?: string | null,
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
+ readonly userId?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -28,6 +29,7 @@ export class Email {
  data.slug,
  data.data,
  data.delivered_by_clerk,
+ data.user_id,
  );
  }
 }

.changeset/clerk-email-send.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+Add an experimental `clerkClient.emails.create()` method for sending transactional emails. It accepts address- or user-based recipients, supports optional `replyTo`, `subject`, and HTML and/or text content, and returns the created `Email` resource.
+
+This method is marked `@experimental` and may change in a future release.

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

@@ -0,0 +1,130 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('EmailApi', () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ secretKey: 'deadbeef',
+ });
+
+ const mockEmail = {
+ object: 'email',
+ id: 'ema_123',
+ slug: null,
+ from_email_name: 'noreply',
+ reply_to_email_name: null,
+ to_email_address: 'admin@acme.com',
+ email_address_id: null,
+ user_id: null,
+ subject: 'Hello',
+ body: '<p>hi</p>',
+ body_plain: null,
+ status: 'queued',
+ data: null,
+ delivered_by_clerk: true,
+ };
+
+ it('sends a transactional email and snake_cases the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ reply_to: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ replyTo: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.toEmailAddress).toBe('admin@acme.com');
+ expect(response.status).toBe('queued');
+ expect(response.deliveredByClerk).toBe(true);
+ });
+
+ it('sends a transactional email with a text body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ body: null,
+ body_plain: 'hi',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.body).toBeNull();
+ expect(response.bodyPlain).toBe('hi');
+ expect(response.status).toBe('queued');
+ });
+
+ it('sends a transactional email addressed by userId', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ // The nested `userId` must be snake_cased to `user_id` on the wire.
+ expect(body).toEqual({
+ to: { user_id: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ to_email_address: 'member@acme.com',
+ email_address_id: 'idn_123',
+ user_id: 'user_123',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { userId: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.toEmailAddress).toBe('member@acme.com');
+ expect(response.emailAddressId).toBe('idn_123');
+ expect(response.userId).toBe('user_123');
+ });
+});

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

@@ -0,0 +1,130 @@
+import type { Email } from '../resources/Email';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/email';
+
+/**
+ * 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`.
+ *
+ * @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.
+ */
+ address: string;
+};
+
+/**
+ * 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 `userId`: the ID of a Clerk user whose primary email address Clerk
+ * resolves server-side, from the instance the secret key belongs to.
+ */
+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;
+ }
+ | {
+ /**
+ * The ID of the Clerk user to send to. Clerk resolves the user's primary
+ * email address from the instance context. Mutually exclusive with
+ * `address`.
+ */
+ 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.
+ */
+type EmailContent =
+ | {
+ /**
+ * The HTML body of the email. Takes precedence over `text` when both are
+ * provided.
+ */
+ html: string;
+ /**
+ * (Optional) The plain text body of the email.
+ */
+ text?: string;
+ }
+ | {
+ /**
+ * (Optional) The HTML body of the email. Takes precedence over `text`
+ * when both are provided.
+ */
+ html?: string;
+ /**
+ * The plain text body of the email.
+ */
+ text: string;
+ };
+
+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
+ * 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.
+ */
+ from: Mailbox;
+
+ /**
+ * (Optional) The mailbox to include in the `reply-to` header of the email.
+ */
+ replyTo?: Mailbox;
+
+ subject: string;
+} & EmailContent;
+
+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.
+ */
+ public async create(params: CreateEmailParams) {
+ return this.request<Email>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ 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
+ // keys, which would leave the nested `userId` untouched).
+ deepSnakecaseBodyParamKeys: true,
+ },
+ });
+ }
+}

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

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EmailApi';
 export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EmailApi,
  EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
@@ -71,6 +72,12 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ /**
+ * @experimental This calls an internal, not-yet-public endpoint for sending
+ * transactional emails and is subject to change. It is advised to
+ * [pin](https://clerk.com/docs/pinning) the SDK version to avoid breaking changes.
+ */
+ emails: new EmailApi(request),
  enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({

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

@@ -13,6 +13,7 @@ export class Email {
  readonly slug?: string | null,
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
+ readonly userId?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -28,6 +29,7 @@ export class Email {
  data.slug,
  data.data,
  data.delivered_by_clerk,
+ data.user_id,
  );
  }
 }

.changeset/clerk-email-send.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+Add an experimental `clerkClient.emails.create()` method for sending transactional emails. It accepts address- or user-based recipients, supports optional `replyTo`, `subject`, and HTML and/or text content, and returns the created `Email` resource.
+
+This method is marked `@experimental` and may change in a future release.

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

@@ -0,0 +1,130 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('EmailApi', () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ secretKey: 'deadbeef',
+ });
+
+ const mockEmail = {
+ object: 'email',
+ id: 'ema_123',
+ slug: null,
+ from_email_name: 'noreply',
+ reply_to_email_name: null,
+ to_email_address: 'admin@acme.com',
+ email_address_id: null,
+ user_id: null,
+ subject: 'Hello',
+ body: '<p>hi</p>',
+ body_plain: null,
+ status: 'queued',
+ data: null,
+ delivered_by_clerk: true,
+ };
+
+ it('sends a transactional email and snake_cases the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ reply_to: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ replyTo: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.toEmailAddress).toBe('admin@acme.com');
+ expect(response.status).toBe('queued');
+ expect(response.deliveredByClerk).toBe(true);
+ });
+
+ it('sends a transactional email with a text body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ body: null,
+ body_plain: 'hi',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.body).toBeNull();
+ expect(response.bodyPlain).toBe('hi');
+ expect(response.status).toBe('queued');
+ });
+
+ it('sends a transactional email addressed by userId', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ // The nested `userId` must be snake_cased to `user_id` on the wire.
+ expect(body).toEqual({
+ to: { user_id: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ to_email_address: 'member@acme.com',
+ email_address_id: 'idn_123',
+ user_id: 'user_123',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { userId: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.toEmailAddress).toBe('member@acme.com');
+ expect(response.emailAddressId).toBe('idn_123');
+ expect(response.userId).toBe('user_123');
+ });
+});

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

@@ -0,0 +1,130 @@
+import type { Email } from '../resources/Email';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/email';
+
+/**
+ * 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`.
+ *
+ * @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.
+ */
+ address: string;
+};
+
+/**
+ * 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 `userId`: the ID of a Clerk user whose primary email address Clerk
+ * resolves server-side, from the instance the secret key belongs to.
+ */
+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;
+ }
+ | {
+ /**
+ * The ID of the Clerk user to send to. Clerk resolves the user's primary
+ * email address from the instance context. Mutually exclusive with
+ * `address`.
+ */
+ 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.
+ */
+type EmailContent =
+ | {
+ /**
+ * The HTML body of the email. Takes precedence over `text` when both are
+ * provided.
+ */
+ html: string;
+ /**
+ * (Optional) The plain text body of the email.
+ */
+ text?: string;
+ }
+ | {
+ /**
+ * (Optional) The HTML body of the email. Takes precedence over `text`
+ * when both are provided.
+ */
+ html?: string;
+ /**
+ * The plain text body of the email.
+ */
+ text: string;
+ };
+
+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
+ * 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.
+ */
+ from: Mailbox;
+
+ /**
+ * (Optional) The mailbox to include in the `reply-to` header of the email.
+ */
+ replyTo?: Mailbox;
+
+ subject: string;
+} & EmailContent;
+
+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.
+ */
+ public async create(params: CreateEmailParams) {
+ return this.request<Email>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ 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
+ // keys, which would leave the nested `userId` untouched).
+ deepSnakecaseBodyParamKeys: true,
+ },
+ });
+ }
+}

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

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EmailApi';
 export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EmailApi,
  EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
@@ -71,6 +72,12 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ /**
+ * @experimental This calls an internal, not-yet-public endpoint for sending
+ * transactional emails and is subject to change. It is advised to
+ * [pin](https://clerk.com/docs/pinning) the SDK version to avoid breaking changes.
+ */
+ emails: new EmailApi(request),
  enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({

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

@@ -13,6 +13,7 @@ export class Email {
  readonly slug?: string | null,
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
+ readonly userId?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -28,6 +29,7 @@ export class Email {
  data.slug,
  data.data,
  data.delivered_by_clerk,
+ data.user_id,
  );
  }
 }

.changeset/clerk-email-send.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+Add an experimental `clerkClient.emails.create()` method for sending transactional emails. It accepts address- or user-based recipients, supports optional `replyTo`, `subject`, and HTML and/or text content, and returns the created `Email` resource.
+
+This method is marked `@experimental` and may change in a future release.

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

@@ -0,0 +1,130 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('EmailApi', () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ secretKey: 'deadbeef',
+ });
+
+ const mockEmail = {
+ object: 'email',
+ id: 'ema_123',
+ slug: null,
+ from_email_name: 'noreply',
+ reply_to_email_name: null,
+ to_email_address: 'admin@acme.com',
+ email_address_id: null,
+ user_id: null,
+ subject: 'Hello',
+ body: '<p>hi</p>',
+ body_plain: null,
+ status: 'queued',
+ data: null,
+ delivered_by_clerk: true,
+ };
+
+ it('sends a transactional email and snake_cases the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ reply_to: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ replyTo: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.toEmailAddress).toBe('admin@acme.com');
+ expect(response.status).toBe('queued');
+ expect(response.deliveredByClerk).toBe(true);
+ });
+
+ it('sends a transactional email with a text body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ body: null,
+ body_plain: 'hi',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.body).toBeNull();
+ expect(response.bodyPlain).toBe('hi');
+ expect(response.status).toBe('queued');
+ });
+
+ it('sends a transactional email addressed by userId', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ // The nested `userId` must be snake_cased to `user_id` on the wire.
+ expect(body).toEqual({
+ to: { user_id: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ to_email_address: 'member@acme.com',
+ email_address_id: 'idn_123',
+ user_id: 'user_123',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { userId: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.toEmailAddress).toBe('member@acme.com');
+ expect(response.emailAddressId).toBe('idn_123');
+ expect(response.userId).toBe('user_123');
+ });
+});

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

@@ -0,0 +1,130 @@
+import type { Email } from '../resources/Email';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/email';
+
+/**
+ * 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`.
+ *
+ * @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.
+ */
+ address: string;
+};
+
+/**
+ * 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 `userId`: the ID of a Clerk user whose primary email address Clerk
+ * resolves server-side, from the instance the secret key belongs to.
+ */
+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;
+ }
+ | {
+ /**
+ * The ID of the Clerk user to send to. Clerk resolves the user's primary
+ * email address from the instance context. Mutually exclusive with
+ * `address`.
+ */
+ 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.
+ */
+type EmailContent =
+ | {
+ /**
+ * The HTML body of the email. Takes precedence over `text` when both are
+ * provided.
+ */
+ html: string;
+ /**
+ * (Optional) The plain text body of the email.
+ */
+ text?: string;
+ }
+ | {
+ /**
+ * (Optional) The HTML body of the email. Takes precedence over `text`
+ * when both are provided.
+ */
+ html?: string;
+ /**
+ * The plain text body of the email.
+ */
+ text: string;
+ };
+
+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
+ * 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.
+ */
+ from: Mailbox;
+
+ /**
+ * (Optional) The mailbox to include in the `reply-to` header of the email.
+ */
+ replyTo?: Mailbox;
+
+ subject: string;
+} & EmailContent;
+
+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.
+ */
+ public async create(params: CreateEmailParams) {
+ return this.request<Email>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ 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
+ // keys, which would leave the nested `userId` untouched).
+ deepSnakecaseBodyParamKeys: true,
+ },
+ });
+ }
+}

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

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EmailApi';
 export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EmailApi,
  EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
@@ -71,6 +72,12 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ /**
+ * @experimental This calls an internal, not-yet-public endpoint for sending
+ * transactional emails and is subject to change. It is advised to
+ * [pin](https://clerk.com/docs/pinning) the SDK version to avoid breaking changes.
+ */
+ emails: new EmailApi(request),
  enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({

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

@@ -13,6 +13,7 @@ export class Email {
  readonly slug?: string | null,
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
+ readonly userId?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -28,6 +29,7 @@ export class Email {
  data.slug,
  data.data,
  data.delivered_by_clerk,
+ data.user_id,
  );
  }
 }

.changeset/clerk-email-send.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+Add an experimental `clerkClient.emails.create()` method for sending transactional emails. It accepts address- or user-based recipients, supports optional `replyTo`, `subject`, and HTML and/or text content, and returns the created `Email` resource.
+
+This method is marked `@experimental` and may change in a future release.

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

@@ -0,0 +1,130 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('EmailApi', () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ secretKey: 'deadbeef',
+ });
+
+ const mockEmail = {
+ object: 'email',
+ id: 'ema_123',
+ slug: null,
+ from_email_name: 'noreply',
+ reply_to_email_name: null,
+ to_email_address: 'admin@acme.com',
+ email_address_id: null,
+ user_id: null,
+ subject: 'Hello',
+ body: '<p>hi</p>',
+ body_plain: null,
+ status: 'queued',
+ data: null,
+ delivered_by_clerk: true,
+ };
+
+ it('sends a transactional email and snake_cases the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ reply_to: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ replyTo: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.toEmailAddress).toBe('admin@acme.com');
+ expect(response.status).toBe('queued');
+ expect(response.deliveredByClerk).toBe(true);
+ });
+
+ it('sends a transactional email with a text body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ body: null,
+ body_plain: 'hi',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.body).toBeNull();
+ expect(response.bodyPlain).toBe('hi');
+ expect(response.status).toBe('queued');
+ });
+
+ it('sends a transactional email addressed by userId', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ // The nested `userId` must be snake_cased to `user_id` on the wire.
+ expect(body).toEqual({
+ to: { user_id: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ to_email_address: 'member@acme.com',
+ email_address_id: 'idn_123',
+ user_id: 'user_123',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { userId: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.toEmailAddress).toBe('member@acme.com');
+ expect(response.emailAddressId).toBe('idn_123');
+ expect(response.userId).toBe('user_123');
+ });
+});

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

@@ -0,0 +1,130 @@
+import type { Email } from '../resources/Email';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/email';
+
+/**
+ * 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`.
+ *
+ * @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.
+ */
+ address: string;
+};
+
+/**
+ * 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 `userId`: the ID of a Clerk user whose primary email address Clerk
+ * resolves server-side, from the instance the secret key belongs to.
+ */
+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;
+ }
+ | {
+ /**
+ * The ID of the Clerk user to send to. Clerk resolves the user's primary
+ * email address from the instance context. Mutually exclusive with
+ * `address`.
+ */
+ 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.
+ */
+type EmailContent =
+ | {
+ /**
+ * The HTML body of the email. Takes precedence over `text` when both are
+ * provided.
+ */
+ html: string;
+ /**
+ * (Optional) The plain text body of the email.
+ */
+ text?: string;
+ }
+ | {
+ /**
+ * (Optional) The HTML body of the email. Takes precedence over `text`
+ * when both are provided.
+ */
+ html?: string;
+ /**
+ * The plain text body of the email.
+ */
+ text: string;
+ };
+
+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
+ * 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.
+ */
+ from: Mailbox;
+
+ /**
+ * (Optional) The mailbox to include in the `reply-to` header of the email.
+ */
+ replyTo?: Mailbox;
+
+ subject: string;
+} & EmailContent;
+
+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.
+ */
+ public async create(params: CreateEmailParams) {
+ return this.request<Email>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ 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
+ // keys, which would leave the nested `userId` untouched).
+ deepSnakecaseBodyParamKeys: true,
+ },
+ });
+ }
+}

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

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EmailApi';
 export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EmailApi,
  EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
@@ -71,6 +72,12 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ /**
+ * @experimental This calls an internal, not-yet-public endpoint for sending
+ * transactional emails and is subject to change. It is advised to
+ * [pin](https://clerk.com/docs/pinning) the SDK version to avoid breaking changes.
+ */
+ emails: new EmailApi(request),
  enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({

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

@@ -13,6 +13,7 @@ export class Email {
  readonly slug?: string | null,
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
+ readonly userId?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -28,6 +29,7 @@ export class Email {
  data.slug,
  data.data,
  data.delivered_by_clerk,
+ data.user_id,
  );
  }
 }

.changeset/clerk-email-send.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+Add an experimental `clerkClient.emails.create()` method for sending transactional emails. It accepts address- or user-based recipients, supports optional `replyTo`, `subject`, and HTML and/or text content, and returns the created `Email` resource.
+
+This method is marked `@experimental` and may change in a future release.

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

@@ -0,0 +1,130 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('EmailApi', () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ secretKey: 'deadbeef',
+ });
+
+ const mockEmail = {
+ object: 'email',
+ id: 'ema_123',
+ slug: null,
+ from_email_name: 'noreply',
+ reply_to_email_name: null,
+ to_email_address: 'admin@acme.com',
+ email_address_id: null,
+ user_id: null,
+ subject: 'Hello',
+ body: '<p>hi</p>',
+ body_plain: null,
+ status: 'queued',
+ data: null,
+ delivered_by_clerk: true,
+ };
+
+ it('sends a transactional email and snake_cases the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ reply_to: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ replyTo: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.toEmailAddress).toBe('admin@acme.com');
+ expect(response.status).toBe('queued');
+ expect(response.deliveredByClerk).toBe(true);
+ });
+
+ it('sends a transactional email with a text body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ body: null,
+ body_plain: 'hi',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.body).toBeNull();
+ expect(response.bodyPlain).toBe('hi');
+ expect(response.status).toBe('queued');
+ });
+
+ it('sends a transactional email addressed by userId', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ // The nested `userId` must be snake_cased to `user_id` on the wire.
+ expect(body).toEqual({
+ to: { user_id: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ to_email_address: 'member@acme.com',
+ email_address_id: 'idn_123',
+ user_id: 'user_123',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { userId: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.toEmailAddress).toBe('member@acme.com');
+ expect(response.emailAddressId).toBe('idn_123');
+ expect(response.userId).toBe('user_123');
+ });
+});

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

@@ -0,0 +1,130 @@
+import type { Email } from '../resources/Email';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/email';
+
+/**
+ * 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`.
+ *
+ * @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.
+ */
+ address: string;
+};
+
+/**
+ * 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 `userId`: the ID of a Clerk user whose primary email address Clerk
+ * resolves server-side, from the instance the secret key belongs to.
+ */
+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;
+ }
+ | {
+ /**
+ * The ID of the Clerk user to send to. Clerk resolves the user's primary
+ * email address from the instance context. Mutually exclusive with
+ * `address`.
+ */
+ 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.
+ */
+type EmailContent =
+ | {
+ /**
+ * The HTML body of the email. Takes precedence over `text` when both are
+ * provided.
+ */
+ html: string;
+ /**
+ * (Optional) The plain text body of the email.
+ */
+ text?: string;
+ }
+ | {
+ /**
+ * (Optional) The HTML body of the email. Takes precedence over `text`
+ * when both are provided.
+ */
+ html?: string;
+ /**
+ * The plain text body of the email.
+ */
+ text: string;
+ };
+
+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
+ * 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.
+ */
+ from: Mailbox;
+
+ /**
+ * (Optional) The mailbox to include in the `reply-to` header of the email.
+ */
+ replyTo?: Mailbox;
+
+ subject: string;
+} & EmailContent;
+
+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.
+ */
+ public async create(params: CreateEmailParams) {
+ return this.request<Email>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ 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
+ // keys, which would leave the nested `userId` untouched).
+ deepSnakecaseBodyParamKeys: true,
+ },
+ });
+ }
+}

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

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EmailApi';
 export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EmailApi,
  EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
@@ -71,6 +72,12 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ /**
+ * @experimental This calls an internal, not-yet-public endpoint for sending
+ * transactional emails and is subject to change. It is advised to
+ * [pin](https://clerk.com/docs/pinning) the SDK version to avoid breaking changes.
+ */
+ emails: new EmailApi(request),
  enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({

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

@@ -13,6 +13,7 @@ export class Email {
  readonly slug?: string | null,
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
+ readonly userId?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -28,6 +29,7 @@ export class Email {
  data.slug,
  data.data,
  data.delivered_by_clerk,
+ data.user_id,
  );
  }
 }

.changeset/clerk-email-send.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+Add an experimental `clerkClient.emails.create()` method for sending transactional emails. It accepts address- or user-based recipients, supports optional `replyTo`, `subject`, and HTML and/or text content, and returns the created `Email` resource.
+
+This method is marked `@experimental` and may change in a future release.

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

@@ -0,0 +1,130 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('EmailApi', () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ secretKey: 'deadbeef',
+ });
+
+ const mockEmail = {
+ object: 'email',
+ id: 'ema_123',
+ slug: null,
+ from_email_name: 'noreply',
+ reply_to_email_name: null,
+ to_email_address: 'admin@acme.com',
+ email_address_id: null,
+ user_id: null,
+ subject: 'Hello',
+ body: '<p>hi</p>',
+ body_plain: null,
+ status: 'queued',
+ data: null,
+ delivered_by_clerk: true,
+ };
+
+ it('sends a transactional email and snake_cases the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ reply_to: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ replyTo: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.toEmailAddress).toBe('admin@acme.com');
+ expect(response.status).toBe('queued');
+ expect(response.deliveredByClerk).toBe(true);
+ });
+
+ it('sends a transactional email with a text body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ body: null,
+ body_plain: 'hi',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.body).toBeNull();
+ expect(response.bodyPlain).toBe('hi');
+ expect(response.status).toBe('queued');
+ });
+
+ it('sends a transactional email addressed by userId', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ // The nested `userId` must be snake_cased to `user_id` on the wire.
+ expect(body).toEqual({
+ to: { user_id: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ to_email_address: 'member@acme.com',
+ email_address_id: 'idn_123',
+ user_id: 'user_123',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { userId: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.toEmailAddress).toBe('member@acme.com');
+ expect(response.emailAddressId).toBe('idn_123');
+ expect(response.userId).toBe('user_123');
+ });
+});

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

@@ -0,0 +1,130 @@
+import type { Email } from '../resources/Email';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/email';
+
+/**
+ * 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`.
+ *
+ * @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.
+ */
+ address: string;
+};
+
+/**
+ * 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 `userId`: the ID of a Clerk user whose primary email address Clerk
+ * resolves server-side, from the instance the secret key belongs to.
+ */
+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;
+ }
+ | {
+ /**
+ * The ID of the Clerk user to send to. Clerk resolves the user's primary
+ * email address from the instance context. Mutually exclusive with
+ * `address`.
+ */
+ 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.
+ */
+type EmailContent =
+ | {
+ /**
+ * The HTML body of the email. Takes precedence over `text` when both are
+ * provided.
+ */
+ html: string;
+ /**
+ * (Optional) The plain text body of the email.
+ */
+ text?: string;
+ }
+ | {
+ /**
+ * (Optional) The HTML body of the email. Takes precedence over `text`
+ * when both are provided.
+ */
+ html?: string;
+ /**
+ * The plain text body of the email.
+ */
+ text: string;
+ };
+
+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
+ * 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.
+ */
+ from: Mailbox;
+
+ /**
+ * (Optional) The mailbox to include in the `reply-to` header of the email.
+ */
+ replyTo?: Mailbox;
+
+ subject: string;
+} & EmailContent;
+
+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.
+ */
+ public async create(params: CreateEmailParams) {
+ return this.request<Email>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ 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
+ // keys, which would leave the nested `userId` untouched).
+ deepSnakecaseBodyParamKeys: true,
+ },
+ });
+ }
+}

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

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EmailApi';
 export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EmailApi,
  EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
@@ -71,6 +72,12 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ /**
+ * @experimental This calls an internal, not-yet-public endpoint for sending
+ * transactional emails and is subject to change. It is advised to
+ * [pin](https://clerk.com/docs/pinning) the SDK version to avoid breaking changes.
+ */
+ emails: new EmailApi(request),
  enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({

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

@@ -13,6 +13,7 @@ export class Email {
  readonly slug?: string | null,
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
+ readonly userId?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -28,6 +29,7 @@ export class Email {
  data.slug,
  data.data,
  data.delivered_by_clerk,
+ data.user_id,
  );
  }
 }

.changeset/clerk-email-send.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+Add an experimental `clerkClient.emails.create()` method for sending transactional emails. It accepts address- or user-based recipients, supports optional `replyTo`, `subject`, and HTML and/or text content, and returns the created `Email` resource.
+
+This method is marked `@experimental` and may change in a future release.

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

@@ -0,0 +1,130 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('EmailApi', () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ secretKey: 'deadbeef',
+ });
+
+ const mockEmail = {
+ object: 'email',
+ id: 'ema_123',
+ slug: null,
+ from_email_name: 'noreply',
+ reply_to_email_name: null,
+ to_email_address: 'admin@acme.com',
+ email_address_id: null,
+ user_id: null,
+ subject: 'Hello',
+ body: '<p>hi</p>',
+ body_plain: null,
+ status: 'queued',
+ data: null,
+ delivered_by_clerk: true,
+ };
+
+ it('sends a transactional email and snake_cases the body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ reply_to: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json(mockEmail);
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ replyTo: { address: 'support@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.toEmailAddress).toBe('admin@acme.com');
+ expect(response.status).toBe('queued');
+ expect(response.deliveredByClerk).toBe(true);
+ });
+
+ it('sends a transactional email with a text body', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ body: null,
+ body_plain: 'hi',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { address: 'admin@acme.com' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ text: 'hi',
+ });
+
+ expect(response.id).toBe('ema_123');
+ expect(response.body).toBeNull();
+ expect(response.bodyPlain).toBe('hi');
+ expect(response.status).toBe('queued');
+ });
+
+ it('sends a transactional email addressed by userId', async () => {
+ server.use(
+ http.post(
+ 'https://api.clerk.test/v1/email',
+ validateHeaders(async ({ request }) => {
+ const body = await request.json();
+ // The nested `userId` must be snake_cased to `user_id` on the wire.
+ expect(body).toEqual({
+ to: { user_id: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+ return HttpResponse.json({
+ ...mockEmail,
+ to_email_address: 'member@acme.com',
+ email_address_id: 'idn_123',
+ user_id: 'user_123',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.emails.create({
+ to: { userId: 'user_123' },
+ from: { address: 'noreply@acme.com' },
+ subject: 'Hello',
+ html: '<p>hi</p>',
+ });
+
+ expect(response.toEmailAddress).toBe('member@acme.com');
+ expect(response.emailAddressId).toBe('idn_123');
+ expect(response.userId).toBe('user_123');
+ });
+});

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

@@ -0,0 +1,130 @@
+import type { Email } from '../resources/Email';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/email';
+
+/**
+ * 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`.
+ *
+ * @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.
+ */
+ address: string;
+};
+
+/**
+ * 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 `userId`: the ID of a Clerk user whose primary email address Clerk
+ * resolves server-side, from the instance the secret key belongs to.
+ */
+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;
+ }
+ | {
+ /**
+ * The ID of the Clerk user to send to. Clerk resolves the user's primary
+ * email address from the instance context. Mutually exclusive with
+ * `address`.
+ */
+ 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.
+ */
+type EmailContent =
+ | {
+ /**
+ * The HTML body of the email. Takes precedence over `text` when both are
+ * provided.
+ */
+ html: string;
+ /**
+ * (Optional) The plain text body of the email.
+ */
+ text?: string;
+ }
+ | {
+ /**
+ * (Optional) The HTML body of the email. Takes precedence over `text`
+ * when both are provided.
+ */
+ html?: string;
+ /**
+ * The plain text body of the email.
+ */
+ text: string;
+ };
+
+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
+ * 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.
+ */
+ from: Mailbox;
+
+ /**
+ * (Optional) The mailbox to include in the `reply-to` header of the email.
+ */
+ replyTo?: Mailbox;
+
+ subject: string;
+} & EmailContent;
+
+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.
+ */
+ public async create(params: CreateEmailParams) {
+ return this.request<Email>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ 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
+ // keys, which would leave the nested `userId` untouched).
+ deepSnakecaseBodyParamKeys: true,
+ },
+ });
+ }
+}

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

@@ -9,6 +9,7 @@ export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './EmailApi';
 export * from './EnterpriseConnectionApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';

packages/backend/src/api/factory.ts

@@ -9,6 +9,7 @@ import {
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ EmailApi,
  EnterpriseConnectionAPI,
  IdPOAuthAccessTokenApi,
  InstanceAPI,
@@ -71,6 +72,12 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),
+ /**
+ * @experimental This calls an internal, not-yet-public endpoint for sending
+ * transactional emails and is subject to change. It is advised to
+ * [pin](https://clerk.com/docs/pinning) the SDK version to avoid breaking changes.
+ */
+ emails: new EmailApi(request),
  enterpriseConnections: new EnterpriseConnectionAPI(request),
  idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
  buildRequest({

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

@@ -13,6 +13,7 @@ export class Email {
  readonly slug?: string | null,
  readonly data?: Record<string, any> | null,
  readonly deliveredByClerk?: boolean,
+ readonly userId?: string | null,
  ) {}
 
  static fromJSON(data: EmailJSON): Email {
@@ -28,6 +29,7 @@ export class Email {
  data.slug,
  data.data,
  data.delivered_by_clerk,
+ data.user_id,
  );
  }
 }