API Client & Resend Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/actions.ts
• src/commands/doctor.ts
• src/commands/emails/send.ts
• skills/resend-cli/SKILL.md
• skills/resend-cli/references/error-codes.md
• skills/resend-cli/references/workflows.md
• src/commands/careers/apply.ts

The Resend CLI interacts with the Resend platform by wrapping the official Node.js SDK and performing direct HTTPS requests for specialized endpoints. It provides a standardized interface for sending emails, managing domains, and administering account resources like API keys and webhooks. The system prioritizes non-interactive execution for CI/CD pipelines while maintaining a guided experience for terminal users.

Sources: SKILL.md:1-15, src/lib/actions.ts:1-10

Authentication and Credential Resolution

The CLI resolves credentials through a priority-based hierarchy. It first checks for a literal API key passed via the --api-key flag, followed by the RESEND_API_KEY environment variable. If neither exists, it attempts to read from a local configuration file populated by the resend login command.

Credential Types

The integration supports two primary authentication methods:

• Static API Keys: Standard Resend API keys starting with the re_ prefix.
• OAuth Grants: Temporary access tokens refreshed automatically when expired, used primarily in authenticated browser-based logins.

Sources: src/commands/doctor.ts:98-125, skills/resend-cli/references/error-codes.md:10-16

The diagram shows the priority logic for resolving credentials before initializing the API client.
Sources: src/commands/doctor.ts:98-125, SKILL.md:46-52

API Action Runners

The CLI uses generic "Action Runners" located in src/lib/actions.ts to standardize how SDK calls are performed. These runners wrap SDK methods with UI enhancements like spinners and provide unified error handling.

Runner	Purpose	Key Parameters
runGet	Fetches a single resource	loading, sdkCall, onInteractive
runList	Fetches a collection	loading, sdkCall, onInteractive
runCreate	Submits new data	loading, sdkCall, errorCode
runDelete	Removes a resource	id, skipConfirm, sdkCall
runWrite	Updates existing data	loading, sdkCall, successMsg

Sources: src/lib/actions.ts:15-117

Execution Logic

Action runners execute the following steps:

1. Client Acquisition: Calls requireClient() to ensure a valid, authorized session exists.
2. Permission Check: Validates that the current key has sufficient permissions (e.g., sending_access vs full_access).
3. Request Decoration: Attaches a User-Agent and, if provided, an idempotency-key.
4. Spinner Management: Displays a terminal spinner during the network request.
5. Output Formatting: Sanitizes the response and prints either a human-readable summary (TTY) or raw JSON (non-TTY).

Sources: src/lib/actions.ts:15-35, src/commands/emails/send.ts:327-345

Specialized Integrations

Email Dispatching

The resend emails send command integrates with the SDK's emails.send method but adds CLI-specific features like file reading and React Email rendering.

This diagram illustrates the data preparation flow for email dispatching.
Sources: src/commands/emails/send.ts:250-320, skills/resend-cli/references/workflows.md:25-50

Career Applications

Unlike standard resource management, the career application feature uses a FormData multipart request rather than the standard JSON SDK methods. It maps job-specific UUID fields provided by the /careers/:id GET endpoint to a POST request containing a binary resume upload.

Sources: src/commands/careers/apply.ts:115-145, tests/commands/careers/apply.test.ts:72-100

Health Monitoring and Diagnostics

The doctor command serves as the primary diagnostic tool for the Resend integration. It performs a sequential check of the environment to identify communication failures.

Check	Function	Derived From
CLI Version	Compares local version to GitHub latest	fetchLatestVersion
API Key	Checks for presence and masks output	checkApiKeyPresence
Storage	Identifies if storage is secure or plaintext	getCredentialBackend
API Validation	Tests key against /domains endpoint	resend.domains.list()

Sources: src/commands/doctor.ts:40-200

Diagnostic Flow

When doctor runs, it validates network reachability. A network timeout or application_error results in a warn status, whereas a restricted_api_key error indicates a valid key that lacks permission to list domains.

Sources: src/commands/doctor.ts:140-165, tests/commands/doctor.test.ts:180-205

Error Mapping and Resilience

The CLI maps Resend API errors to internal error codes to provide actionable advice in the terminal.

• Transient Errors: The CLI identifies OAUTH_NETWORK_ERROR_NAME and TIMEOUT_ERROR_NAME as transient. The runGet and runList actions allow for retries on these errors.
• Validation Errors: Failures like missing_body or react_email_build_error are caught locally before reaching the API.
• Permissions: If a sending_access key attempts a management operation, the client blocks the request with insufficient_permissions.

Sources: src/lib/actions.ts:28, src/commands/doctor.ts:25-30, skills/resend-cli/references/error-codes.md:20-50

The API Client & Resend Integration provides a robust bridge between the user's local environment and the Resend API, combining strict credential resolution with resilient action runners to ensure reliable email operations and resource management.

Sources: SKILL.md:20-40, src/lib/actions.ts:1-10