# Gamopanda Email

The **Gamopanda Email** module manages email domain verification, DKIM/SPF authentication records, custom sender email addresses, and reply-to settings for transactional email delivery. Accounts can send emails via default shared Gamopanda domains or configure custom verified sending domains.

---

## How it works

1. **Choose domain mode**:
   - **Shared domain** (`useGamopandaDomain: true`) — send emails immediately using Gamopanda's pre-verified sending infrastructure.
   - **Custom domain** (`useGamopandaDomain: false`) — provide your custom domain (e.g. `example.com`), MAIL FROM subdomain (e.g. `mail.example.com`), and custom sender email address.
2. **Configure DNS authentication** — for custom domains, Gamopanda generates required DKIM, SPF, and MAIL FROM DNS records in `dnsRecords`. Add these records to your domain's DNS provider.
3. **Verify DNS setup** — trigger the **Verify DNS** action (`verify_dns`) to test records. Once validated, status flags (`isDomainVerified`, `isDkimVerified`, `isMailFromVerified`, `isVerified`) update to `true`.
4. **Attach to notification rules** — select this integration (`integrationId`) in [Notification](/notification) rules with `integrationProvider: gamopanda_email`.

---

## Fields

### Basic information

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | string | ✅ | — | The name of the Gamopanda Email integration record |
| `description` | string | ❌ | — | A brief description of the integration setup |
| `useGamopandaDomain` | boolean | ✅ | `true` | When `true`, uses Gamopanda's default shared domain for email delivery |
| `replyToEmailAddress` | string | ✅ | — | The email address set in the `Reply-To` header of outgoing emails |
| `status` | enum | ✅ | `draft` | Status of the integration: `draft` · `live` · `paused` |

### Custom domain configuration

*(Required when `useGamopandaDomain` is `false`)*

| Field | Type | Required | Description |
|---|---|---|---|
| `domain` | string | Conditionally | The custom sending domain (e.g., `example.com`). Non-editable after creation. |
| `mailFrom` | string | Conditionally | Custom MAIL FROM subdomain (e.g., `mail.example.com` or `bounces.example.com`). Non-editable after creation. |
| `senderEmailAddress` | string | Conditionally | Custom sender address (e.g., `no-reply@example.com`) displayed in the `From` header |

### Domain verification status (Read-only)

| Field | Type | Description |
|---|---|---|
| `isVerified` | boolean | Overall verification status indicator (returns `true` when all DNS checks pass) |
| `isDomainVerified` | boolean | Status of domain ownership verification |
| `isDkimVerified` | boolean | Status of DKIM DNS record verification |
| `isMailFromVerified` | boolean | Status of custom MAIL FROM subdomain verification |
| `dnsRecords` | JSON array | List of DNS records (CNAME, TXT, MX) required for domain authentication |

---

## Actions & verification

### Verify DNS Action (`verify_dns`)

Trigger the **Verify DNS** action to check if your DNS provider has successfully published the required DKIM, SPF, and MAIL FROM records. 

- **Eligibility**: Available for custom domains (`useGamopandaDomain: false`) when `isVerified` is `false`.

---

## Real-world examples

**📧 Custom Domain Setup Example**

```json
{
  "name": "Corporate Custom Email Gateway",
  "description": "Custom sending domain configuration for example.com",
  "useGamopandaDomain": false,
  "domain": "example.com",
  "mailFrom": "mail.example.com",
  "senderEmailAddress": "no-reply@example.com",
  "replyToEmailAddress": "support@example.com",
  "status": "live"
}
```

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | CREATE · GET · LIST · UPDATE · DELETE | Full management access |
| End user | *(none)* | No access |
| Guest user | *(none)* | No access |

---

## Related resources

| Resource | Description |
|---|---|
| [Email Template](/email-template) | Custom HTML templates linked to email notifications |
| [Notification](/notification) | Active notification rules targeting Gamopanda Email integration |
| [Notification Log](/notification-log) | Read-only delivery logs recording execution history |

---

## API reference

See the [API Reference](/api/gamopanda-email) for full schemas and interactive examples for:

- `GET /schema/gamopanda_email/record` — list Gamopanda Email records
- `POST /schema/gamopanda_email/record` — create a Gamopanda Email record
- `GET /schema/gamopanda_email/record/{id}` — get a Gamopanda Email record by ID
- `PATCH /schema/gamopanda_email/record/{id}` — update a Gamopanda Email record
- `DELETE /schema/gamopanda_email/record/{id}` — delete a Gamopanda Email record
- `POST /schema/gamopanda_email/record/{id}/action/verify_dns` — trigger DNS verification for custom domains