Facturación

MailLand utiliza Stripe para la gestión de suscripciones y facturación. Cada espacio de trabajo tiene su propia suscripción con precios basados en uso o en plan. Cualquier miembro puede leer el estado de facturación; solo el Owner del espacio de trabajo puede modificarlo (las llamadas de mutación devuelven 403 INSUFFICIENT_PERMISSIONS, y las claves API siempre son rechazadas en esos endpoints).

Estados de PagoCopiar enlace de la sección

paymentStatus se devuelve como una cadena snake_case, no como un enum numérico:

Obtener Detalles de SuscripciónCopiar enlace de la sección

GET https://api.mail.land/v1/account/subscription

curl https://api.mail.land/v1/account/subscription \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "planName": "Pro",
  "monthlyEmailLimit": 100000,
  "rateLimitPerSecond": 10,
  "pricePerMonth": 49.00,
  "startDate": "2026-01-15T08:00:00Z",
  "endDate": "2026-03-01T00:00:00Z",
  "status": "Active",
  "paymentStatus": "current",
  "marketingPausedDueToPayment": false,
  "sendingBlockedDueToPayment": false,
  "transactionalDailyLimit": 5000,
  "daysUntilBlocked": null,
  "cancelAtPeriodEnd": false,
  "planFamilyId": "fam_pro",
  "planTierPublicId": "tier_pro_monthly",
  "usage": {
    "emailsSentThisMonth": 45000,
    "monthlyLimit": 100000,
    "percentageUsed": 45.0,
    "transactionalCount": 30000,
    "marketingCount": 12000,
    "apiCount": 40000,
    "smtpCount": 5000,
    "campaignCount": 3000,
    "automationCount": 2000,
    "inboundForwardCount": 500
  }
}

No hay id, planId, interval, currentPeriodStart/currentPeriodEnd, ni campos numéricos anidados de paymentStatus/validación/dominio/equipo/automatización en esta respuesta: use los nombres de campo anteriores. paymentStatus es una cadena snake_case: "current", "grace_period", "overdue" o "blocked". status está en PascalCase ("Active", "Suspended", "Cancelled"): la única excepción es el resultado sin suscripción, que devuelve "active" en minúsculas.

Campos de UsoCopiar enlace de la sección

No hay contadores de uso de validación, dominio, miembros del equipo o automatización en esta respuesta: solo contadores de envío de correo.

Cuándo se cuenta el uso de correoCopiar enlace de la sección

Los destinatarios cuentan contra su uso y cuota (emailsSentThisMonth / monthlyLimit) en el momento en que la aceptación se registra de forma duradera. Los destinatarios rechazados o suprimidos antes de la aceptación nunca cuentan. Un rebote, una supresión posterior, un fallo de entrega u otra no entrega que ocurra después de la aceptación no restaura ni recupera automáticamente el uso o la cuota: el conteo no se ajusta retroactivamente. Esta sección describe solo la contabilidad de uso; no establece ni implica precios de Stripe por correo ni ningún derecho de reembolso, que se rigen por separado por los términos de su suscripción.

Planes y retenciónCopiar enlace de la sección

Los planes son Free, Pro y Max. Los registros de mensajes se conservan 30 días en Free, 90 días en Pro y 180 días en Max.

Resumen de PolíticaCopiar enlace de la sección

Obtenga el estado de verificación del espacio de trabajo y la política de envío:

GET https://api.mail.land/v1/account/subscription/policy-summary

curl https://api.mail.land/v1/account/subscription/policy-summary \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

La respuesta real es un objeto anidado, no plano (SubscriptionController.cs:137-200):

{
  "subscription": {
    "planFamilyId": "fam_pro",
    "planFamilyName": "Pro",
    "planTierId": "tier_pro_monthly",
    "monthlyQuota": 100000,
    "pricePerMonth": 49.00
  },
  "usage": {
    "usedThisMonth": 45000,
    "remainingThisMonth": 55000,
    "percentUsed": 45.0
  },
  "effectiveRates": {
    "transactionalRatePerMin": 600,
    "marketingRatePerMin": 300,
    "isOverridden": false
  },
  "domainWarmup": [
    {
      "domainId": "h4k7m1n9w2p5x8",
      "domainName": "example.com",
      "currentStage": 2,
      "totalStages": 5,
      "todaySentCount": 350,
      "dailyLimit": 500,
      "progressPercent": 70.0,
      "completed": false,
      "bypassed": false
    }
  ],
  "alerts": [
    {
      "type": "warning",
      "code": "QUOTA_WARNING",
      "message": "You have used 80% of your monthly quota. Consider upgrading your plan.",
      "actionUrl": "/billing"
    }
  ],
  "dailySendingLimit": {
    "limit": 5000,
    "usedToday": 1200,
    "remainingToday": 3800,
    "resetsAt": "2026-02-18T00:00:00Z"
  },
  "verification": {
    "level": 2,
    "levelName": "SenderVerified",
    "limits": {},
    "progress": {},
    "nextSteps": []
  }
}

Crear Sesión de PagoCopiar enlace de la sección

Inicie una sesión de Stripe Checkout para suscribirse o actualizar su plan:

POST https://api.mail.land/v1/account/billing/checkout

{
  "planTierId": "tier_pro_monthly",
  "locale": "en",
  "businessAttested": true,
  "businessAttestationKey": "business-use-v3-button"
}

Una solicitud sin businessAttested: true y sin un businessAttestationKey aceptado se rechaza con 400 BUSINESS_ATTESTATION_REQUIRED antes de cobrar nada. MailLand guarda quién confirmó, cuándo, con qué texto (la clave que usted envió) y en qué idioma. En Stripe Checkout puede introducir un identificador fiscal; es opcional. Los precios no incluyen IVA y MailLand no cobra IVA; un NIF-IVA de la UE verificado, fuera del Reino Unido, añade la nota de inversión del sujeto pasivo a sus facturas.

No hay campo successUrl ni cancelUrl: las URLs de éxito/cancelación no son proporcionadas por quien llama.

curl -X POST https://api.mail.land/v1/account/billing/checkout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "planTierId": "tier_pro_monthly", "locale": "en", "businessAttested": true, "businessAttestationKey": "business-use-v3-button" }'

{
  "upgraded": false,
  "sessionId": "cs_live_abc123...",
  "url": "https://checkout.stripe.com/c/pay/cs_live_abc123..."
}

Redirija al usuario a la url para completar el pago en la página de pago alojada por Stripe. Si el espacio de trabajo ya tiene una suscripción activa, el plan se cambia en el mismo lugar en lugar de abrir un nuevo checkout: la respuesta es { "upgraded": true } sin sessionId/url, y no hay redirección. Solo redirija cuando url esté presente.

Portal de FacturaciónCopiar enlace de la sección

Abra el Portal del Cliente de Stripe para la gestión de autoservicio (actualizar método de pago, cancelar, ver facturas):

POST https://api.mail.land/v1/account/billing/portal

{
  "locale": "en"
}

locale es opcional.

curl -X POST https://api.mail.land/v1/account/billing/portal \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "locale": "en" }'

{
  "url": "https://billing.stripe.com/p/session/abc123..."
}

Redirija al usuario a la url para acceder al portal de Stripe.

Listar FacturasCopiar enlace de la sección

GET https://api.mail.land/v1/account/billing/invoices

curl https://api.mail.land/v1/account/billing/invoices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "items": [
    {
      "publicId": "inv_abc123",
      "invoiceNumber": "INV-2026-0015",
      "stripeInvoiceId": "in_1AbCdEfGhIjKlMn",
      "status": "Paid",
      "amountDue": 4900,
      "amountPaid": 4900,
      "currency": "eur",
      "periodStart": "2026-01-01T00:00:00Z",
      "periodEnd": "2026-02-01T00:00:00Z",
      "paidAt": "2026-01-01T00:05:00Z",
      "hostedInvoiceUrl": "https://pay.stripe.com/invoice/inv_abc123",
      "invoicePdfUrl": "https://pay.stripe.com/invoice/inv_abc123/pdf",
      "createdAt": "2026-01-01T00:00:00Z"
    },
    {
      "publicId": "inv_def456",
      "invoiceNumber": "INV-2026-0014",
      "stripeInvoiceId": "in_2BcDeFgHiJkLmNo",
      "status": "Paid",
      "amountDue": 4900,
      "amountPaid": 4900,
      "currency": "eur",
      "periodStart": "2025-12-01T00:00:00Z",
      "periodEnd": "2026-01-01T00:00:00Z",
      "paidAt": "2025-12-01T00:05:00Z",
      "hostedInvoiceUrl": "https://pay.stripe.com/invoice/inv_def456",
      "invoicePdfUrl": "https://pay.stripe.com/invoice/inv_def456/pdf",
      "createdAt": "2025-12-01T00:00:00Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Esta es una respuesta paginada por cursor, no { "invoices": [...] }: pase nextCursor de vuelta como el parámetro cursor para obtener la siguiente página, y deténgase cuando hasMore sea false. El tamaño de página predeterminado es 20, no 10; los nombres de campo son invoiceNumber, amountDue, amountPaid, hostedInvoiceUrl e invoicePdfUrl (no number, amount, invoiceUrl, invoicePdf).

Respuestas de ErrorCopiar enlace de la sección

Otros Endpoints de FacturaciónCopiar enlace de la sección

También disponibles, no detallados arriba: POST /v1/account/billing/cancel, POST /v1/account/billing/reactivate, y el endpoint público GET /public/plans/catalog.

Pasos SiguientesCopiar enlace de la sección

• Espacios de Trabajo: administrar la configuración del espacio de trabajo
• Gestión de Equipos: administrar miembros del equipo
• Límites de Velocidad: comprender los límites de velocidad de la API