mila
FiyatlandırmaKılavuzlarMCPSDKHakkımızda
Giriş yapKaydol
FiyatlandırmaKılavuzlarMCPSDKHakkımızda

Özellik kılavuzları

mila'nın API'si ve MCP sunucusuyla entegrasyon

REST API temel URL'si, Bearer API anahtarı kimlik doğrulaması, v1 kaynakları ve bir MCP istemcisini mila'nın barındırılan MCP sunucusuna nasıl bağlayacağınız.

Bu kılavuz neyi kapsıyor

mila panelindeki her şeyin arkasında belgelenmiş bir REST API var, ayrıca mila barındırılan bir Model Context Protocol (MCP) sunucusu da çalıştırıyor -- böylece bir yapay zeka asistanı veya ajan, hiçbir şeyi kopyala-yapıştır yapmanıza gerek kalmadan mila'nın belgelerini okuyabilir (ve ileride hesabınız üzerinde işlem de yapabilir). Bu kılavuz her ikisini de kapsıyor: REST API'yi doğrudan çağırmak ve bir MCP istemcisini mila'ya yönlendirmek.

REST API: temel URL ve kimlik doğrulama

API, https://api.mila.cx adresinde, /api/v1/... altında sürümlenmiş olarak yaşıyor. Her istek, bearer token olarak gönderilen bir API anahtarıyla doğrulanır:

Authorization: Bearer <api-anahtarınız>

Panelde Hesap > API Anahtarları'ndan bir anahtar oluşturun. Düz metin anahtar, oluşturduktan hemen sonra yalnızca BİR KEZ gösterilir -- hemen güvenli bir yere kopyalayın, çünkü mila sonrasında yalnızca anahtarın bir hash'ini saklar ve onu size tekrar gösteremez (yine de bir anahtarı her zaman iptal edip yenisini oluşturabilirsiniz).

Anahtar yetkileri (scope)

Bir anahtar oluştururken iki seçenek var:

Yetkiler rolün yerine geçmez, ona eklenir: bir işlemin gerçekleşmesi için hem anahtar sahibinin rolü hem de anahtarın yetkisi yeterli olmalıdır. Böylece bir sunucudaki dar yetkili anahtar sızsa bile, sahibinin panelde yapabildiği her şeyi yapamaz.

Scope'lar eklenmeden önce oluşturulmuş anahtarlar çalışmaya devam eder ve o günkü yetkilerini korur. Bu anahtarlar sonradan eklenen domains:transfer gibi yetkileri hiçbir zaman kazanmaz -- yeni bir yetki vermek için yeni bir anahtar oluşturmanız gerekir. Panelde bu anahtarlar "Eski anahtar (yetki öncesi)" olarak görünür.

Bununla neler yapabilirsiniz

v1 API'si, panelin kendisinin yönettiği aynı kaynakları kapsar, her biri bir alan adı altında sınırlandırılmış olarak:

Hızlı bir örnek -- alan adlarınızı listelemek:

curl "https://api.mila.cx/api/v1/domains" \
  -H "Authorization: Bearer $MILA_API_KEY"

Ve bir posta kutusu oluşturmak:

curl -X POST "https://api.mila.cx/api/v1/domains/<domain-id>/mailboxes" \
  -H "Authorization: Bearer $MILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "sales",
    "password_method": "password",
    "password": "guclu-ve-benzersiz-bir-parola",
    "may_send": true,
    "may_receive": true
  }'

Diğer her kaynak için -- tam endpoint'ler, method'lar ve parametreler -- API referansına bakın; her yazma işleminin tam istek gövdesi alanlarını gösteren curl, JavaScript ve Python'da çalıştırılabilir örnekler için kod örnekleri bölümüne bakın (ya da bir MCP'ye bağlı asistana sorun -- ikisini de talep üzerine getirebilir, bir sonraki bölüme bakın).

Anahtara güvenmeden önce kontrol edin

Yanlış hesabın anahtarı yanlış görünmez. Kimlik doğrulaması geçer ve GET /api/v1/domains dolu bir listeyle 200 döner -- ama başka birinin listesiyle. İlk gerçek gönderime kadar hiçbir şey hata vermez; bir mağaza için bu, ilk siparişin onay e-postası demektir.

Bu yüzden önce sorun:

curl "https://api.mila.cx/api/v1/account" \
  -H "Authorization: Bearer $MILA_API_KEY"

{
  "account": { "id": "org_...", "name": "INKLEDER", "slug": "inkleder" },
  "api_key": {
    "id": "key_...",
    "name": "Storefront",
    "prefix": "mila_ab12",
    "role": "admin",
    "scopes": ["mail:send"],
    "domain_access": "all"
  }
}

Bir kurulum ekranı yazıyorsanız account.name'i gösterin ve kullanıcıya onaylatın. Geliştirici olmayan birine "anahtar geçerli" demek hiçbir şey ifade etmez; şirketinin adını görmek her şeyi ifade eder. prefix, sırrı bir daha elleme gereği duymadan hangi anahtarın yapıştırıldığını göstermenizi sağlar; scopes ise bu anahtarın entegrasyonunuzun ihtiyacı olan şeyi yapıp yapamayacağını baştan söyler -- mail:send taşımayan bir anahtar sorunsuz kimlik doğrular, sonra her gönderimi reddeder.

Bu uç herhangi bir scope istemez. Kullanıcı hangi anahtarı yapıştırdıysa onunla sorulabilir; scope'lar var olmadan önce üretilmiş anahtarlar dahil (onlar da gerçekte taşıdıkları tam kümeyi bildirir, boş liste değil).

Bir gönderim reddedildiğinde

POST /api/v1/emails from adresini reddederse, sebebi güvenle söyleyebildiğinde yanıt gövdesi bir code taşır:

{
  "statusCode": 404,
  "code": "SENDER_DOMAIN_NOT_OWNED",
  "message": "This API key's account does not hold the domain of ..."
}

Bu tam olarak söylediği şey demektir: alan adı bu hesapta değil. Yanlış anahtar hatasının gönderim anında yakalanmış hâlidir ve kullanıcıya genel bir hata yerine kendi cümlelerinizle göstermeye değer.

Bir from'un reddedilmesinin diğer tüm sebepleri aynı 404'ü code olmadan döndürür, ve bu bilinçlidir: belirli bir posta kutusunun var olup olmadığını geçerli bir anahtarı olan hiç kimseye doğrulamayız.

API ile alan adı eklemek

Alan adı eklemek, şu sırayla ilerleyen dört adımlı bir yaşam döngüsüdür (1. ve 4. adımlar admin rolünde bir API anahtarı gerektirir):

  1. Oluşturun: POST /api/v1/domains, gövde { "name": "example.com" }. Alan adı pending durumunda döner. (Oluşturma, sistem genelinde 30 saniyede bir yeni alan adıyla sınırlıdır -- 429 aldıysanız yarım dakika bekleyip yeniden deneyin.)
  2. Yayınlanacak DNS kayıtlarını alın: GET /api/v1/domains/<domain-id>/dns-records, DNS sağlayıcınıza ekleyeceğiniz her şeyi döndürür -- vennyx-mila-verify= doğrulama TXT'i, MX, SPF, DKIM, DMARC ve istemci-autoconfig kayıtları.
  3. Kayıtların yayılıp yayılmadığını kontrol edin: GET /api/v1/domains/<domain-id>/diagnostics canlı bir DNS kontrolü çalıştırır ve her bloğu beklenen-mevcut karşılaştırmasıyla, geçti/geçmedi olarak raporlar.
  4. Etkinleştirin: POST /api/v1/domains/<domain-id>/activate. Sunucu DNS'i kendisi yeniden kontrol eder; doğrulama TXT'i ve MX kayıtları geçene kadar 422 (başarısız bloklar listesiyle) döner -- diğer kayıtlar teslimatı iyileştirir ama etkinleştirmeyi engellemez.

Aynı yaşam döngüsü SDK'da (client.domains.create/dnsRecords/diagnostics/activate) ve MCP üzerinden domains:write scope'uyla create_domain, check_domain_dns ve activate_domain araçları olarak da mevcuttur.

Bir alan adını başka bir organizasyona devretmek

Alan adını yanlış organizasyona eklediyseniz, POST /api/v1/domains/<domain-id>/transfer ile taşıyabilirsiniz. Gövde, hedef organizasyonun devir kodunu taşır:

{ "target_transfer_code": "<hedef-organizasyonun-devir-kodu>" }

Devir kodu hedef organizasyonun panelinde görünür ve yalnızca o organizasyonun paylaşabileceği bir sırdır -- yani bir anahtar çalınsa bile alan adı, hırsızın zaten sahip olmadığı bir yere gönderilemez.

Bu uç üç şey ister: anahtarda domains:transfer yetkisi, anahtar sahibinde owner rolü ve alan adının anahtarın organizasyonuna ait olması. Devir geri alınamaz; alan adı, posta kutuları ve içlerindeki postayla birlikte taşınır.

Alan adı silmek (ve vazgeçmek)

DELETE /api/v1/domains/<domain-id> silmeyi planlar, hemen yapmaz. Posta akışı anında durur; veriler yedi gün sonra kalıcı olarak silinir. O zamana kadar POST /api/v1/domains/<domain-id>/cancel-deletion ile vazgeçebilirsiniz ve posta kutuları içerikleriyle birlikte olduğu gibi geri gelir.

Posta kutusu olan bir alan adı için, panelde olduğu gibi adını geri yazmanız gerekir: ?confirm=example.com. Böylece tahmin edilmiş bir id'ye atılan çıplak bir DELETE kimsenin postasını götüremez.

Silme domains:delete yetkisi ister — domains:write bunu kapsamaz ve kapsamlardan önce üretilmiş anahtarlar buna hiçbir zaman sahip olamaz. Vazgeçme ise yalnızca domains:write ister: bir hatayı durdurmak, onu yapmaktan daha zor olmamalı.

Vazgeçmek alan adını yeniden yayına almaz; etkinleştirme ayrı bir adımdır.

@vennyx/mila SDK'sini kullanmak

İstekleri elle kurmak istemiyor musunuz? mila ayrıca resmi bir TypeScript/JavaScript istemcisi de yayınlıyor:

npm install @vennyx/mila

import { MilaClient } from '@vennyx/mila';

const client = new MilaClient({ apiKey: process.env.MILA_API_KEY! });
const domains = await client.domains.list();

Her istek ve yanıt uçtan uca tipli, hatalar elle ayrıştırılacak bir durum kodu yerine tek bir MilaApiError olarak dönüyor, ek dosya göndermek de sadece bir Buffer -- SDK, API'nin tel üzerinde beklediği base64 kodlamayı sizin için hallediyor. Tam kaynak listesi ve bir anlatım için mila'nın SDK sayfasına bakın.

Gerçek HTML e-posta mı gönderiyorsunuz? @vennyx/mila-react-template ile eşleştirin

Outlook, Gmail ve Apple Mail'de bozulmadan görünen HTML'i elle yazmak başlı başına bir iş. @vennyx/mila-react-template, tam olarak bunun için inşa edilmiş, ayrı bir bulletproof React component kütüphanesi -- SDK'nın kendi emails.send() metoduyla birlikte kullanın:

npm install @vennyx/mila-react-template

import { MilaEmailLayout, MilaButtonFluid, renderMilaEmail } from '@vennyx/mila-react-template';

function InviteEmail({ inviteUrl }: { inviteUrl: string }) {
  return (
    <MilaEmailLayout locale="tr" previewText="Davet edildiniz">
      <h1>Davet edildiniz</h1>
      <MilaButtonFluid href={inviteUrl} label="Daveti kabul et" />
    </MilaEmailLayout>
  );
}

const { html, text } = await renderMilaEmail(<InviteEmail inviteUrl="https://example.com/accept/abc" />);
await client.emails.send({
  from: 'merhaba@sizin-domaininiz.com',
  to: ['birisi@example.com'],
  subject: 'Davet edildiniz',
  html,
  text,
});

Her component gerçek, tüm büyük e-posta istemcilerine karşı test edilmiş HTML üretir -- Outlook-güvenli butonlar (arka planda VML), doğru dark-mode davranışı ve sizin için otomatik üretilen eşleşen bir düz-metin sürümü. Kutudan çıktığı gibi iki dilli (Türkçe/İngilizce) -- her component bir locale prop'u alıyor.

mila'nın MCP sunucusuna bağlanmak

mila, iki farklı amaca hizmet eden iki ayrı adreste barındırılan bir MCP sunucusu çalıştırır:

İkisi de Streamable HTTP taşımasını konuşur (POST üzerinden JSON-RPC) ve durumsuzdur (stateless) -- bağlantının kendisi dışında ekstra bir oturum kurulumu yoktur. Çoğu MCP istemcisi şuna benzer bir yapılandırma girdisi bekler (tam şekil istemciden istemciye değişir -- kendi istemcinizinkini kontrol edin):

{
  "mcpServers": {
    "mila": {
      "type": "streamable-http",
      "url": "https://docs-mcp.mila.cx"
    }
  }
}

Daha kapsamlı bir anlatım, örnek istemler ve tam araç kataloğu için mila'nın MCP sayfasına bakın.

Bir alan adı silinmeden de API'den kaybolabilir

GET /api/v1/domains yalnızca hesabınızın o an elinde tuttuğu alan adlarını listeler, GET /api/v1/domains/{id} ise diğerleri için 404 döner. Bir alan adının bu kümeden çıkmasının iki yolu vardır ve ikisi de tel üzerinde birebir aynı görünür:

Bu yüzden, başarıyla sorguladığınız bir alan adı kimliğinde aniden gelen 404'ü "ben sildim" değil "artık sizin değil" olarak okuyun. Durumu düzenli aralıklarla eşitleyen entegrasyonlar alan adını yeniden oluşturmak yerine bunu bir insana göstermelidir -- yeniden oluşturma başarısız olur, çünkü ad artık başkasına aittir.

Sırada ne var