Mailo API Kullanım Kılavuzu

Mailo API ile mail, SMS ve WhatsApp gönderimini entegre edin. RESTful API tasarımı, kolay kullanım ve güvenilir altyapı.

API Version: 1.0 Format: JSON Protocol: HTTPS WhatsApp Destekli

Giriş

Mailo API, uygulamalarınızdan kolayca mail ve SMS göndermenizi sağlayan RESTful bir API'dir. JSON formatında veri alışverişi yapar ve HTTPS üzerinden güvenli iletişim sağlar.

Özellikler

Kimlik Doğrulama

Mailo API, API Key tabanlı kimlik doğrulama kullanır. API Key'inizi HTTP header'ında göndermelisiniz.

API Key Alma

  1. Mailo admin paneline giriş yapın
  2. API Keys menüsüne gidin
  3. "Yeni API Key" butonuna tıklayın
  4. Gerekli bilgileri doldurup API Key'inizi oluşturun
  5. Oluşturulan API Key'i güvenli bir yere kaydedin (bir daha göremezsiniz!)

API Key Kullanımı

API Key'inizi üç farklı yöntemle gönderebilirsiniz:

1. HTTP Header (Önerilen)
X-API-Key: your_api_key_here
2. Query String
?api_key=your_api_key_here
3. POST Data
{"api_key": "your_api_key_here"}
Güvenlik Notu: API Key'lerinizi asla public repository'lerde paylaşmayın. Environment variable veya güvenli config dosyalarında saklayın.

Base URL

Tüm API istekleri aşağıdaki base URL üzerinden yapılır:

http://mailo.mekanode.com//api/

API Endpoints

Endpoint Metod Açıklama
/api/send-mail.php POST Mail gönderimi
/api/send-sms.php POST SMS gönderimi
/api/send-whatsapp.php POST WhatsApp mesajı gönderimi

Rate Limiting (Hız Sınırları)

Her API Key için günlük gönderim limiti vardır. Bu limit API Key oluşturulurken belirlenir ve her gece saat 00:00'da sıfırlanır.

Kalan Kota: Her başarılı istek sonucunda remaining_quota alanında kalan gönderim hakkınızı görebilirsiniz.

Limit Aşımı

Günlük limitiniz dolduğunda 401 Unauthorized hatası alırsınız:

{
  "success": false,
  "error": "Geçersiz API key veya günlük limit aşıldı"
}

Mail Gönderme

Mail göndermek için aşağıdaki endpoint'i kullanın:

POST /api/send-mail.php

Request Headers

Header Değer Açıklama
Content-Type application/json Zorunlu
X-API-Key your_api_key Zorunlu

Request Body Parametreleri

Parametre Tip Zorunluluk Açıklama
to string Zorunlu Alıcı email adresi (örn: user@example.com)
subject string Zorunlu Mail konusu
body string Zorunlu Mail içeriği (HTML veya düz metin)
is_html boolean Opsiyonel HTML mail mi? (varsayılan: true)
from_email string Opsiyonel Gönderici email (SMTP ayarlarından gelir)
from_name string Opsiyonel Gönderici adı

Başarılı Yanıt

200 OK 
{
  "success": true,
  "message": "Mail başarıyla gönderildi",
  "remaining_quota": 999
}

Hata Yanıtları

400 Bad Request 
{
  "success": false,
  "error": "'to' alanı gereklidir (telefon numarası)"
}
401 Unauthorized 
{
  "success": false,
  "error": "Geçersiz API key veya günlük limit aşıldı"
}
500 Internal Server Error 
{
  "success": false,
  "error": "Mail gönderilemedi. Lütfen daha sonra tekrar deneyin."
}

Mail Gönderme Örnekleri

cURL

curl -X POST http://mailo.mekanode.com//api/send-mail.php \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hoş Geldiniz!",
    "body": "
Merhaba!
Hoş geldiniz mesajı.
",
    "is_html": true
  }'

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$apiUrl = 'http://mailo.mekanode.com//api/send-mail.php';

$data = [
    'to' => 'recipient@example.com',
    'subject' => 'Hoş Geldiniz!',
    'body' => '<h1>Merhaba!</h1><p>Hoş geldiniz mesajı.</p>',
    'is_html' => true,
    'from_name' => 'Firma Adı'
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && $result['success']) {
    echo "Mail gönderildi! Kalan kota: " . $result['remaining_quota'];
} else {
    echo "Hata: " . $result['error'];
}
?>

JavaScript (Node.js)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const apiUrl = 'http://mailo.mekanode.com//api/send-mail.php';

const data = {
    to: 'recipient@example.com',
    subject: 'Hoş Geldiniz!',
    body: '
Merhaba!
Hoş geldiniz mesajı.
',
    is_html: true,
    from_name: 'Firma Adı'
};

axios.post(apiUrl, data, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log('Mail gönderildi!');
    console.log('Kalan kota:', response.data.remaining_quota);
})
.catch(error => {
    console.error('Hata:', error.response.data.error);
});

Python

import requests
import json

api_key = 'YOUR_API_KEY'
api_url = 'http://mailo.mekanode.com//api/send-mail.php'

data = {
    'to': 'recipient@example.com',
    'subject': 'Hoş Geldiniz!',
    'body': '
Merhaba!
Hoş geldiniz mesajı.
',
    'is_html': True,
    'from_name': 'Firma Adı'
}

headers = {
    'X-API-Key': api_key,
    'Content-Type': 'application/json'
}

response = requests.post(api_url, json=data, headers=headers)
result = response.json()

if response.status_code == 200 and result['success']:
    print(f"Mail gönderildi! Kalan kota: {result['remaining_quota']}")
else:
    print(f"Hata: {result['error']}")

SMS Gönderme

SMS göndermek için aşağıdaki endpoint'i kullanın:

POST /api/send-sms.php

Request Headers

Header Değer Açıklama
Content-Type application/json Zorunlu
X-API-Key your_api_key Zorunlu

Request Body Parametreleri

Parametre Tip Zorunluluk Açıklama
to string Zorunlu Alıcı telefon numarası (örn: 905xxxxxxxxx veya 0532xxxxxxx)
message string Zorunlu SMS mesajı içeriği
subject string Opsiyonel SMS konusu (mesajın başına eklenir)
Telefon Numarası Formatı: Telefon numaraları otomatik olarak formatlanır. 0 ile başlayan numaralar +90 ile değiştirilir.
Karakter Limiti: Standart SMS 160 karakter, Türkçe karakterli SMS 70 karakterdir. Bu limitler aşıldığında mesaj otomatik olarak çoklu SMS olarak gönderilir ve her SMS ayrı sayılır.

Başarılı Yanıt

200 OK 
{
  "success": true,
  "message": "SMS başarıyla gönderildi",
  "remaining_quota": 999
}

Hata Yanıtları

400 Bad Request 
{
  "success": false,
  "error": "'to' alanı gereklidir (telefon numarası)"
}
403 Forbidden 
{
  "success": false,
  "error": "Bu API key SMS gönderimi için yetkilendirilmemiş"
}

SMS Gönderme Örnekleri

cURL

curl -X POST http://mailo.mekanode.com//api/send-sms.php \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "905xxxxxxxxx",
    "message": "Doğrulama kodunuz: 123456",
    "subject": "Güvenlik Kodu"
  }'

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$apiUrl = 'http://mailo.mekanode.com//api/send-sms.php';

$data = [
    'to' => '905xxxxxxxxx',
    'message' => 'Doğrulama kodunuz: 123456',
    'subject' => 'Güvenlik Kodu'
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && $result['success']) {
    echo "SMS gönderildi! Kalan kota: " . $result['remaining_quota'];
} else {
    echo "Hata: " . $result['error'];
}
?>

JavaScript (Node.js)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const apiUrl = 'http://mailo.mekanode.com//api/send-sms.php';

const data = {
    to: '905xxxxxxxxx',
    message: 'Doğrulama kodunuz: 123456',
    subject: 'Güvenlik Kodu'
};

axios.post(apiUrl, data, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log('SMS gönderildi!');
    console.log('Kalan kota:', response.data.remaining_quota);
})
.catch(error => {
    console.error('Hata:', error.response.data.error);
});

Python

import requests

api_key = 'YOUR_API_KEY'
api_url = 'http://mailo.mekanode.com//api/send-sms.php'

data = {
    'to': '905xxxxxxxxx',
    'message': 'Doğrulama kodunuz: 123456',
    'subject': 'Güvenlik Kodu'
}

headers = {
    'X-API-Key': api_key,
    'Content-Type': 'application/json'
}

response = requests.post(api_url, json=data, headers=headers)
result = response.json()

if response.status_code == 200 and result['success']:
    print(f"SMS gönderildi! Kalan kota: {result['remaining_quota']}")
else:
    print(f"Hata: {result['error']}")

WhatsApp Gönderme

WhatsApp mesajı göndermek için aşağıdaki endpoint'i kullanın:

POST /api/send-whatsapp.php
Ön koşul: Kullandığınız API key'e admin panelden bir WhatsApp hesabı atanmış ve o hesap QR kod ile bağlanmış (durumu "Bağlı") olmalıdır. Aksi halde istek başarısız olur.

Request Headers

Header Değer Açıklama
Content-Type application/json Zorunlu
X-API-Key your_api_key Zorunlu

Request Body Parametreleri

Parametre Tip Zorunluluk Açıklama
to string Zorunlu Alıcı telefon numarası (örn: 905xxxxxxxxx veya 0532xxxxxxx)
message string Zorunlu WhatsApp mesajı içeriği
Telefon Numarası Formatı: Telefon numaraları otomatik olarak formatlanır. 0 ile başlayan numaralar 90 ile değiştirilir ve WhatsApp JID formatına çevrilir.
Best-effort kanal: WhatsApp entegrasyonu resmi olmayan bir protokol istemcisi (Baileys) üzerinden çalışır. Bağlantı WhatsApp tarafında herhangi bir anda kesilebilir; bu durumda admin panelden hesabın yeniden QR ile bağlanması gerekir. Yüksek hacimli/otomatik gönderimlerde numaranın askıya alınma riskini göz önünde bulundurun.

Başarılı Yanıt

200 OK 
{
  "success": true,
  "message": "WhatsApp mesajı başarıyla gönderildi",
  "remaining_quota": 999
}

Hata Yanıtları

400 Bad Request 
{
  "success": false,
  "error": "'to' alanı gereklidir (telefon numarası)"
}
403 Forbidden 
{
  "success": false,
  "error": "Bu API key WhatsApp gönderimi için yetkilendirilmemiş"
}
500 Internal Server Error 
{
  "success": false,
  "error": "WhatsApp mesajı gönderilemedi. Lütfen logları kontrol edin."
}

WhatsApp Gönderme Örnekleri

cURL

curl -X POST http://mailo.mekanode.com//api/send-whatsapp.php \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "905xxxxxxxxx",
    "message": "Merhaba, siparişiniz kargoya verildi!"
  }'

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$apiUrl = 'http://mailo.mekanode.com//api/send-whatsapp.php';

$data = [
    'to' => '905xxxxxxxxx',
    'message' => 'Merhaba, siparişiniz kargoya verildi!'
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && $result['success']) {
    echo "WhatsApp mesajı gönderildi! Kalan kota: " . $result['remaining_quota'];
} else {
    echo "Hata: " . $result['error'];
}
?>

JavaScript (Node.js)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const apiUrl = 'http://mailo.mekanode.com//api/send-whatsapp.php';

const data = {
    to: '905xxxxxxxxx',
    message: 'Merhaba, siparişiniz kargoya verildi!'
};

axios.post(apiUrl, data, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log('WhatsApp mesajı gönderildi!');
    console.log('Kalan kota:', response.data.remaining_quota);
})
.catch(error => {
    console.error('Hata:', error.response.data.error);
});

Python

import requests

api_key = 'YOUR_API_KEY'
api_url = 'http://mailo.mekanode.com//api/send-whatsapp.php'

data = {
    'to': '905xxxxxxxxx',
    'message': 'Merhaba, siparişiniz kargoya verildi!'
}

headers = {
    'X-API-Key': api_key,
    'Content-Type': 'application/json'
}

response = requests.post(api_url, json=data, headers=headers)
result = response.json()

if response.status_code == 200 and result['success']:
    print(f"WhatsApp mesajı gönderildi! Kalan kota: {result['remaining_quota']}")
else:
    print(f"Hata: {result['error']}")

Hata Kodları

Mailo API standart HTTP durum kodlarını kullanır:

Kod Açıklama Çözüm
200 Başarılı İstek başarıyla işlendi
400 Bad Request Gerekli parametreler eksik veya hatalı. Hata mesajını kontrol edin.
401 Unauthorized API key geçersiz veya günlük limit aşıldı. API key'inizi kontrol edin.
403 Forbidden API key'iniz bu servise yetkili değil. Servis tipini kontrol edin.
405 Method Not Allowed Sadece POST metodu desteklenir. GET yerine POST kullanın.
500 Internal Server Error Sunucu hatası. Lütfen daha sonra tekrar deneyin veya destek ile iletişime geçin.

En İyi Uygulamalar

1. API Key Güvenliği

2. Hata Yönetimi

3. Mail Gönderimi

4. SMS Gönderimi

5. WhatsApp Gönderimi

6. Performans

7. Monitoring ve Logging

Örnek: Retry Logic (PHP)

<?php
function sendMailWithRetry($apiKey, $data, $maxRetries = 3) {
    $apiUrl = 'https://example.com/api/send-mail.php';
    $attempt = 0;

    while ($attempt < $maxRetries) {
        $ch = curl_init($apiUrl);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'X-API-Key: ' . $apiKey,
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        // Başarılı
        if ($httpCode === 200) {
            return json_decode($response, true);
        }

        // 4xx hataları için retry yapma
        if ($httpCode >= 400 && $httpCode < 500) {
            return json_decode($response, true);
        }

        // 5xx hataları için retry yap
        $attempt++;
        if ($attempt < $maxRetries) {
            // Exponential backoff: 1s, 2s, 4s
            sleep(pow(2, $attempt - 1));
        }
    }

    return ['success' => false, 'error' => 'Max retry limit reached'];
}
?>

Webhooks (Yakında)

Webhook özelliği yakında eklenecektir. Webhook'lar ile mail ve SMS gönderim durumları hakkında gerçek zamanlı bildirim alabileceksiniz.

Planlanan Özellikler

Bilgi: Webhook özelliği için bizi takip edin!

Destek

API kullanımı ile ilgili sorularınız için: