# Descripción general para desarrolladores

> URL base, autenticación, ID de objeto, errores, paginación, límites de velocidad, SDK, webhooks y MCP. Las convenciones comunes a todas las integraciones con Emailit.

En esta página se reúnen las convenciones que necesitas conocer antes de escribir código para Emailit: dónde está la API, cómo se autentican las peticiones, cómo se identifican los objetos y cómo funcionan los errores, la paginación y los límites de velocidad. Cada sección enlaza con la referencia detallada.

## Formas de integración

| Interfaz | Endpoint | Para qué sirve |
| --- | --- | --- |
| API REST | `https://api.emailit.com/v2` | Enviar emails y gestionar todos los recursos desde el código. |
| SMTP relay | `smtp.emailit.com` | Aplicaciones, frameworks y CMS que ya usan SMTP. Consulta [Configuración SMTP](/es/docs/smtp/settings/). |
| Webhooks | Tu endpoint HTTPS | Eventos en tiempo real de entrega, de interacción y de recursos. |
| Servidor MCP | `https://api.emailit.com/mcp` | Permitir que asistentes de IA como Claude, ChatGPT y Cursor trabajen con tu espacio de trabajo. |
| OAuth 2.1 | `https://api.emailit.com/oauth/*` | Integraciones que actúan en nombre de usuarios de Emailit sin manejar sus claves de API. |

¿No sabes si usar la API o SMTP? Lee [API o SMTP](/es/docs/get-started/api-or-smtp/).

## URL base y control de versiones

Todos los endpoints REST están bajo una única URL base:

```text
https://api.emailit.com/v2
```

`v2` es la versión actual y la única documentada. La antigua API `v1` está obsoleta; consulta [Control de versiones](/es/docs/api-reference/versioning/).

## Autenticación

Envía una clave de API como token bearer en la cabecera `Authorization` de cada petición:

```bash
curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

- Las claves de API empiezan por `secret_`. Las claves antiguas sin el prefijo siguen funcionando.
- Cada clave pertenece a un espacio de trabajo y tiene un permiso: **Full Access** (`full`) puede llamar a todos los endpoints y **Sending Only** (`sending`) solo puede enviar y gestionar los envíos. Consulta [Claves de API](/es/docs/developers/api-keys/).
- Los tokens de acceso OAuth emitidos para [aplicaciones OAuth](/es/docs/developers/oauth-apps/) se aceptan en la misma cabecera.
- Si falta la clave, se devuelve `401` con `API key required`; una clave desconocida devuelve `401` con `Invalid API key`, y un espacio de trabajo suspendido devuelve `403` con `Workspace is suspended`.

No llames nunca a la API con tu clave desde un navegador o una app móvil. Mantenla en tu servidor. Más detalles: [Autenticación](/es/docs/api-reference/authentication/).

## ID y prefijos

Cada objeto tiene un ID de tipo cadena con un prefijo que indica el tipo, así que puedes saber de un vistazo a qué se refiere un ID.

| Objeto | Prefijo | Ejemplo |
| --- | --- | --- |
| Email | `em_` | `em_4K6oASS7KP9ztzWmSN9ndEu13HW` |
| Dominio de envío | `dom_` | `dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6` |
| Clave de API | `key_` | `key_4F2kN8sQwE1rT6yU3iO9pA7sD5f` |
| Lista de contactos | `aud_` | `aud_3zR8tY2uI6oP4aS1dF9gH7jK5lM` |
| Suscriptor | `sub_` | `sub_4K6oASS7KP9ztzWnqS4svxApJzO` |
| Contacto | `con_` | `con_4A9sD2fG6hJ1kL8zX3cV7bN5mQw` |
| Plantilla | `tem_` | `tem_3wE8rT1yU5iO9pA2sD6fG4hJ7kL` |
| Dirección bloqueada | `sup_` | `sup_4K6oASS7KP9ztzWol5ElicOeKFE` |
| Webhook | `wh_` | `wh_3mN7bV2cX6zL9kJ4hG1fD8sA5pO` |
| Petición de webhook | `whr_` | `whr_4K6oASS7KP9ztzWpVUIec9Jneax` |
| Evento | `evt_` | `evt_4K6oASS7KP9ztzWpqId2iIptac5` |
| Campaña | `cmp_` | `cmp_4B1nM5qW9eR3tY7uI2oP6aS8dF4` |
| Formulario | `frm_` | `frm_4C3vB7nM1qW5eR9tY2uI6oP8aS4` |
| Respuesta de formulario | `fsub_` | `fsub_4K6oASS7KP9ztzWqvxLV3IsFRs8` |
| Automatización | `aut_` | `aut_4D5fG9hJ3kL7zX1cV6bN2mQ8wE4` |
| Ejecución de automatización | `aur_` | `aur_4K6oASS7KP9ztzWrWOjGgqompRo` |
| Verificación de email | `ev_` | `ev_4E7gH1jK5lZ9xC3vB8nM2qW6eR4` |
| Lista de direcciones (verificación masiva) | `evl_` | `evl_4F9hJ3kL7zX1cV5bN9mQ2wE6rT8` |
| Informe DMARC | `dmr_` | `dmr_4K6oASS7KP9ztzWsW7e5qkOYHO6` |

Los dominios creados antes del cambio a los ID `dom_` pueden tener todavía ID `sd_` o `sed_`.

Algunos endpoints también aceptan un identificador legible en lugar del ID: un nombre para las claves de API, los dominios, los webhooks, las campañas y las listas de contactos, y una dirección de email para los contactos y las direcciones bloqueadas. Los emails, las plantillas y los eventos solo se buscan por ID.

## Peticiones y respuestas

- **JSON de entrada, JSON de salida.** Envía los cuerpos de las peticiones en JSON con `Content-Type: application/json`. Un JSON mal formado devuelve `400` con `Invalid JSON in request body`. El cuerpo de una petición puede ocupar hasta 50 MB, y el mensaje MIME final de un email, hasta 40 MB.
- **Errores.** La mayoría de los errores devuelven `{"statusCode", "error", "message"}`. Los errores de validación añaden un array `details` y los errores de envío devuelven `validation_errors`. Las funciones que dependen del plan devuelven `403` con `"error": "plan_required"`. Consulta [Errores](/es/docs/api-reference/errors/).
- **Paginación.** Los endpoints de listado reciben `page` y `limit` (de 1 a 100) y devuelven `data`, `next_page_url` y `previous_page_url`. Las plantillas y las automatizaciones usan `page` y `per_page`. Consulta [Paginación](/es/docs/api-reference/pagination/).
- **Filtrado y ordenación.** Filtra con `field.condition=value`, combina filtros con `match=all` o `match=or` y ordena con `order` y `direction`. Por ejemplo, `GET /v2/emails?status.exact=bounced&order=created_at&direction=desc`. Consulta [Filtrado y ordenación](/es/docs/api-reference/filtering/).
- **Idempotencia.** Envía una cabecera `Idempotency-Key` en `POST /emails` y `POST /emails/:id/forward` para que los reintentos sean seguros. Emailit repite la primera respuesta durante 24 horas. Consulta [Idempotencia](/es/docs/api-reference/idempotency/).
- **Límites de velocidad.** El envío está limitado por espacio de trabajo, por defecto a 2 emails por segundo y 5000 emails al día, compartidos entre la API y SMTP. Las respuestas incluyen las cabeceras `ratelimit-*`, y un `429` incluye `retry-after`. Consulta [Límites de velocidad](/es/docs/api-reference/rate-limits/) y [Límites y cuotas](/es/docs/limits/).

## SDK

Las bibliotecas oficiales envuelven la API REST para Node.js, PHP, Laravel, Python, Ruby, Go, Java, .NET y Rust. Todas están en [GitHub](https://github.com/emailit). Para los comandos de instalación, consulta [SDK y bibliotecas](/es/docs/sdks/), y para ejemplos completos, las guías de frameworks, empezando por [Node.js](/es/docs/frameworks/nodejs/).

## Webhooks

Los webhooks envían eventos a tu endpoint en cuanto ocurren: entregas, rebotes, aperturas, clics, correo entrante y cambios en dominios, contactos y otros recursos. Cada petición lleva un array JSON de hasta 100 eventos y va firmada con HMAC-SHA256 en la cabecera `X-Emailit-Signature`. Las peticiones fallidas se reintentan, con un máximo de 11 intentos. Empieza por [Configurar un webhook](/es/docs/webhooks/set-up/) y [Firma de las peticiones](/es/docs/webhooks/request-signature/).

## Servidor MCP y herramientas de IA

El [servidor MCP](/es/docs/mcp/) alojado en `https://api.emailit.com/mcp` ofrece a los asistentes de IA 109 herramientas que cubren toda la API v2, desde el envío de emails hasta las campañas y las automatizaciones. Los asistentes inician sesión con OAuth o con una clave de API, y los [plugins de Emailit](/es/docs/mcp/plugins-and-skills/) añaden skills para ChatGPT, Codex, Claude Code, Cursor y Grok.

La documentación también se publica para la IA: cada página tiene una versión en Markdown, y [/docs/llms.txt](/es/docs/developers/llms-txt/) las indexa todas.

## Próximos pasos

  - [Crear una clave de API](/es/docs/developers/api-keys/): Elige un permiso, limítala a un dominio y guárdala de forma segura.
  - [Enviar tu primer email](/es/docs/quickstart/api/): Haz tu primera llamada a la API en unos minutos.
  - [SDK y bibliotecas](/es/docs/sdks/): Bibliotecas oficiales para nueve lenguajes y frameworks.
  - [Referencia de la API](/es/docs/api-reference/): Todos los endpoints, parámetros y respuestas.

---
Fuente: https://emailit.com/es/docs/developers/