Faturalandırma

MailLand, abonelik yönetimi ve faturalandırma için Stripe kullanır. Her çalışma alanının kullanım tabanlı veya plan tabanlı fiyatlandırmayla kendi aboneliği vardır. Herhangi bir üye faturalandırma durumunu okuyabilir; yalnızca çalışma alanı Sahibi bunu değiştirebilir (değiştiren çağrılar 403 INSUFFICIENT_PERMISSIONS döner ve API anahtarları bu uç noktalarda her zaman reddedilir).

Ödeme DurumlarıBölüm bağlantısını kopyala

paymentStatus, sayısal bir enum değil, snake_case bir dize olarak döner:

Abonelik Ayrıntılarını AlınBölüm bağlantısını kopyala

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
  }
}

Bu yanıtta id, planId, interval, currentPeriodStart/currentPeriodEnd veya iç içe sayısal paymentStatus/doğrulama/alan adı/ekip/otomasyon kullanım alanları yoktur, yukarıdaki alan adlarını kullanın. paymentStatus, "current", "grace_period", "overdue" veya "blocked" şeklinde snake_case bir dizedir. status, PascalCase'dir ("Active", "Suspended", "Cancelled"): tek istisna, küçük harfli "active" döndüren abonelik olmayan geri dönüş yanıtıdır.

Kullanım AlanlarıBölüm bağlantısını kopyala

Bu yanıtta doğrulama, alan adı, ekip üyesi veya otomasyon kullanım sayaçları yoktur, yalnızca e-posta gönderim sayaçları.

E-posta Kullanımı Ne Zaman SayılırBölüm bağlantısını kopyala

Alıcılar, kabulün kalıcı olarak kaydedildiği anda kullanımınıza ve kotanıza (emailsSentThisMonth / monthlyLimit) karşı sayılır. Kabulden önce reddedilen veya bastırılan alıcılar hiçbir zaman sayılmaz. Kabulden sonra meydana gelen bir sekme (bounce), alt akış bastırması, teslimat hatası veya başka bir teslim edilememe durumu, kullanımı veya kotayı otomatik olarak geri yüklemez veya geri almaz, sayım geriye dönük olarak ayarlanmaz. Bu bölüm yalnızca kullanım muhasebesini açıklar; e-posta başına Stripe fiyatlandırmasını veya abonelik şartlarınızca ayrıca yönetilen herhangi bir iade hakkını belirtmez veya ima etmez.

Planlar ve SaklamaBölüm bağlantısını kopyala

Planlar Free, Pro ve Max'tır. Mesaj günlükleri Free'de 30 gün, Pro'da 90 gün ve Max'ta 180 gün saklanır.

İlke ÖzetiBölüm bağlantısını kopyala

Çalışma alanı doğrulama durumunu ve gönderme politikasını alın:

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

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

Gerçek yanıt, düz değil iç içe bir nesnedir (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": []
  }
}

Ödeme Oturumu OluşturunBölüm bağlantısını kopyala

Abone olmak veya yükseltmek için bir Stripe Checkout oturumu başlatın:

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

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

businessAttested: true ve kabul edilen bir businessAttestationKey içermeyen istek, herhangi bir ücret alınmadan önce 400 BUSINESS_ATTESTATION_REQUIRED ile reddedilir. MailLand kimin, ne zaman, hangi ifadeyle (gönderdiğiniz anahtar) ve hangi dilde onayladığını saklar. Stripe Checkout'ta bir vergi numarası girebilirsiniz; bu isteğe bağlıdır. Fiyatlara KDV dahil değildir ve MailLand KDV tahsil etmez; Birleşik Krallık dışındaki doğrulanmış bir AB KDV numarası faturalarınıza ters ücret notunu ekler.

Bu istekte successUrl veya cancelUrl alanı yoktur, başarı/iptal URL'leri çağıran tarafından sağlanmaz.

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..."
}

Stripe'ın barındırılan ödeme sayfasında ödemeyi tamamlamak için kullanıcıyı url adresine yönlendirin. Çalışma alanının zaten aktif bir aboneliği varsa, yeni bir ödeme açmak yerine plan yerinde değiştirilir: yanıt, sessionId/url olmadan { "upgraded": true } şeklindedir ve yönlendirme yoktur. Yalnızca url mevcut olduğunda yönlendirin.

Faturalandırma PortalıBölüm bağlantısını kopyala

Self servis yönetim için Stripe Müşteri Portalını açın (ödeme yöntemini güncelleyin, iptal edin, faturaları görüntüleyin):

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

{
  "locale": "en"
}

locale isteğe bağlıdır.

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..."
}

Stripe portalına erişmek için kullanıcıyı url adresine yönlendirin.

Faturaları ListeleyinBölüm bağlantısını kopyala

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
}

Bu, { "invoices": [...] } değil, imleç (cursor) ile sayfalanmış bir yanıttır: bir sonraki sayfayı almak için nextCursor'ı cursor parametresi olarak geri gönderin ve hasMore false olduğunda durun. Varsayılan sayfa boyutu 10 değil 20'dir; alan adları number, amount, invoiceUrl, invoicePdf değil, invoiceNumber, amountDue, amountPaid, hostedInvoiceUrl ve invoicePdfUrl'dir.

Hata YanıtlarıBölüm bağlantısını kopyala

Diğer Faturalandırma Uç NoktalarıBölüm bağlantısını kopyala

Ayrıca mevcut olan ve yukarıda ayrıntılı anlatılmayan: POST /v1/account/billing/cancel, POST /v1/account/billing/reactivate ve genel GET /public/plans/catalog uç noktası.

Sonraki AdımlarBölüm bağlantısını kopyala

• Çalışma Alanları: çalışma alanı ayarlarını yönetin
• Ekip Yönetimi: ekip üyelerini yönetin
• Hız Sınırları: API hız sınırlarını anlayın