Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

Conceptos básicos de la API

URL base, permisos de las claves de API, lista de errores, límites de peticiones, claves de idempotencia y paginación de la API de BillionSend.

Las páginas de endpoints de la referencia de la API se generan a partir de las definiciones de rutas de la API. La especificación OpenAPI 3.1 es la misma fuente en un solo archivo JSON.

La API es compatible con la API de Resend: mismas rutas, mismos formatos de petición y de error. Llámala desde los SDK de BillionSend o con HTTP directo.

URL base

https://api.billionsend.com

Autenticación

Envía en cada petición una clave de API de Claves de API en el panel:

Authorization: Bearer bs_...

Una clave ausente o mal formada responde 401 missing_api_key, y una incorrecta 401 invalid_api_key.

Una clave tiene un nivel de permiso:

  • Acceso total puede usar todos los endpoints.
  • Solo envío solo puede enviar. Todo lo que queda fuera de /emails responde 403 restricted_api_key, y lo mismo vale para GET /emails, GET /emails/{id}, GET /emails/metrics, DELETE /emails/{id} y todos los endpoints de /emails/receiving, porque devuelven contenido almacenado.

Una clave también se puede limitar a un dominio o a una bandeja de entrada. Una clave limitada a un dominio trabaja dentro de él: solo envía desde ese dominio, solo lee su correo, solo ve y cambia ese dominio en /domains, y responde 403 restricted_api_key en todo lo que pertenece al equipo entero (webhooks, supresiones, plantillas, propiedades de contacto, /usage, /deliverability, verificaciones, POST /domains); consulta Claves de API. Una clave que creas con la API nunca es más amplia que la clave que la creó.

Un equipo puede tener 25 claves activas. Las acciones que requieren una clave creada por un propietario o administrador se listan en Roles del equipo.

Errores

Todo error tiene esta forma:

{ "statusCode": 422, "name": "validation_error", "message": "..." }
Estado y nombre Significado
400 invalid_parameter El cuerpo no es un JSON válido.
401 missing_api_key / invalid_api_key Sin clave, o clave incorrecta.
403 restricted_api_key El permiso o el ámbito de la clave no lo permite.
403 forbidden Tu rol o tu clave no permite esta acción.
403 plan_limit_reached Alcanzaste un límite de tu plan. Consulta Planes y límites.
403 sending_paused El envío está en pausa porque tu tasa de rebotes o de quejas es demasiado alta.
404 not_found El endpoint, o lo que pediste, no existe.
409 invalid_idempotent_request La clave de idempotencia se usó con otro contenido.
415 El cuerpo no es application/json.
422 validation_error La petición no es válida. El mensaje dice por qué.
422 all_recipients_suppressed Todos los destinatarios están suprimidos o se han dado de baja. Consulta Supresiones.
429 rate_limit_exceeded Demasiadas peticiones.
429 daily_quota_exceeded / monthly_quota_exceeded Se agotó la cuota de envío de tu plan. Consulta Planes y límites.
503 service_unavailable El almacén de estadísticas no respondió. El envío no se ve afectado.

Todo 429 lleva una cabecera retry-after: los segundos que hay que esperar.

Toda respuesta, sea de error o no, lleva una cabecera x-request-id: el id de la petición, el mismo que tiene en la página Registros del panel. Indícalo cuando nos consultes por una petición.

Un destinatario cuyo dominio nunca puede recibir correo, como x@example.com, x@foo.test o x@gmail.con, se rechaza con 422 validation_error. Lo mismo vale para un contacto nuevo con esa dirección. Para probar sin escribir a nadie, envía a success@simulator.amazonses.com.

La recepción, las bandejas de entrada y la seguridad del agente añaden errores propios, que esas páginas listan.

Límites de peticiones

Cada clave de API puede hacer 600 peticiones por minuto, y las claves de un equipo juntas 3000. Por encima del límite recibes 429 rate_limit_exceeded y una cabecera retry-after. Más de 20 autenticaciones fallidas por minuto desde una misma dirección IP se rechazan del mismo modo.

Idempotencia

POST /emails y POST /emails/batch admiten una cabecera Idempotency-Key de 1 a 256 caracteres. También las respuestas, los reenvíos y los envíos de borrador de las bandejas de entrada, y las respuestas y los reenvíos de correo recibido. Si reintentas con la misma clave y el mismo contenido, obtienes la respuesta original en lugar de un segundo email. La misma clave con otro contenido responde 409.

Paginación

Los endpoints de lista admiten limit (de 1 a 100, 20 por defecto) y los cursores after y before, cada uno un id de elemento de una página anterior. La respuesta incluye has_more. Las listas van del más reciente al más antiguo:

  • after recibe el último id de una página y devuelve elementos más antiguos.
  • before recibe el primer id y devuelve elementos más recientes.

Para ponerte al día con lo nuevo, pasa como before el id más reciente que guardaste.

Algunas listas siguen otro orden, que indican sus páginas de referencia: los hilos de una bandeja (actividad más reciente primero), los emails de un hilo (del más antiguo al más reciente), y los temas y las etiquetas (del más antiguo al más reciente, todos de una vez). Un cursor que no coincide con ningún elemento responde 422 validation_error (404 bajo /inboxes).

Reglas que conviene conocer

  • Los adjuntos admiten solo content en base64 incrustado. Una URL path remota responde 422. Los adjuntos suman hasta 10 MiB por email, y el email entero debe quedar por debajo de 40 MB. Los programas y scripts (.exe, .js, .bat y similares, también dentro de un ZIP) se rechazan siempre. En un equipo nuevo, algunos tipos de riesgo, como archivos comprimidos, páginas web y archivos de Office con macros, se aceptan pero esperan una revisión antes de enviarse.
  • Los contactos pertenecen al equipo. No hay audiencias: los endpoints de audiencia funcionan como alias de los segmentos.
  • Las bajas pertenecen al dominio de envío. Consulta Bajas.
  • Destinatarios: to, cc y bcc juntos admiten hasta 50 direcciones, cada una un solo buzón. Un envío en el que todas las direcciones de to están suprimidas responde 422 all_recipients_suppressed.
  • Las cabeceras tienen lista de permitidas: cualquier nombre X-* (salvo X-SES-* y X-BillionSend-*), cabeceras de hilos y de prioridad, y el par List-Unsubscribe. Cualquier otra responde 422.
  • Los asuntos pueden tener hasta 998 caracteres.
  • Endpoints adicionales: GET /usage (plan, límites y uso), DELETE /emails/{id} y GET /emails/metrics (Analíticas).
  • Contactos en bloque: POST /contacts/batch crea y POST /contacts/batch/remove elimina hasta 1000 contactos en una petición. include=properties,topics en las listas de contactos añade las propiedades y los temas de cada contacto.
  • Las supresiones en bloque admiten hasta 1000 direcciones por petición.
  • Estados adicionales: los envíos masivos pueden quedar canceled.
  • La recepción y las bandejas de entrada están en beta, con long-polling y un flujo de eventos en directo para el correo nuevo. Consulta Recepción y Bandejas de entrada.
  • Los ajustes no admitidos se rechazan con 422 en lugar de ignorarse en silencio.

Enlaces de descarga firmados

El correo recibido lleva enlaces de descarga del mensaje original y de sus adjuntos. Son URL GET sencillas que no necesitan clave de API, funcionan una hora y responden 403 cuando caducan. Pide a la API un enlace nuevo. Consulta Recepción.

¿Te ha resultado útil esta página?