# Dominios

Endpoints para la gestion completa de dominios de envio: registro, verificacion DNS, consulta de estado y configuracion de perfil de remitente.

**Base URL:** `https://api.reallyquickemails.com`

***

## Autenticacion

Todos los endpoints de dominios requieren autenticacion mediante Secret Key:

| Header          | Tipo   | Requerido | Descripcion                       |
| --------------- | ------ | --------- | --------------------------------- |
| `Authorization` | string | Si        | `Bearer sk_proj_...`              |
| `Content-Type`  | string | Si\*      | `application/json` (en POST/PUT). |

***

## POST /domains/register

Registra un nuevo dominio de envio. Crea la identidad en AWS SES, genera los registros DNS necesarios y almacena la configuracion en la base de datos.

### Request Body

| Campo          | Tipo   | Requerido | Descripcion                                                    |
| -------------- | ------ | --------- | -------------------------------------------------------------- |
| `domain`       | string | Si        | Dominio a registrar (ej. `mitienda.com`).                      |
| `sender_name`  | string | Si        | Nombre del remitente (ej. `Mi Tienda`).                        |
| `sender_email` | string | Si        | Direccion de correo del remitente (ej. `ventas@mitienda.com`). |
| `external_key` | string | No        | Clave externa para integraciones de terceros.                  |

### Ejemplo

```bash
curl -X POST https://api.reallyquickemails.com/domains/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -d '{
    "domain": "mitienda.com",
    "sender_name": "Mi Tienda",
    "sender_email": "ventas@mitienda.com"
  }'
```

### Respuesta exitosa (201 Created)

```json
{
  "success": true,
  "domain": "mitienda.com",
  "dns_records": [
    {
      "type": "TXT",
      "name": "_amazonses",
      "value": "abcdef1234567890abcdef1234567890",
      "purpose": "ses_verification"
    },
    {
      "type": "CNAME",
      "name": "abc123._domainkey",
      "value": "abc123.dkim.amazonses.com",
      "purpose": "dkim"
    },
    {
      "type": "CNAME",
      "name": "def456._domainkey",
      "value": "def456.dkim.amazonses.com",
      "purpose": "dkim"
    },
    {
      "type": "CNAME",
      "name": "ghi789._domainkey",
      "value": "ghi789.dkim.amazonses.com",
      "purpose": "dkim"
    },
    {
      "type": "TXT",
      "name": "@",
      "value": "v=spf1 include:amazonses.com ~all",
      "purpose": "spf"
    },
    {
      "type": "TXT",
      "name": "_dmarc",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@mitienda.com",
      "purpose": "dmarc"
    },
    {
      "type": "CNAME",
      "name": "bounce",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "purpose": "return_path"
    }
  ],
  "message": "Domain registered. Configure the DNS records shown above, then call POST /domains/mitienda.com/verify to validate."
}
```

### Registros DNS generados

| #   | Tipo  | Nombre                 | Proposito        | Notas                                                       |
| --- | ----- | ---------------------- | ---------------- | ----------------------------------------------------------- |
| 1   | TXT   | `_amazonses`           | Verificacion SES | Valor generado por AWS SES                                  |
| 2-4 | CNAME | `{token}._domainkey`   | DKIM             | 3 registros, tokens generados por AWS SES                   |
| 5   | TXT   | `@` (raiz del dominio) | SPF              | `v=spf1 include:amazonses.com ~all`                         |
| 6   | TXT   | `_dmarc`               | DMARC            | `v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@{domain}` |
| 7   | CNAME | `bounce`               | Return-Path      | Apunta a `feedback-smtp.us-east-1.amazonses.com`            |

> **Nota:** Los nombres de los registros son relativos al dominio. Por ejemplo, si tu dominio es `mitienda.com`, el registro `_amazonses` se configura como `_amazonses.mitienda.com` en tu proveedor DNS. Algunos proveedores agregan el dominio automaticamente, por lo que solo necesitas ingresar `_amazonses`.

### Codigos de Error

| Codigo | Descripcion                                                 |
| ------ | ----------------------------------------------------------- |
| `400`  | Campos requeridos faltantes o dominio con formato invalido. |
| `401`  | API Key invalida.                                           |
| `409`  | El dominio ya esta registrado en este proyecto.             |
| `500`  | Error interno al comunicarse con AWS SES.                   |

***

## GET /domains/:domain/dns-records

Retorna los registros DNS almacenados para un dominio. No realiza consultas a AWS -- devuelve los datos guardados en la base de datos al momento del registro.

### Parametros de Ruta

| Parametro | Tipo   | Descripcion                              |
| --------- | ------ | ---------------------------------------- |
| `domain`  | string | Dominio registrado (ej. `mitienda.com`). |

### Ejemplo

```bash
curl -X GET https://api.reallyquickemails.com/domains/mitienda.com/dns-records \
  -H "Authorization: Bearer sk_proj_tu_secret_key"
```

### Respuesta exitosa (200 OK)

```json
{
  "success": true,
  "domain": "mitienda.com",
  "dns_records": [
    {
      "type": "TXT",
      "name": "_amazonses",
      "value": "abcdef1234567890abcdef1234567890",
      "purpose": "ses_verification",
      "verified": false
    },
    {
      "type": "CNAME",
      "name": "abc123._domainkey",
      "value": "abc123.dkim.amazonses.com",
      "purpose": "dkim",
      "verified": false
    },
    {
      "type": "CNAME",
      "name": "def456._domainkey",
      "value": "def456.dkim.amazonses.com",
      "purpose": "dkim",
      "verified": false
    },
    {
      "type": "CNAME",
      "name": "ghi789._domainkey",
      "value": "ghi789.dkim.amazonses.com",
      "purpose": "dkim",
      "verified": false
    },
    {
      "type": "TXT",
      "name": "@",
      "value": "v=spf1 include:amazonses.com ~all",
      "purpose": "spf",
      "verified": null
    },
    {
      "type": "TXT",
      "name": "_dmarc",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@mitienda.com",
      "purpose": "dmarc",
      "verified": null
    },
    {
      "type": "CNAME",
      "name": "bounce",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "purpose": "return_path",
      "verified": null
    }
  ]
}
```

### Codigos de Error

| Codigo | Descripcion                           |
| ------ | ------------------------------------- |
| `401`  | API Key invalida.                     |
| `404`  | Dominio no encontrado en el proyecto. |

***

## POST /domains/:domain/verify

Verifica el estado DNS del dominio consultando directamente a AWS SES. Comprueba tres aspectos:

1. **Verificacion de dominio** -- El registro TXT de verificacion SES esta configurado.
2. **DKIM** -- Los 3 registros CNAME de DKIM estan configurados y propagados.
3. **MAIL FROM** -- El registro CNAME de Return-Path (`bounce`) esta configurado.

Actualiza el estado en la base de datos y retorna si el dominio puede enviar correos.

### Parametros de Ruta

| Parametro | Tipo   | Descripcion                              |
| --------- | ------ | ---------------------------------------- |
| `domain`  | string | Dominio registrado (ej. `mitienda.com`). |

### Ejemplo

```bash
curl -X POST https://api.reallyquickemails.com/domains/mitienda.com/verify \
  -H "Authorization: Bearer sk_proj_tu_secret_key"
```

### Respuesta exitosa (200 OK)

```json
{
  "success": true,
  "domain": "mitienda.com",
  "verification": {
    "domain_verified": true,
    "dkim_verified": true,
    "mail_from_verified": false
  },
  "can_send": true,
  "message": "Domain and DKIM verified. MAIL FROM pending -- emails will send but Return-Path may not match."
}
```

El campo `can_send` es `true` cuando tanto `domain_verified` como `dkim_verified` son `true`. La verificacion de `mail_from` no es obligatoria para enviar pero se recomienda para mejorar la entregabilidad.

### Codigos de Error

| Codigo | Descripcion                           |
| ------ | ------------------------------------- |
| `401`  | API Key invalida.                     |
| `404`  | Dominio no encontrado en el proyecto. |
| `502`  | Error al comunicarse con AWS SES.     |

***

## GET /domains/:domain/status

Retorna el estado de verificacion almacenado en la base de datos. No consulta AWS SES, por lo que es un endpoint rapido ideal para polling desde la interfaz.

### Parametros de Ruta

| Parametro | Tipo   | Descripcion                              |
| --------- | ------ | ---------------------------------------- |
| `domain`  | string | Dominio registrado (ej. `mitienda.com`). |

### Ejemplo

```bash
curl -X GET https://api.reallyquickemails.com/domains/mitienda.com/status \
  -H "Authorization: Bearer sk_proj_tu_secret_key"
```

### Respuesta exitosa (200 OK)

```json
{
  "success": true,
  "domain": "mitienda.com",
  "status": "verified",
  "can_send": true,
  "dns_records_summary": {
    "total": 7,
    "verified": 5,
    "pending": 2,
    "failed": 0
  },
  "sender": {
    "sender_name": "Mi Tienda",
    "sender_email": "ventas@mitienda.com"
  },
  "last_verified_at": "2025-03-10T18:45:00.000Z"
}
```

### Codigos de Error

| Codigo | Descripcion                           |
| ------ | ------------------------------------- |
| `401`  | API Key invalida.                     |
| `404`  | Dominio no encontrado en el proyecto. |

***

## GET /domains

Busca un dominio especifico por nombre. Retorna informacion basica del dominio y su perfil de remitente.

### Query Parameters

| Parametro | Tipo   | Requerido | Descripcion                  |
| --------- | ------ | --------- | ---------------------------- |
| `domain`  | string | Si        | Nombre del dominio a buscar. |

### Ejemplo

```bash
curl -X GET "https://api.reallyquickemails.com/domains?domain=mitienda.com" \
  -H "Authorization: Bearer sk_proj_tu_secret_key"
```

### Respuesta exitosa (200 OK)

```json
{
  "success": true,
  "domain": {
    "domain": "mitienda.com",
    "status": "verified",
    "can_send": true,
    "created_at": "2025-03-01T12:00:00.000Z",
    "sender": {
      "sender_name": "Mi Tienda",
      "sender_email": "ventas@mitienda.com",
      "reply_email": "soporte@mitienda.com"
    }
  }
}
```

### Codigos de Error

| Codigo | Descripcion                           |
| ------ | ------------------------------------- |
| `400`  | Parametro `domain` no proporcionado.  |
| `401`  | API Key invalida.                     |
| `404`  | Dominio no encontrado en el proyecto. |

***

## DELETE /domains/:domain

Elimina un dominio. El dominio se elimina inmediatamente de AWS SES y se marca como eliminado (soft-delete) en la base de datos. El perfil de remitente asociado se desactiva.

### Parametros de Ruta

| Parametro | Tipo   | Descripcion                              |
| --------- | ------ | ---------------------------------------- |
| `domain`  | string | Dominio a eliminar (ej. `mitienda.com`). |

### Ejemplo

```bash
curl -X DELETE https://api.reallyquickemails.com/domains/mitienda.com \
  -H "Authorization: Bearer sk_proj_tu_secret_key"
```

### Respuesta exitosa (200 OK)

```json
{
  "success": true,
  "domain": "mitienda.com",
  "message": "Domain and associated sender profile removed"
}
```

> **Advertencia:** Esta operacion es irreversible en AWS SES. Una vez eliminado, deberas volver a registrar el dominio y configurar los registros DNS nuevamente.

### Codigos de Error

| Codigo | Descripcion                           |
| ------ | ------------------------------------- |
| `401`  | API Key invalida.                     |
| `404`  | Dominio no encontrado en el proyecto. |

***

## PUT /domains/:domain/sender

Actualiza el perfil de remitente asociado a un dominio. Los campos `sender_name` y `sender_email` son obligatorios.

### Parametros de Ruta

| Parametro | Tipo   | Descripcion                            |
| --------- | ------ | -------------------------------------- |
| `domain`  | string | Dominio asociado (ej. `mitienda.com`). |

### Request Body

| Campo          | Tipo   | Requerido | Descripcion                                                      |
| -------------- | ------ | --------- | ---------------------------------------------------------------- |
| `sender_name`  | string | Si        | Nombre visible del remitente.                                    |
| `sender_email` | string | Si        | Direccion de correo del remitente. Debe terminar en `@{domain}`. |
| `reply_email`  | string | No        | Direccion de correo para respuestas (Reply-To).                  |

### Ejemplo

```bash
curl -X PUT https://api.reallyquickemails.com/domains/mitienda.com/sender \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -d '{
    "sender_name": "Equipo Mi Tienda",
    "sender_email": "ventas@mitienda.com",
    "reply_email": "soporte@mitienda.com"
  }'
```

### Respuesta exitosa (200 OK)

```json
{
  "success": true,
  "domain": "mitienda.com",
  "sender": {
    "sender_name": "Equipo Mi Tienda",
    "sender_email": "ventas@mitienda.com",
    "reply_email": "soporte@mitienda.com"
  }
}
```

### Codigos de Error

| Codigo | Descripcion                                                                        |
| ------ | ---------------------------------------------------------------------------------- |
| `400`  | Falta `sender_name` o `sender_email`, o `sender_email` no coincide con el dominio. |
| `401`  | API Key invalida.                                                                  |
| `404`  | Dominio no encontrado en el proyecto.                                              |

***

## Verificacion de Email (Magic Link)

Alternativa a la verificacion de dominio completo. Permite verificar un email individual como remitente sin necesidad de configurar DNS. AWS SES envia un email de verificacion al remitente — al hacer clic en el enlace, el email queda verificado para enviar.

> **Nota:** La verificacion por email es mas rapida pero no incluye DKIM/SPF. Para mejor deliverability, se recomienda verificar el dominio completo.

***

### POST /domains/verify-email

Inicia la verificacion de un email como remitente. AWS SES envia un enlace de verificacion al email proporcionado.

#### Request Body

| Campo          | Tipo   | Requerido | Descripcion                       |
| -------------- | ------ | --------- | --------------------------------- |
| `sender_email` | string | Si        | Email a verificar como remitente. |
| `sender_name`  | string | Si        | Nombre visible del remitente.     |
| `external_key` | string | No        | Clave externa para integraciones. |

#### Ejemplo

```bash
curl -X POST https://api.reallyquickemails.com/domains/verify-email \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_email": "ventas@gmail.com",
    "sender_name": "Mi Empresa"
  }'
```

#### Respuesta exitosa (201)

```json
{
  "success": true,
  "identity_id": "550e8400-e29b-41d4-a716-446655440000",
  "sender_email": "ventas@gmail.com",
  "verification_status": "pending",
  "sender_profile_id": "123e4567-e89b-12d3-a456-426614174000",
  "sender": {
    "from_name": "Mi Empresa",
    "from_email": "ventas@gmail.com",
    "email_verified": false,
    "domain_authenticated": false
  },
  "message": "Verification email sent. The sender must click the link in the email to verify."
}
```

El remitente recibira un email de AWS con un enlace. Al hacer clic, su email queda verificado.

#### Errores

| Codigo | Descripcion                                 |
| ------ | ------------------------------------------- |
| `400`  | `sender_email and sender_name are required` |
| `401`  | API Key invalida                            |
| `409`  | Email ya registrado en este proyecto        |

***

### GET /domains/verify-email/status

Consulta el estado de verificacion de un email. Verifica contra AWS SES en tiempo real.

#### Query Parameters

| Parametro | Tipo   | Requerido | Descripcion        |
| --------- | ------ | --------- | ------------------ |
| `email`   | string | Si        | Email a consultar. |

#### Ejemplo

```bash
curl "https://api.reallyquickemails.com/domains/verify-email/status?email=ventas@gmail.com" \
  -H "Authorization: Bearer sk_proj_tu_secret_key"
```

#### Respuesta exitosa (200)

```json
{
  "success": true,
  "identity_id": "550e8400-e29b-41d4-a716-446655440000",
  "sender_email": "ventas@gmail.com",
  "verification_status": "verified",
  "sender_profile": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "from_name": "Mi Empresa",
    "from_email": "ventas@gmail.com",
    "email_verified": true,
    "domain_authenticated": false
  },
  "can_send": true
}
```

#### Estados de verificacion

| Estado     | Descripcion                                                 |
| ---------- | ----------------------------------------------------------- |
| `pending`  | Email de verificacion enviado, esperando clic del remitente |
| `verified` | Remitente verificado, listo para enviar                     |
| `failed`   | Verificacion fallida                                        |

#### Errores

| Codigo | Descripcion                         |
| ------ | ----------------------------------- |
| `400`  | `email query parameter is required` |
| `401`  | API Key invalida                    |
| `404`  | Email no encontrado en el proyecto  |

***

### POST /domains/verify-email/resend

Reenvia el email de verificacion al remitente.

#### Request Body

| Campo          | Tipo   | Requerido | Descripcion            |
| -------------- | ------ | --------- | ---------------------- |
| `sender_email` | string | Si        | Email al que reenviar. |

#### Ejemplo

```bash
curl -X POST https://api.reallyquickemails.com/domains/verify-email/resend \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_email": "ventas@gmail.com"
  }'
```

#### Respuesta exitosa (200)

```json
{
  "success": true,
  "message": "Verification email resent",
  "sender_email": "ventas@gmail.com"
}
```

***

### DELETE /domains/verify-email

Elimina un email verificado como remitente.

#### Query Parameters

| Parametro | Tipo   | Requerido | Descripcion       |
| --------- | ------ | --------- | ----------------- |
| `email`   | string | Si        | Email a eliminar. |

#### Ejemplo

```bash
curl -X DELETE "https://api.reallyquickemails.com/domains/verify-email?email=ventas@gmail.com" \
  -H "Authorization: Bearer sk_proj_tu_secret_key"
```

#### Respuesta exitosa (200)

```json
{
  "success": true,
  "sender_email": "ventas@gmail.com",
  "message": "Email identity and associated sender profile removed"
}
```

#### Errores

| Codigo | Descripcion                         |
| ------ | ----------------------------------- |
| `400`  | `email query parameter is required` |
| `401`  | API Key invalida                    |
| `404`  | Email no encontrado en el proyecto  |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://reallyquickemails.gitbook.io/reallyquickemails-docs/referencia-api/domains.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.