کلیدهای API

کلیدهای API (اعتبارنامه‌ها) برنامه شما را با API MailLand احراز هویت می‌کنند. هر کلید بر اساس محصول، حالت، جریان، کانال و به صورت اختیاری بر اساس دامنه و آدرس IP محدود می‌شود.

در داشبورد، کلیدها را از اعتبارنامه‌ها (Credentials) در نوار کناری (بخش Global) ایجاد و مدیریت کنید. همین عملیات از طریق API ‏/v1/credentials که در ادامه آمده نیز در دسترس است.

نمونه‌های Authorization: Bearer در این صفحه از توکن دسترسی JWT که POST /v1/auth/login برمی‌گرداند استفاده می‌کنند (به Login نگاه کنید). کلیدهای API متفاوت‌اند: آن‌ها را در هدر X-API-Key بفرستید، نه به عنوان توکن Bearer.

فرمت کلیدکپی پیوند بخش

تمام کلیدهای API MailLand از این فرمت پیروی می‌کنند:

ml_{mode}{product}{stream?}_{random45chars}

• ml_: پیشوند تمام کلیدها
• حالت: p (Production) یا s (Sandbox)
• محصول: e (Sending)، i (Inbound)، v (Validation)
• جریان (فقط Sending): t (Transactional) یا m (Marketing)
• ۴۵ کاراکتر تصادفی

مثال‌ها:

ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...  → Production Sending Transactional
ml_sem_Xn7Kp2qR4tW9yB1cD6eF...  → Sandbox Sending Marketing
ml_pi_Mn5Jp8kL3rV6wA2xC4fG...   → Production Inbound
ml_pv_Qw9Er3tY6uI1oP5aS8dF...   → Production Validation

ویژگی‌های اعتبارنامهکپی پیوند بخش

هنگام ایجاد اعتبارنامه، موارد زیر را پیکربندی می‌کنید:

channels یک رشته واحد است و هرگز آرایه نیست. برای مجاز کردن هر دو کانال "channels": "Api, Smtp" بفرستید؛ ["Api", "Smtp"] با 400 رد می‌شود.

ایجاد اعتبارنامهکپی پیوند بخش

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Transactional",
    "product": "Sending",
    "mode": "Production",
    "stream": "Transactional",
    "channels": "Api",
    "scope": "AllDomains",
    "rateLimitPerHour": 5000,
    "rateLimitPerDay": 50000
  }'

{
  "id": "n4k9pq2rt8mwxa",
  "name": "Production Transactional",
  "key": "ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...",
  "keyPrefix": "ml_pet_Ab3Kx9mN",
  "product": "sending",
  "mode": "production",
  "stream": "transactional",
  "channels": "api",
  "scope": "allDomains",
  "sandboxBehavior": "logOnly",
  "rateLimitPerHour": 5000,
  "rateLimitPerDay": 50000,
  "isActive": true,
  "createdAt": "2026-02-17T10:00:00Z"
}

محدوده: محدودیت دامنهکپی پیوند بخش

به طور پیش‌فرض، اعتبارنامه‌ها می‌توانند از هر دامنه تأیید شده در فضای کاری شما ارسال کنند (AllDomains). برای محدود کردن اعتبارنامه به دامنه‌های خاص:

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing - notifications.com only",
    "product": "Sending",
    "mode": "Production",
    "stream": "Marketing",
    "channels": "Api",
    "scope": "SelectedDomains",
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

همچنین می‌توانید تخصیص دامنه‌ها را پس از ایجاد به‌روزرسانی کنید:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

محدودیت‌های IPکپی پیوند بخش

یک اعتبارنامه را به آدرس‌های IP یا محدوده‌های CIDR خاص محدود کنید:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/allowed-ips \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIps": [
      { "ipAddress": "203.0.113.10", "description": "Production server" },
      { "ipAddress": "198.51.100.0/24", "description": "Office network" }
    ]
  }'

هنگامی که محدودیت‌های IP پیکربندی شده‌اند، درخواست‌های API از IP های غیرمجاز 403 IP_NOT_ALLOWED برمی‌گردانند.

پیکربندی کانالکپی پیوند بخش

فیلد channels کنترل می‌کند که اعتبارنامه در کجا می‌تواند احراز هویت شود:

برای استفاده از اعتبارنامه برای SMTP relay، اطمینان حاصل کنید که Smtp در کانال‌ها گنجانده شده است. هنگام احراز هویت از طریق SMTP، از هر نام کاربری و کلید API به عنوان رمز عبور استفاده کنید.

چرخش کلیدکپی پیوند بخش

کلید API یک اعتبارنامه را بدون توقف با استفاده از یک دوره تنفس بچرخانید:

curl -X POST https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/rotate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodHours": 24
  }'

{
  "key": "ml_pet_Yn8Lq3rS5uW0zA4bC7dE...",
  "oldKeyExpiresAt": "2026-02-18T10:00:00Z"
}

در طول دوره تنفس (پیش‌فرض ۲۴ ساعت)، هر دو کلید قدیمی و جدید معتبر هستند. پس از دوره تنفس، کلید قدیمی از کار می‌افتد.

حالت Sandboxکپی پیوند بخش

"Sandbox" دو معنای جدا دارد که با هم ترکیب می‌شوند:

۱. اعتبارنامه‌های Sandbox (mode: Sandbox). برای توسعه، CI/CD و Staging. نتیجهٔ ارسال به sandboxBehavior اعتبارنامه بستگی دارد:

• LogOnly (پیش‌فرض): درخواست اعتبارسنجی و با 202 پاسخ داده می‌شود، اما چیزی تحویل نمی‌شود و پیامی ساخته نمی‌شود. پاسخ شامل isSandboxed: true، ‏sandboxReason: "credential_sandbox_mode" و messageIds خالی است.
• AllowListOnly: گیرندگانی که با فهرست مجاز Sandbox فضای کاری شما مطابقت دارند واقعاً تحویل می‌گیرند؛ بقیه در rejectedRecipients با دلیل recipient_not_in_sandbox_allowlist برمی‌گردند. اگر هیچ گیرنده‌ای مجاز نباشد، پاسخ همچنان 202 است با acceptedRecipients: [] و sandboxReason: "all_recipients_not_in_sandbox_allowlist".

در SMTP اعتبارنامهٔ Sandbox هرگز تحویل نمی‌دهد: پیام پذیرفته و ثبت می‌شود اما ارسال نمی‌شود، صرف‌نظر از sandboxBehavior.

۲. فضاهای کاری Sandbox. فضای کاری جدید با سطح تأیید Sandbox شروع می‌شود (به فضاهای کاری مراجعه کنید). تا زمان تأیید، ارسال حتی با اعتبارنامهٔ Production به گیرندگان فهرست مجاز محدود است. هر گیرندهٔ دیگر با 429 SENDING_BLOCKED رد می‌شود («Recipient '…' is not in sandbox allowlist. Add to allowlist or complete verification.»).

فهرست مجاز را در داشبورد از تنظیمات ← Sandbox Allow List مدیریت کنید. هر مورد یک آدرس ([email protected]) یا یک دامنهٔ کامل (*@example.com) است. همین فهرست با GET /v1/account/settings/sandbox-allowlist, POST /v1/account/settings/sandbox-allowlist, DELETE /v1/account/settings/sandbox-allowlist/{email} هم در دسترس است (توکن bearer داشبورد؛ POST فیلد email و description اختیاری می‌گیرد).

مدیریت اعتبارنامه‌هاکپی پیوند بخش

فهرست اعتبارنامه‌هاکپی پیوند بخش

curl "https://api.mail.land/v1/credentials?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

فیلتر بر اساس محصول یا حالت:

curl "https://api.mail.land/v1/credentials?product=Sending&mode=Production" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

به‌روزرسانی اعتبارنامهکپی پیوند بخش

curl -X PATCH https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "rateLimitPerHour": 10000,
    "isActive": false
  }'

تمام فیلدها اختیاری هستند: فقط آنچه می‌خواهید تغییر دهید را درج کنید.

حذف اعتبارنامهکپی پیوند بخش

curl -X DELETE https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

در صورت موفقیت 204 No Content برمی‌گرداند. اعتبارنامه‌های حذف شده بلافاصله احراز هویت را متوقف می‌کنند. حذف کلید را باطل می‌کند: اعتبارنامه همچنان در GET /v1/credentials با isActive: false فهرست می‌شود.

محدودیت‌های نرخکپی پیوند بخش

هر اعتبارنامه محدودیت‌های نرخ مستقل از سایر اعتبارنامه‌ها دارد:

هنگامی که محدودیت نرخ تجاوز می‌شود، API 429 با هدرهای X-RateLimit-* برمی‌گرداند:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708171800
Retry-After: 45

مراحل بعدیکپی پیوند بخش

• شروع سریع: اولین ایمیل خود را ارسال کنید
• REST API: مرجع کامل API ارسال
• SMTP Relay: احراز هویت با کلید API از طریق SMTP