# Porkbun API v3 — Email

> Email forwarding (forward an address at the domain to another mailbox) and email hosting mailbox passwords

Part of the Porkbun API v3.58. Topic index: https://porkbun.com/llms · Full reference: https://porkbun.com/llms-full.txt · Overview: https://porkbun.com/llms.txt · OpenAPI spec: https://porkbun.com/api/json/v3/spec

**Auth:** send `X-API-Key` / `X-Secret-API-Key` headers (preferred) or `apikey` / `secretapikey` in the JSON body. Create keys at https://porkbun.com/account/api

---

# Endpoints

## POST /api/json/v3/email/getForwards/{domain}

**List email forwards**

The email forwards on a domain: each `address` at the domain and the `forwardTo` mailbox it is delivered to (an address can forward to several). `limits` gives how many the domain has and may have; `dnsConfigured` says whether the apex MX records in the Porkbun zone point at Porkbun forwarding (if the domain uses other nameservers, those decide). Supports GET with header auth.

| Parameter | In | Required | Description |
|---|---|---|---|
| `domain` | path | yes |  |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/email/getForwards/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_..."}'
```

Response fields:

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `domain` | string |  |
| `forwards` | object[] |  |
| `limits` | object | Forwards the domain has (`used`, including any Porkbun manages itself) and may have (`max`) |
| `dnsConfigured` | boolean |  |

## GET /api/json/v3/email/getForwards/{domain}

**List email forwards**

The email forwards on a domain: each `address` at the domain and the `forwardTo` mailbox it is delivered to (an address can forward to several). `limits` gives how many the domain has and may have; `dnsConfigured` says whether the apex MX records in the Porkbun zone point at Porkbun forwarding (if the domain uses other nameservers, those decide). Supports GET with header auth.

| Parameter | In | Required | Description |
|---|---|---|---|
| `domain` | path | yes |  |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/email/getForwards/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_..."}'
```

Response fields:

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `domain` | string |  |
| `forwards` | object[] |  |
| `limits` | object | Forwards the domain has (`used`, including any Porkbun manages itself) and may have (`max`) |
| `dnsConfigured` | boolean |  |

## POST /api/json/v3/email/addForward/{domain}

**Add an email forward**

Forward an address at the domain to another mailbox. Free, up to the domain's limit (20 by default). Forwarding needs Porkbun's MX records and SPF include at the zone apex, and this sets them up. **When that would delete other apex MX records (another mail service) or rewrite an existing SPF record, the call is refused with `DNS_CHANGE_CONFIRMATION_REQUIRED` and `dnsChanges` describing exactly what would change; tell the user, then resend with `confirmDnsChanges: true`.** `dryRun: true` previews it, including whether confirmation is needed. Catch-all/wildcard forwards are not supported. An address cannot be both a forward and an email hosting mailbox.

| Parameter | In | Required | Description |
|---|---|---|---|
| `domain` | path | yes |  |

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | The address at the domain to forward: the part before the @ (`info`) or the whole address (`info@example.com`) |
| `forwardTo` | string | yes | The mailbox to deliver to |
| `confirmDnsChanges` | boolean | no | Agree to the DNS changes a DNS_CHANGE_CONFIRMATION_REQUIRED response described |
| `dryRun` | boolean | no |  |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/email/addForward/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","address":"info","forwardTo":"me@example.net"}'
```

Response fields:

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `domain` | string |  |
| `address` | string |  |
| `forwardTo` | string |  |
| `dnsChanges` | object | What setting up forwarding does to the zone apex |
| `limits` | object | Forwards the domain has (`used`, including any Porkbun manages itself) and may have (`max`) |

## POST /api/json/v3/email/deleteForward/{domain}

**Delete an email forward**

Delete one forward, named by its `address` and `forwardTo` (an address can forward to several). When it was the domain's last forward and there are no email hosting mailboxes, Porkbun's forwarding MX and SPF records are removed too (`dnsRecordsRemoved: true`).

| Parameter | In | Required | Description |
|---|---|---|---|
| `domain` | path | yes |  |

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes |  |
| `forwardTo` | string | yes |  |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/email/deleteForward/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","address":"info","forwardTo":"me@example.net"}'
```

Response fields:

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `address` | string |  |
| `forwardTo` | string |  |
| `dnsRecordsRemoved` | boolean |  |

## POST /api/json/v3/email/setPassword

**Set email hosting password**

Set the password for an email hosting account associated with a domain managed by your API key.

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `emailAddress` | string | yes | The full email address (e.g. user@example.com) |
| `password` | string | yes | The new password. Must pass Porkbun password validation rules. |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/email/setPassword \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","emailAddress":"user@example.com"}'
```

Response fields (BasicResponse):

| Field | Type | Description |
|---|---|---|
| `warnings` | string[] | Advisory, and present only when there is something to say. It never means the call failed. The one to handle: a DNS write is accepted and stored even when the domain is NOT delegated to our nameservers -- we keep the zone ready in case the delegation comes back -- so the write changed nothing that resolves, and this field says so. Show these to the user as written. |
| `status` | string |  |
| `message` | string | Human-readable message. Present on ERROR, sometimes on SUCCESS. |
| `code` | string | Machine-readable error code. Present when status is ERROR. |

---

## More

- Guides (how-tos): https://porkbun.com/llms/guides
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Short overview: https://porkbun.com/llms.txt
- Official MCP server: https://porkbun.com/mcp (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api