Referencia de la API

Códigos de error

Todos los códigos de error que puede devolver la API, con su estado HTTP y qué hacer. Envío y recepción usan formatos de error distintos.

Enviar email

Los errores devuelven un objeto JSON con error, code y responseTime. Consulta Enviar email.

  • 401MISSING_AUTH_HEADER

    No hay header Authorization.

  • 401INVALID_API_KEY

    La API key no es válida o fue revocada.

  • 401ACCOUNT_BLOCKED

    La cuenta fue bloqueada.

  • 401NO_CREDITS_LEFT

    No hay créditos de email suficientes para todos los destinatarios. Cada dirección en to, cc y bcc usa 1 crédito.

  • 401DOMAIN_NOT_VALIDATED

    Dominio del remitente no verificado.

  • 401LISTED_SPAM_HAUS

    El dominio del remitente está listado en Spamhaus.

  • 401ISP_DOMAIN_BLOCKED

    No se permite enviar desde dominios conocidos (gmail.com, outlook.com, etc).

  • 401FROM_HEADER_DOMAIN_MISMATCH

    Dominio del header From no autorizado para este remitente.

  • 401USER_NOT_FOUND

    Usuario no encontrado.

  • 401MISSING_USER_PRIVILEGES

    Faltan privilegios de usuario.

  • 401EMAIL_CREDITS_NOT_FOUND

    Error al obtener los créditos de email.

  • 401EMAIL_NOT_VALIDATED

    El email de la cuenta aún no fue verificado.

  • 429CREDENTIAL_TEMPORARILY_BLOCKED

    API key bloqueada temporalmente por violaciones repetidas de la política.

  • 429IP_TEMPORARILY_BLOCKED

    IP de la solicitud bloqueada temporalmente por violaciones repetidas de la política.

  • 429TOO_MANY_CONCURRENT_CONNECTIONS

    Demasiadas solicitudes simultáneas desde esta IP. Inténtalo de nuevo en breve.

  • 400INVALID_JSON

    El cuerpo de la solicitud no es un JSON válido.

  • 400MISSING_FROM

    El campo from falta o está vacío.

  • 400INVALID_FROM_FORMAT

    El campo from debe ser una dirección de email válida.

  • 400MISSING_SENDERNAME

    El campo senderName falta o está vacío.

  • 400INVALID_SENDERNAME_FORMAT

    El campo senderName contiene caracteres no válidos.

  • 400MISSING_SUBJECT

    El campo subject falta o está vacío.

  • 400MISSING_BODY

    El campo body falta o está vacío.

  • 400MISSING_TOADDRESS

    El campo to falta o está vacío.

  • 400MISSING_TO

    El campo to falta o está vacío.

  • 400INVALID_TOADDRESS

    Una o más direcciones de destinatario están mal formadas.

  • 400TOADDRESS_LIMIT_EXCEEDED

    Más de 50 destinatarios en el array to.

  • 400INVALID_CCADDRESS

    Una o más direcciones de cc están mal formadas.

  • 400INVALID_BCCADDRESS

    Una o más direcciones de bcc están mal formadas.

  • 400RECIPIENT_LIMIT_EXCEEDED

    to, cc y bcc juntos tienen más de 50 destinatarios únicos.

  • 400INVALID_SCHEDULED_AT

    scheduled_at no es una fecha válida o está en el pasado.

  • 400INVALID_SENDER_FORMAT

    El formato del email del remitente no es válido.

  • 400HEADER_NOT_ALLOWED

    La clave del header personalizado no está en la lista permitida (List-Unsubscribe, List-Id, X-*, etc).

  • 400INVALID_HEADER_VALUE

    El valor del header contiene caracteres no válidos (CR/LF no permitidos).

  • 400DANGEROUS_ATTACHMENT

    Uno o más adjuntos fueron bloqueados por motivos de seguridad.

  • 400INVALID_ATTACHMENT

    El contenido de un adjunto no es base64 válido.

  • 400MISSING_UNSUBSCRIBE_PLACEHOLDER

    unsubscribe es true pero el body no tiene placeholder de baja ([unsubscribe_url], [unsubscribe], [unsub_url] o [opt_out_url]).

  • 403ACCOUNT_RESTRICTED

    La cuenta está restringida temporalmente.

  • 403DAILY_LIMIT

    Se alcanzó el límite diario de envío de emails.

  • 403MARKETING_LIMIT_REACHED

    Se alcanzó el límite diario de marketing del plan gratuito: 30 emails de marketing o cold outreach por día, contados por destinatario en una ventana móvil de 24 horas. La respuesta incluye limit, used, recipients y upgradeUrl. Los emails transaccionales se siguen enviando; nada queda en cola.

  • 403FORBIDDEN_HTML_CONTENT

    El HTML contiene contenido activo no permitido en emails (script, iframe, form, input, button, embed, object, svg, handlers on*, enlaces javascript:, meta refresh…). La respuesta lista lo encontrado. Usa un <a> con estilos en lugar de botones o formularios.

  • 403SPAM_DETECTED

    Contenido del email marcado como spam. La respuesta incluye el quarantine_id y las instrucciones de liberación.

  • 403SENDER_NAME_MISMATCH

    Se detectaron varios nombres de remitente para la misma dirección.

  • 403FOLLOWUP_PATTERN_DETECTED

    Contenido del email marcado como patrón repetido de seguimiento sospechoso.

  • 403SCAM_PATTERN_DETECTED

    Contenido del email marcado como patrón de estafa.

  • 403SHARED_DOMAIN_REQUIRES_PAID_PLAN

    Este dominio de envío compartido solo está disponible en los planes de pago. La respuesta indica en allowedDomains los dominios compartidos que puedes usar, además de upgradeUrl. Usa uno de ellos o tu propio dominio verificado.

  • 403ACCOUNT_SUSPENDED_SPOOFING

    Cuenta suspendida por intentos repetidos de suplantación del header From.

  • 409IDEMPOTENCY_IN_PROGRESS

    Una solicitud con la misma Idempotency-Key todavía se está procesando. Espera (Retry-After: 1) y reintenta con la misma clave.

  • 422IDEMPOTENCY_KEY_REUSED

    Esta Idempotency-Key ya se usó con otro cuerpo. Usa una clave nueva para cada email nuevo.

  • 500INTERNAL_SERVER_ERROR

    Error inesperado del servidor. Inténtalo de nuevo.

  • 500PARSE_ERROR

    No se pudo procesar el contenido del email (fallo de parse MIME).

  • 500PERSIST_FAILED

    No se pudo poner el email en cola (fallo de persistencia en la base de datos).

  • 503AUTH_UNAVAILABLE

    No se pudo validar la API key en este momento. Inténtalo de nuevo.

  • 503UNSUBSCRIBE_UNAVAILABLE

    Servicio de enlace de baja no disponible temporalmente. Inténtalo más tarde.

Límites del plan gratuito

En el plan gratuito, el marketing y el cold outreach están limitados a 30 emails por día, contados por destinatario (un email a 5 personas cuenta como 5) en una ventana móvil de 24 horas. Los emails transaccionales no se ven afectados. Por encima del límite la solicitud se rechaza y nada queda en cola: vuelve a enviar cuando se libere la ventana o mejora tu plan.

403MARKETING_LIMIT_REACHED

Lo devuelve /v3.0/send cuando este email superaría el límite de marketing del plan gratuito. used es lo que ya se contó en las últimas 24 horas y recipients es cuántos sumaría este email.

{
  "code": "MARKETING_LIMIT_REACHED",
  "error": "Daily marketing limit reached for the free plan (30/30, 2 recipients in this email). Transactional emails still go out.",
  "limit": 30,
  "used": 30,
  "recipients": 2,
  "upgradeUrl": "https://app.sendcorex.com/dashboard/billing"
}
403SHARED_DOMAIN_REQUIRES_PAID_PLAN

Se devuelve al crear un remitente en un dominio compartido que solo está disponible en los planes de pago. allowedDomains indica los dominios compartidos que tu plan puede usar; tu propio dominio verificado siempre funciona.

{
  "code": "SHARED_DOMAIN_REQUIRES_PAID_PLAN",
  "error": "This shared domain is available on paid plans. Use inboxtaken.com or your own domain.",
  "allowedDomains": ["inboxtaken.com"],
  "upgradeUrl": "https://app.sendcorex.com/dashboard/billing"
}

Reglas completas: Política de Uso Aceptable — Plan gratuito

Recepción: errores HTTP

Estos rechazan toda la solicitud. El body es { "type": "ERROR", "code": "...", "message": "..." }. Con RATE_LIMITED, espera los segundos indicados en el header Retry-After.

  • 400INVALID_JSON

    The body is not {"commands":[...]} or has more than 20 commands.

  • 401MISSING_AUTH_HEADER

    No Authorization header was sent.

  • 401INVALID_TOKEN

    The token is malformed, unknown or revoked.

  • 401TOKEN_EXPIRED

    The access token has expired. Call Refresh Token and repeat the request.

  • 401INVALID_REFRESH_TOKEN

    The refresh token is invalid, expired, revoked or already used. Generate a new token in the dashboard.

  • 429RATE_LIMITED

    More than 15 requests/s or 15 in flight for the same IP + mailbox. Wait the number of seconds in Retry-After.

  • 503AUTH_UNAVAILABLE

    Authentication is temporarily unavailable. Try again.

Recepción: errores de comando

Estos vuelven dentro del resultado del comando, con HTTP 200, así que un comando que falla no detiene a los demás de la misma solicitud. Revisa results[].type. Consulta Ejecutar comandos.

  • CMDINVALID_ARGS

    A required argument is missing or invalid.

  • CMDUNKNOWN_COMMAND

    The command name does not exist.

  • CMDNOT_FOUND

    The message, thread or folder does not exist for this token.

  • CMDINVALID_CURSOR

    The cursor is malformed or belongs to another account or folder.

  • CMDALREADY_EXISTS

    A folder or label with this name already exists.

  • CMDNOT_IN_TRASH

    delete only works on messages in Trash or Spam. Use move to send a message to Trash first.

  • CMDSENDER_NOT_FOUND

    The sender behind the token is not registered.

  • CMDSENDER_NO_DOMAIN

    The sender behind the token has no domain.

  • CMDNO_CREDITS

    The account has fewer email credits than recipients (1 credit per copy).

  • CMDNO_RECIPIENT

    The conversation has no recipient to reply to.

  • CMDINVALID_RULE

    The rule is not valid. The message says which condition or action and why.

  • CMDLIMIT

    The mailbox reached the limit (100 rules, 200 templates or 100 labels).

  • CMDINVALID_TOADDRESS

    The to address is not a valid email.

  • CMDINVALID_CCADDRESS

    One of the cc addresses is not a valid email.

  • CMDINVALID_BCCADDRESS

    One of the bcc addresses is not a valid email.

  • CMDINVALID_RECIPIENT

    The recipient is missing or not a valid email.

  • CMDRECIPIENT_LIMIT_EXCEEDED

    to, cc and bcc together have more than 50 addresses.

  • CMDINVALID_ATTACHMENT

    An attachment content is not valid base64.

  • CMDFILE_BLOCKED

    A file was blocked by the security scan.

  • CMDATTACHMENTS_TOO_LARGE

    The attachments of the email add up to more than 25 MB, or the mailbox already has 500 MB of uploads waiting to be sent.

  • CMDTOO_MANY_OPEN_COMPOSES

    The mailbox has 50 emails with uploads that were not sent yet. Send them, or wait for the unused ones to be deleted after 48 hours.

  • CMDATTACHMENT_MISSING

    An uploaded attachment no longer exists (uploads not sent within 48 hours, and not used by a draft or scheduled email, are deleted). Upload it again.

  • CMDALREADY_SENT

    The compose_uid belongs to an email that was already sent.

  • CMDINVALID_TIME

    send_at is missing, less than 1 minute away or more than 1 year away.

  • CMDMISSING_SUBJECT

    A new email needs a subject.

  • CMDMISSING_TARGET

    Reply and forward need the original email, and it must still exist.

  • CMDDRAFT_NOT_FOUND

    The draft does not exist anymore: it was sent, deleted, or saved again (every save returns a new draft_id).

  • CMDNOT_SCHEDULED

    The email was already sent or canceled.

  • CMDSEND_FAILED

    The send was refused. The email is back in Drafts and the message says why.

  • CMDNO_UNSUBSCRIBE

    The email has no List-Unsubscribe header.

  • CMDRECIPIENT_UNSUBSCRIBED

    One or more recipients unsubscribed from this mailbox. `recipients` lists them: remove them or send again with `unsubscribe: false`.

  • CMDPAID_PLAN_REQUIRED

    More than one address in `to` needs a paid plan.

  • CMDTOO_MANY_RECIPIENTS

    `to` has more than 30 addresses.

  • CMDINVALID_AUDIENCE

    The audience is not valid: unknown group, a segment of another mailbox or a message this mailbox didn’t send.

  • CMDAUDIENCE_OVER_LIMIT

    The audience has more people than you can send to (up to 5,000 per email and your daily limit). `total` and `allowed` say how many.

  • CMDEMPTY_AUDIENCE

    Nobody in this audience right now.

  • CMDBEST_TIME_NEEDS_AUDIENCE

    `best_time` needs an `audience` and `mode: new`.

  • CMDREAD_ONLY_ACCESS

    The token or app has Read only access and the command writes. In the attachment upload route it is HTTP 403.

  • CMDINTERNAL

    Server error. The detail is only written to the server log.