Pulumi Namecheap Provider

A Pulumi provider for managing Namecheap resources, dynamically bridged from the Terraform Namecheap Provider.

Introduction

This package provides a Pulumi provider that enables you to manage your Namecheap domain records and DNS configuration using TypeScript, JavaScript, Python, Go, or C#. The provider is automatically generated from the Terraform Namecheap provider, giving you access to all its functionality within the Pulumi ecosystem.

Features

• Domain Record Management: Create and manage DNS records (A, AAAA, CNAME, MX, TXT, etc.) for your Namecheap domains
• Multiple Record Types: Support for A, AAAA, ALIAS, CAA, CNAME, MX, MXE, NS, TXT, URL, URL301, and FRAME records
• Email Configuration: Configure email services with support for NONE, MXE, MX, FWD, OX, and GMAIL
• Sandbox Support: Test your configurations in Namecheap's sandbox environment
• TypeScript Support: Full type safety with comprehensive TypeScript definitions

Installation

npm

npm install pulumi-namecheap

yarn

yarn add pulumi-namecheap

pnpm

pnpm add pulumi-namecheap

bun

bun add pulumi-namecheap

Configuration

Before using the provider, you need to configure authentication with your Namecheap API credentials.

Required Configuration

• API Key: Your Namecheap API key
• API User: Your Namecheap API username
• Username: Your Namecheap account username
• Client IP: The IP address from which you're making API calls (must be whitelisted in Namecheap)

Optional Configuration

• Use Sandbox: Set to true to use Namecheap's sandbox environment for testing

Setting Configuration

You can configure the provider in several ways:

1. Using Pulumi Config

pulumi config set namecheap:apiKey your-api-key
pulumi config set namecheap:apiUser your-api-user
pulumi config set namecheap:userName your-username
pulumi config set namecheap:clientIp your-client-ip
pulumi config set namecheap:useSandbox false  # optional

2. Using Environment Variables

export NAMECHEAP_API_KEY="your-api-key"
export NAMECHEAP_API_USER="your-api-user"
export NAMECHEAP_USER_NAME="your-username"
export NAMECHEAP_CLIENT_IP="your-client-ip"
export NAMECHEAP_USE_SANDBOX="false"  # optional

3. Provider Constructor

import * as namecheap from 'pulumi-namecheap'

const provider = new namecheap.Provider('namecheap-provider', {
  apiKey: 'your-api-key',
  apiUser: 'your-api-user',
  userName: 'your-username',
  clientIp: 'your-client-ip',
  useSandbox: false, // optional
})

Usage

Basic Domain Records Management

import * as namecheap from 'pulumi-namecheap'

// Create DNS records for your domain
const records = new namecheap.DomainRecords('my-domain-records', {
  domain: 'example.com',
  mode: 'OVERWRITE', // MERGE (default) or OVERWRITE
  records: [
    {
      hostname: '@',
      type: 'A',
      address: '192.168.1.100',
      ttl: 300,
    },
    {
      hostname: 'www',
      type: 'CNAME',
      address: 'example.com',
      ttl: 300,
    },
    {
      hostname: '@',
      type: 'MX',
      address: 'mail.example.com',
      mxPref: 10,
      ttl: 300,
    },
    {
      hostname: '@',
      type: 'TXT',
      address: 'v=spf1 include:_spf.google.com ~all',
      ttl: 300,
    },
  ],
})

Advanced Configuration with Email Setup

import * as namecheap from 'pulumi-namecheap'

const domainRecords = new namecheap.DomainRecords('example-domain', {
  domain: 'example.com',
  emailType: 'GMAIL', // Configure Gmail for email
  mode: 'MERGE',
  records: [
    // A record for root domain
    {
      hostname: '@',
      type: 'A',
      address: '203.0.113.1',
      ttl: 1800,
    },
    // CNAME for www subdomain
    {
      hostname: 'www',
      type: 'CNAME',
      address: 'example.com',
      ttl: 1800,
    },
    // Multiple MX records for redundancy
    {
      hostname: '@',
      type: 'MX',
      address: 'aspmx.l.google.com',
      mxPref: 1,
      ttl: 3600,
    },
    {
      hostname: '@',
      type: 'MX',
      address: 'alt1.aspmx.l.google.com',
      mxPref: 5,
      ttl: 3600,
    },
    // TXT record for domain verification
    {
      hostname: '@',
      type: 'TXT',
      address: 'google-site-verification=your-verification-string',
      ttl: 3600,
    },
  ],
})

// Export the domain records ID
export const domainRecordsId = domainRecords.domainRecordsId

Using Custom Provider Instance

import * as namecheap from 'pulumi-namecheap'

// Create a custom provider for sandbox testing
const sandboxProvider = new namecheap.Provider('sandbox-provider', {
  apiKey: 'your-sandbox-api-key',
  apiUser: 'your-api-user',
  userName: 'your-username',
  clientIp: 'your-client-ip',
  useSandbox: true,
})

// Use the custom provider
const testRecords = new namecheap.DomainRecords(
  'test-records',
  {
    domain: 'test-domain.com',
    records: [
      {
        hostname: 'test',
        type: 'A',
        address: '192.168.1.1',
        ttl: 300,
      },
    ],
  },
  { provider: sandboxProvider },
)

Resources

DomainRecords

Manages DNS records for a Namecheap domain.

Properties

• domain (Required): The domain name to manage records for
• records (Optional): Array of DNS record configurations
• emailType (Optional): Email service configuration (NONE, MXE, MX, FWD, OX, GMAIL)
• mode (Optional): How to handle existing records (MERGE or OVERWRITE)
• nameservers (Optional): Custom nameservers for the domain

Record Types

Each record in the records array supports:

• hostname (Required): The subdomain/hostname for the record
• type (Required): Record type (A, AAAA, ALIAS, CAA, CNAME, MX, MXE, NS, TXT, URL, URL301, FRAME)
• address (Required): The target IP address or hostname
• ttl (Optional): Time to live (60-60000 seconds)
• mxPref (Optional): MX record priority (required for MX records)

API Reference

For detailed API documentation, see the generated documentation in your IDE or visit the Pulumi Registry.

Authentication Setup

Getting Your API Credentials

1. Log in to Namecheap: Go to your Namecheap account dashboard
2. Enable API Access: Navigate to Profile → Tools → Namecheap API Access
3. Generate API Key: Create a new API key for your application
4. Whitelist IP: Add your client IP address to the whitelist
5. Note Your Details: Save your API key, username, and API user name

Testing in Sandbox

Namecheap provides a sandbox environment for testing. Set useSandbox: true in your provider configuration to use the sandbox API endpoints.

Examples

You can find more examples in the examples directory or check out these common use cases:

• Basic A/CNAME Records
• Email Configuration
• Multi-domain Management
• Sandbox Testing

Support

This provider is a derived work of the Terraform Provider distributed under MPL 2.0.

If you encounter a bug or missing feature, please consult the source terraform-provider-namecheap repo.

For Pulumi-specific issues, please open an issue in the pulumi-any-terraform repository.

License

This package is distributed under the MIT License. The underlying Terraform provider is distributed under MPL 2.0.