De cero a un mensaje enviado, en minutos

Empieza aquí: de cero a un mensaje enviado

La documentación está organizada en torno a lo que intentas hacer, no en torno a la forma de la API, porque los desarrolladores escanean en lugar de leer y lo primero que casi todos quieren es un único mensaje fuera. Hay dos formas de enviar —relay SMTP y la API REST— y puedes estar en vivo en cualquiera de las dos en minutos una vez que el DNS de tu dominio está en su sitio. Elige la que coincide con cómo ya funciona tu aplicación; ninguna es más capaz, son formas de integración distintas para situaciones distintas. La referencia de cada endpoint, parámetro y código de respuesta vive en la referencia completa de la API; esta página es el mapa y el quickstart que te lleva a tu primera llamada exitosa.

Opción A — relay SMTP, si tu app ya habla SMTP

Si tu framework o aplicación ya envía correo por SMTP, esto es un cambio de configuración en lugar de un cambio de código. Apunta tu cliente SMTP al relay con tus credenciales sobre un puerto cifrado —587 con STARTTLS, o 465 con TLS implícito— y estás enviando:

Configuración SMTPHost:     smtp.authorizehosting.com
Port:     587          (STARTTLS)  ·  o 465 (TLS implícito)
Username: tu-identidad-de-envio
Password: tu-clave-de-relay
TLS:      requerido — el relay rechaza el texto plano

Esa es toda la integración para la mayoría de remitentes. Lo único que vale la pena hacer antes de enviar en volumen es confirmar que tu autenticación está en su sitio, porque que el relay acepte tu mensaje y que la bandeja del destinatario lo acepte son dos cosas distintas: ve la sección de autenticación más abajo.

Opción B — la API REST, si el envío vive en tu código

Si prefieres que la lógica de envío se asiente en tu aplicación con respuestas estructuradas y webhooks, la API REST sigue convenciones predecibles: un token Bearer en el encabezado Authorization, un cuerpo JSON, y una respuesta JSON con un esquema estable. Aquí está la llamada mínima inicial, con la credencial leída de una variable de entorno en lugar de hardcodeada —algo pequeño que importa, porque un ejemplo de docs que hardcodea un secreto enseña un hábito inseguro—:

Primera llamada a la API — curlcurl https://api.authorizehosting.com/v1/send \
  -H "Authorization: Bearer $AUTHORIZE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "alerts@tudominio.com",
    "to": "cliente@ejemplo.com",
    "subject": "Pedido #4821 confirmado",
    "stream": "transactional",
    "text": "Tu pedido va en camino."
  }'

Un envío exitoso devuelve 202 Accepted con un identificador de mensaje que puedes correlacionar contra eventos de webhook después. El campo stream vale la pena fijarlo desde la primera llamada: enruta el mensaje al MTA virtual correcto para que tu tráfico transaccional y masivo lleven reputaciones separadas, que es una de las razones para estar en infraestructura dedicada en primer lugar.

Lo que la mayoría de quickstarts omite: los modos de fallo

Cuando la documentación solo muestra el caso de éxito, los desarrolladores descubren los modos de fallo por ensayo y error en producción, que es el peor lugar para aprenderlos. Así que aquí están las respuestas que vale la pena manejar desde el inicio. Un 202 significa aceptado para entrega. Un 401 significa que la clave de API es incorrecta o falta. Un 422 significa que la petición se entendió pero un campo es inválido —una dirección malformada, un campo requerido ausente—. Un 429 significa que te están limitando la tasa y deberías retroceder y reintentar. Y en el lado SMTP, la distinción que importa es la cubierta en el glosario: un 421 es un aplazamiento temporal para reintentar, un 550 es un rechazo permanente para detenerse e investigar.

Un patrón que vale la pena incorporar desde el inicio: la idempotencia. Si un fallo de red te deja sin saber si un envío tuvo éxito, reintentar sin una clave de idempotencia arriesga enviar dos veces. Incluir una deja que la API reconozca el reintento y evite el duplicado: el tipo de consideración de producción que un fragmento mínimo omite pero una integración real necesita.

Autenticación: la parte que decide si algo de esto llega a la bandeja

Recibir un 202 de vuelta significa que el mensaje fue aceptado por nosotros, no que aterrizará en la bandeja del destinatario, y la brecha entre ambos es casi enteramente sobre autenticación de dominio. Antes de enviar en volumen, tres registros DNS necesitan estar bien: SPF autorizando el relay, DKIM firmando tus mensajes, y DMARC indicando a los receptores cómo manejar los fallos. En los planes gestionados el equipo operador los monta contigo; en cualquier plan puedes verificarlos tú mismo con las herramientas gratuitas —el verificador DMARC, el aplanador SPF y el tester DKIM— que te leen de vuelta exactamente lo que ve un servidor receptor. La página de fundamentos de entregabilidad explica por qué esta capa importa más que cualquier cosa en tu código de envío.

Webhooks: saber qué pasó después de enviar

Que la API acepte un mensaje es el comienzo de su vida, no el final. Los webhooks entregan los eventos que siguen —entregado, rebotado, con queja, abierto donde se rastrea— a un endpoint que tú controlas, con campos estructurados de resultado de autenticación para que veas no solo que un mensaje rebotó sino si falló la autenticación en el camino. El esquema de payload v2 lleva estos campos estructurados; el formato v1 más antiguo está obsoleto pero soportado al menos hasta el final de 2026, como se nota en el changelog. Construye tu manejador para verificar la firma del webhook y para ser idempotente, ya que la entrega al-menos-una-vez significa que un evento puede llegar más de una vez.

Cómo está organizada la documentación

Más allá de este quickstart, la documentación sigue los flujos de trabajo del desarrollador en lugar de la estructura interna de la API. Hay un camino de primeros pasos que te lleva de la cuenta al primer envío; una sección de autenticación que cubre tanto las credenciales de API como la capa de autenticación de correo SPF/DKIM/DMARC; una referencia de envío para cada parámetro tanto en SMTP como en REST; una sección de webhooks con cada tipo de evento y payload; y un camino de migración si estás moviendo una integración existente desde otro proveedor, que es mayormente un ejercicio de mapeo de campos documentado por proveedor origen. Las descripciones de endpoint explican el propósito de negocio, no solo la mecánica: para qué sirve una llamada, no solo qué hace.

Cuando los docs no lo responden

La documentación responde las preguntas que generalizan. La infraestructura de correo también genera una larga cola de situaciones específicas —un cliente SMTP inusual, un patrón de entregabilidad particular de tu base de destinatarios, una migración con un pliegue que la guía estándar no cubre—. Para esas, el camino más rápido no es buscar un doc que puede no existir; es preguntar al equipo operador, que en los planes gestionados son las mismas personas que operan la infraestructura en lugar de un nivel de soporte separado leyendo de un guion. La buena documentación responde la pregunta de un desarrollador antes de que la haga; un proveedor honesto también hace fácil hacer las preguntas que la documentación no puede anticipar.