resend-cli 1.0.3 → 1.2.0

package/src/commands/domains/verify.ts

@@ -0,0 +1,38 @@
+import { Command } from '@commander-js/extra-typings';
+import { runWrite } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+
+export const verifyDomainCommand = new Command('verify')
+  .description('Trigger async DNS verification for a domain')
+  .argument('<id>', 'Domain ID')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Verification is async — the domain enters "pending" status while DNS records are checked.
+Poll the status with: resend domains get <id>`,
+      output: '  {"object":"domain","id":"<id>"}',
+      errorCodes: ['auth_error', 'verify_error'],
+      examples: [
+        'resend domains verify 4dd369bc-aa82-4ff3-97de-514ae3000ee0',
+        'resend domains verify 4dd369bc-aa82-4ff3-97de-514ae3000ee0 --json',
+      ],
+    }),
+  )
+  .action(async (id, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    await runWrite(
+      {
+        spinner: {
+          loading: 'Verifying domain...',
+          success: 'Verification started',
+          fail: 'Failed to verify domain',
+        },
+        sdkCall: (resend) => resend.domains.verify(id),
+        errorCode: 'verify_error',
+        successMsg: `Domain verification started. Check status with resend domains get ${id}.`,
+      },
+      globalOpts,
+    );
+  });

package/src/commands/emails/batch.ts

@@ -0,0 +1,140 @@
+import { Command } from '@commander-js/extra-typings';
+import type { CreateBatchOptions } from 'resend';
+import type { GlobalOpts } from '../../lib/client';
+import { requireClient } from '../../lib/client';
+import { readFile } from '../../lib/files';
+import { buildHelpText } from '../../lib/help-text';
+import { outputError, outputResult } from '../../lib/output';
+import { requireText } from '../../lib/prompts';
+import { withSpinner } from '../../lib/spinner';
+import { isInteractive } from '../../lib/tty';
+
+export const batchCommand = new Command('batch')
+  .description('Send up to 100 emails in a single API request from a JSON file')
+  .option(
+    '--file <path>',
+    'Path to a JSON file containing an array of email objects (required in non-interactive mode)',
+  )
+  .option(
+    '--idempotency-key <key>',
+    'Deduplicate this batch request using this key',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context:
+        'Non-interactive: --file\nLimit: 100 emails per request (API hard limit — warned if exceeded)\nUnsupported per-email fields: attachments, scheduled_at\n\nFile format (--file path):\n  [\n    {"from":"you@domain.com","to":["user@example.com"],"subject":"Hello","text":"Hi"},\n    {"from":"you@domain.com","to":["other@example.com"],"subject":"Hello","html":"<b>Hi</b>"}\n  ]',
+      output: '  [{"id":"<email-id>"},{"id":"<email-id>"}]',
+      errorCodes: [
+        'auth_error',
+        'missing_file',
+        'file_read_error',
+        'invalid_json',
+        'invalid_format',
+        'batch_error',
+      ],
+      examples: [
+        'resend emails batch --file ./emails.json',
+        'resend emails batch --file ./emails.json --json',
+        'resend emails batch --file ./emails.json --idempotency-key my-batch-2026-02-18',
+        'RESEND_API_KEY=re_123 resend emails batch --file ./emails.json --json',
+      ],
+    }),
+  )
+  .action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    const resend = requireClient(globalOpts);
+
+    const filePath = await requireText(
+      opts.file,
+      { message: 'Path to JSON file', placeholder: './emails.json' },
+      {
+        message:
+          'Missing --file flag. Provide a JSON file with an array of email objects.',
+        code: 'missing_file',
+      },
+      globalOpts,
+    );
+
+    const raw = readFile(filePath, globalOpts);
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      outputError(
+        { message: 'File content is not valid JSON.', code: 'invalid_json' },
+        { json: globalOpts.json },
+      );
+    }
+
+    if (!Array.isArray(parsed)) {
+      outputError(
+        {
+          message: 'File content must be a JSON array of email objects.',
+          code: 'invalid_format',
+        },
+        { json: globalOpts.json },
+      );
+    }
+
+    const emails = parsed as unknown[];
+
+    if (emails.length > 100) {
+      console.warn(
+        `Warning: ${emails.length} emails exceeds the 100-email limit. The API may reject this request.`,
+      );
+    }
+
+    for (let i = 0; i < emails.length; i++) {
+      const email = emails[i] as Record<string, unknown>;
+      if ('attachments' in email) {
+        outputError(
+          {
+            message: `Email at index ${i} contains "attachments", which is not supported in batch sends.`,
+            code: 'batch_error',
+          },
+          { json: globalOpts.json },
+        );
+      }
+      if ('scheduled_at' in email) {
+        outputError(
+          {
+            message: `Email at index ${i} contains "scheduled_at", which is not supported in batch sends.`,
+            code: 'batch_error',
+          },
+          { json: globalOpts.json },
+        );
+      }
+    }
+
+    const batchData = await withSpinner(
+      {
+        loading: 'Sending batch...',
+        success: 'Batch sent',
+        fail: 'Failed to send batch',
+      },
+      () =>
+        resend.batch.send(
+          emails as CreateBatchOptions,
+          opts.idempotencyKey
+            ? { idempotencyKey: opts.idempotencyKey }
+            : undefined,
+        ),
+      'batch_error',
+      globalOpts,
+    );
+
+    const emailIds = batchData.data;
+    if (!globalOpts.json && isInteractive()) {
+      console.log(
+        `Sent ${emailIds.length} email${emailIds.length === 1 ? '' : 's'}`,
+      );
+      for (const email of emailIds) {
+        console.log(`  ${email.id}`);
+      }
+    } else {
+      outputResult(emailIds, { json: globalOpts.json });
+    }
+  });

package/src/commands/emails/index.ts

@@ -0,0 +1,24 @@
+import { Command } from '@commander-js/extra-typings';
+import { buildHelpText } from '../../lib/help-text';
+import { batchCommand } from './batch';
+import { receivingCommand } from './receiving/index';
+import { sendCommand } from './send';
+
+export const emailsCommand = new Command('emails')
+  .description('Send and manage emails')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      examples: [
+        'resend emails send --from you@domain.com --to user@example.com --subject "Hello" --text "Hi"',
+        'resend emails batch --file ./emails.json',
+        'resend emails receiving list',
+        'resend emails receiving get <email-id>',
+        'resend emails receiving attachments <email-id>',
+        'resend emails receiving attachment <email-id> <attachment-id>',
+      ],
+    }),
+  )
+  .addCommand(sendCommand)
+  .addCommand(batchCommand)
+  .addCommand(receivingCommand);

package/src/commands/emails/receiving/attachment.ts

@@ -0,0 +1,55 @@
+import { Command } from '@commander-js/extra-typings';
+import type { GlobalOpts } from '../../../lib/client';
+import { requireClient } from '../../../lib/client';
+import { buildHelpText } from '../../../lib/help-text';
+import { outputResult } from '../../../lib/output';
+import { withSpinner } from '../../../lib/spinner';
+import { isInteractive } from '../../../lib/tty';
+
+export const getAttachmentCommand = new Command('attachment')
+  .description('Retrieve a single attachment from a received (inbound) email')
+  .argument('<emailId>', 'Received email UUID')
+  .argument('<attachmentId>', 'Attachment UUID')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context:
+        'The download_url is a signed URL that expires in ~1 hour. Download the file directly:\n  resend emails receiving attachment <emailId> <attachmentId> --json | jq -r .download_url | xargs curl -O',
+      output:
+        '  {"object":"attachment","id":"<uuid>","filename":"invoice.pdf","size":51200,"content_type":"application/pdf","content_disposition":"attachment","content_id":null,"download_url":"<signed-url>","expires_at":"<iso-date>"}',
+      errorCodes: ['auth_error', 'fetch_error'],
+      examples: [
+        'resend emails receiving attachment <email-id> <attachment-id>',
+        'resend emails receiving attachment <email-id> <attachment-id> --json',
+      ],
+    }),
+  )
+  .action(async (emailId, attachmentId, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    const resend = requireClient(globalOpts);
+
+    const data = await withSpinner(
+      {
+        loading: 'Fetching attachment...',
+        success: 'Attachment fetched',
+        fail: 'Failed to fetch attachment',
+      },
+      () =>
+        resend.emails.receiving.attachments.get({ emailId, id: attachmentId }),
+      'fetch_error',
+      globalOpts,
+    );
+
+    if (!globalOpts.json && isInteractive()) {
+      const d = data;
+      console.log(`\n${d.filename ?? '(unnamed)'}`);
+      console.log(`ID:           ${d.id}`);
+      console.log(`Content-Type: ${d.content_type}`);
+      console.log(`Size:         ${d.size} bytes`);
+      console.log(`Disposition:  ${d.content_disposition}`);
+      console.log(`Download URL: ${d.download_url}`);
+      console.log(`Expires:      ${d.expires_at}`);
+    } else {
+      outputResult(data, { json: globalOpts.json });
+    }
+  });

package/src/commands/emails/receiving/attachments.ts

@@ -0,0 +1,68 @@
+import { Command } from '@commander-js/extra-typings';
+import { runList } from '../../../lib/actions';
+import type { GlobalOpts } from '../../../lib/client';
+import { buildHelpText } from '../../../lib/help-text';
+import {
+  buildPaginationOpts,
+  parseLimitOpt,
+  printPaginationHint,
+} from '../../../lib/pagination';
+import { renderAttachmentsTable } from './utils';
+
+export const listAttachmentsCommand = new Command('attachments')
+  .description('List attachments on a received (inbound) email')
+  .argument('<emailId>', 'Received email UUID')
+  .option(
+    '--limit <n>',
+    'Maximum number of attachments to return (1-100)',
+    '10',
+  )
+  .option(
+    '--after <cursor>',
+    'Return attachments after this cursor (next page)',
+  )
+  .option(
+    '--before <cursor>',
+    'Return attachments before this cursor (previous page)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context:
+        'Each attachment has a download_url (signed, expires ~1 hour).\nUse the attachment sub-command to retrieve a single attachment with its download URL:\n  resend emails receiving attachment <emailId> <attachmentId>\n\ncontent_disposition: "inline" means the attachment is embedded in the HTML body (e.g. an image).\ncontent_disposition: "attachment" means it is a standalone file download.',
+      output:
+        '  {"object":"list","has_more":false,"data":[{"id":"<uuid>","filename":"invoice.pdf","size":51200,"content_type":"application/pdf","content_disposition":"attachment","content_id":null,"download_url":"<url>","expires_at":"<iso-date>"}]}',
+      errorCodes: ['auth_error', 'invalid_limit', 'list_error'],
+      examples: [
+        'resend emails receiving attachments <email-id>',
+        'resend emails receiving attachments <email-id> --json',
+        'resend emails receiving attachments <email-id> --limit 25 --json',
+      ],
+    }),
+  )
+  .action(async (emailId, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    const limit = parseLimitOpt(opts.limit, globalOpts);
+    const paginationOpts = buildPaginationOpts(limit, opts.after, opts.before);
+
+    await runList(
+      {
+        spinner: {
+          loading: 'Fetching attachments...',
+          success: 'Attachments fetched',
+          fail: 'Failed to list attachments',
+        },
+        sdkCall: (resend) =>
+          resend.emails.receiving.attachments.list({
+            emailId,
+            ...paginationOpts,
+          }),
+        onInteractive: (list) => {
+          console.log(renderAttachmentsTable(list.data));
+          printPaginationHint(list);
+        },
+      },
+      globalOpts,
+    );
+  });

package/src/commands/emails/receiving/get.ts

@@ -0,0 +1,58 @@
+import { Command } from '@commander-js/extra-typings';
+import { runGet } from '../../../lib/actions';
+import type { GlobalOpts } from '../../../lib/client';
+import { buildHelpText } from '../../../lib/help-text';
+
+export const getReceivingCommand = new Command('get')
+  .description(
+    'Retrieve a single received (inbound) email with full details including HTML, text, and headers',
+  )
+  .argument('<id>', 'Received email UUID')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context:
+        'The raw.download_url field is a signed URL (expires ~1 hour) containing the full RFC 2822\nMIME message. Pipe it to curl to save the original email:\n  resend emails receiving get <id> --json | jq -r .raw.download_url | xargs curl > email.eml\n\nAttachments are listed in the attachments array. Use the attachments sub-command to get\ndownload URLs:\n  resend emails receiving attachments <id>',
+      output:
+        '  {"object":"email","id":"<uuid>","to":["inbox@yourdomain.com"],"from":"sender@external.com","subject":"Hello","html":"<p>Hello!</p>","text":"Hello!","headers":{"x-mailer":"..."},"message_id":"<str>","bcc":[],"cc":[],"reply_to":[],"raw":{"download_url":"<url>","expires_at":"<iso-date>"},"attachments":[]}',
+      errorCodes: ['auth_error', 'fetch_error'],
+      examples: [
+        'resend emails receiving get <email-id>',
+        'resend emails receiving get <email-id> --json',
+      ],
+    }),
+  )
+  .action(async (id, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    await runGet(
+      {
+        spinner: {
+          loading: 'Fetching received email...',
+          success: 'Received email fetched',
+          fail: 'Failed to fetch received email',
+        },
+        sdkCall: (resend) => resend.emails.receiving.get(id),
+        onInteractive: (data) => {
+          console.log(`\nFrom:    ${data.from}`);
+          console.log(`To:      ${data.to.join(', ')}`);
+          console.log(`Subject: ${data.subject}`);
+          console.log(`Date:    ${data.created_at}`);
+          if (data.attachments.length > 0) {
+            console.log(`Files:   ${data.attachments.length} attachment(s)`);
+          }
+          if (data.text) {
+            const snippet =
+              data.text.length > 200
+                ? `${data.text.slice(0, 197)}...`
+                : data.text;
+            console.log(`\n${snippet}`);
+          } else if (data.html) {
+            console.log(
+              '\n(HTML body only — use --json to view or pipe to a browser)',
+            );
+          }
+        },
+      },
+      globalOpts,
+    );
+  });

package/src/commands/emails/receiving/index.ts

@@ -0,0 +1,28 @@
+import { Command } from '@commander-js/extra-typings';
+import { buildHelpText } from '../../../lib/help-text';
+import { getAttachmentCommand } from './attachment';
+import { listAttachmentsCommand } from './attachments';
+import { getReceivingCommand } from './get';
+import { listReceivingCommand } from './list';
+
+export const receivingCommand = new Command('receiving')
+  .description(
+    'Manage received (inbound) emails — requires domain receiving to be enabled',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context:
+        'Receiving must be enabled on the domain first:\n  resend domains update <id> --receiving enabled',
+      examples: [
+        'resend emails receiving list',
+        'resend emails receiving get <email-id>',
+        'resend emails receiving attachments <email-id>',
+        'resend emails receiving attachment <email-id> <attachment-id>',
+      ],
+    }),
+  )
+  .addCommand(listReceivingCommand, { isDefault: true })
+  .addCommand(getReceivingCommand)
+  .addCommand(listAttachmentsCommand)
+  .addCommand(getAttachmentCommand);

package/src/commands/emails/receiving/list.ts

@@ -0,0 +1,59 @@
+import { Command } from '@commander-js/extra-typings';
+import { runList } from '../../../lib/actions';
+import type { GlobalOpts } from '../../../lib/client';
+import { buildHelpText } from '../../../lib/help-text';
+import {
+  buildPaginationOpts,
+  parseLimitOpt,
+  printPaginationHint,
+} from '../../../lib/pagination';
+import { renderReceivingEmailsTable } from './utils';
+
+export const listReceivingCommand = new Command('list')
+  .alias('ls')
+  .description(
+    'List received (inbound) emails for domains with receiving enabled',
+  )
+  .option('--limit <n>', 'Maximum number of emails to return (1-100)', '10')
+  .option('--after <cursor>', 'Return emails after this cursor (next page)')
+  .option(
+    '--before <cursor>',
+    'Return emails before this cursor (previous page)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context:
+        'Receiving must be enabled on the domain first:\n  resend domains update <id> --receiving enabled\n\nPagination: use --after or --before with a received email ID as the cursor.\nOnly one of --after or --before may be used at a time.\nThe response includes has_more: true when additional pages exist.',
+      output:
+        '  {"object":"list","has_more":false,"data":[{"id":"<uuid>","to":["inbox@yourdomain.com"],"from":"sender@external.com","subject":"Hello","created_at":"<iso-date>","message_id":"<str>","bcc":null,"cc":null,"reply_to":null,"attachments":[]}]}',
+      errorCodes: ['auth_error', 'invalid_limit', 'list_error'],
+      examples: [
+        'resend emails receiving list',
+        'resend emails receiving list --limit 25 --json',
+        'resend emails receiving list --after <email-id> --json',
+      ],
+    }),
+  )
+  .action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    const limit = parseLimitOpt(opts.limit, globalOpts);
+    const paginationOpts = buildPaginationOpts(limit, opts.after, opts.before);
+
+    await runList(
+      {
+        spinner: {
+          loading: 'Fetching received emails...',
+          success: 'Received emails fetched',
+          fail: 'Failed to list received emails',
+        },
+        sdkCall: (resend) => resend.emails.receiving.list(paginationOpts),
+        onInteractive: (list) => {
+          console.log(renderReceivingEmailsTable(list.data));
+          printPaginationHint(list);
+        },
+      },
+      globalOpts,
+    );
+  });

package/src/commands/emails/receiving/utils.ts

@@ -0,0 +1,38 @@
+import type {
+  ListAttachmentsResponseSuccess,
+  ListReceivingEmail,
+} from 'resend';
+import { renderTable } from '../../../lib/table';
+
+export function renderReceivingEmailsTable(
+  emails: ListReceivingEmail[],
+): string {
+  const rows = emails.map((e) => {
+    const to = e.to.join(', ');
+    const toStr = to.length > 40 ? `${to.slice(0, 37)}...` : to;
+    const subject =
+      e.subject.length > 50 ? `${e.subject.slice(0, 47)}...` : e.subject;
+    return [e.from, toStr, subject, e.created_at, e.id];
+  });
+  return renderTable(
+    ['From', 'To', 'Subject', 'Created At', 'ID'],
+    rows,
+    '(no received emails)',
+  );
+}
+
+export function renderAttachmentsTable(
+  attachments: ListAttachmentsResponseSuccess['data'],
+): string {
+  const rows = attachments.map((a) => [
+    a.filename ?? '(unnamed)',
+    a.content_type,
+    String(a.size),
+    a.id,
+  ]);
+  return renderTable(
+    ['Filename', 'Content-Type', 'Size (bytes)', 'ID'],
+    rows,
+    '(no attachments)',
+  );
+}