Kampanyalar (toplu gönderim)

Kampanya, en çok 10.000 alıcıya kuyruklanan veya zamanlanan toplu gönderimdir. Kredi dispatch anında alıcı başına düşer; bastırma listesi gönderim yolunda uygulanır.

Uçlar (12)

POST/campaignsKampanya oluştur
GET/campaigns/{id}Durum + sayaçlar
GET/campaignsTarih aralığı listesi
GET/campaigns/{id}/reportAlıcı bazlı rapor
GET/campaigns/{id}/report/summary7'li özet rapor
GET/campaigns/{id}/report/funnelDönüşüm hunisi
GET/campaigns/{id}/recipientsAlıcı dökümü
GET/campaigns/{id}/recipients/exportCSV dökümü
POST/campaigns/{id}/cancelİptal et
POST/campaigns/{id}/pauseDuraklat
POST/campaigns/{id}/resumeDevam ettir
POST/campaigns/{id}/resend-to-unopenedAçmayanlara yeniden gönder

Kampanya oluştur

POST/public/v1/campaignsscopesend

Gövde

Ad	Tip	Zorunlu	Açıklama
`from`	string	hayır	Doğrulanmış kimlik adresi; boşsa varsayılan kimlik. Not: kampanya motoru From'u kimlikten türetir — domain kimliğinde özel local-part (`info@…`) korunmaz (bilinen v1 sınırı).
`subject`	string	evet	Konu.
`html`	string	evet	HTML gövde.
`recipients`	string[]	evet	Ham (raw) hedef listesi. En az 1, en çok 10.000 adres.
`scheduledAt`	string (ISO 8601)	hayır	Verilirse kampanya zamanlanır, boşsa hemen kuyruklanır.
`audience`	string	hayır	`members` \| `non_members`. Boşsa `non_members`.
`customerRef`	string	hayır	Ölçüm/ayıklama etiketi — bkz. customerRef. Max 64, `[A-Za-z0-9_-]`.

Kredi notu

Kampanyada kredi gönderim (dispatch) anında düşer — yanıttaki creditsCharged o ana kadar düşülen değerdir ve anında kuyruklanan kampanyada 0 olabilir. Kesin değeri GET /campaigns/{id} ile izleyin.

Alıcılar normalize edilir, tekilleştirilir; bastırma listesi gönderim yolunda uygulanır ve raporda suppressed olarak görünür.

Hatalar

POST/campaigns

curl -X POST https://api.mailmaks.com/mail/api/public/v1/campaigns \
  -H "Authorization: Bearer mm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "bulten@ornek.com",
    "subject": "Eylül bülteni",
    "html": "<h1>Merhaba</h1><p>Bu ay…</p>",
    "recipients": [
      "a@x.com",
      "b@y.com"
    ],
    "scheduledAt": "2026-09-20T07:00:00Z",
    "audience": "non_members",
    "customerRef": "hastane-42"
  }'

Yanıt200

{
  "campaignId": "…",
  "totalRecipients": 4980,
  "creditsCharged": 0
}

Durum + sayaçlar

GET/public/v1/campaigns/{id}scoperead

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

Hatalar

GET/campaigns/{id}

curl https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_… \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "campaignId": "…",
  "subject": "…",
  "status": "sending",
  "totalRecipients": 4980,
  "sentCount": 1200,
  "failedCount": 3,
  "suppressedCount": 17,
  "creditsCharged": 1200,
  "creditsRefunded": 0,
  "createdAt": "…",
  "scheduledAt": "…",
  "completedAt": null
}

Tarih aralığı listesi

GET/public/v1/campaignsscoperead

Yanıt sayfalı zarftır; items satırları GET /campaigns/{id} şeklindedir (PublicCampaignDto).

Sorgu parametreleri

Ad	Tip	Zorunlu	Açıklama
`from`	string (ISO 8601)	hayır	CreatedAt aralığı başlangıcı.
`to`	string (ISO 8601)	hayır	CreatedAt aralığı bitişi.
`page`	integer	hayır	Sayfa numarası, ≥ 1.
`pageSize`	integer	hayır	1–100 (varsayılan 20).

Hatalar

GET/campaigns

curl "https://api.mailmaks.com/mail/api/public/v1/campaigns?from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z&page=1&pageSize=20" \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "items": [
    {
      "campaignId": "…",
      "subject": "…",
      "status": "sending",
      "totalRecipients": 4980,
      "sentCount": 1200,
      "failedCount": 3,
      "suppressedCount": 17,
      "creditsCharged": 1200,
      "creditsRefunded": 0,
      "createdAt": "…",
      "scheduledAt": "…",
      "completedAt": null
    }
  ],
  "totalCount": 42,
  "page": 1,
  "pageSize": 20
}

Alıcı bazlı rapor

GET/public/v1/campaigns/{id}/reportscoperead

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

Sorgu parametreleri

Ad	Tip	Zorunlu	Açıklama
`page`	integer	hayır	Sayfa numarası, ≥ 1.
`pageSize`	integer	hayır	1–500 (varsayılan 50).

Alıcı iç durumu	Son olay	→ Rapor durumu
failed	(her değer)	`failed`
suppressed	(her değer)	`suppressed`
pending / sending	(her değer)	`pending`
sent	bounce	`bounced`
sent	complaint	`complained`
sent	reject	`failed`
sent	delivery / open / click	`delivered`
sent	send / (yok)	`pending` (gönderildi, teslim olayı henüz yok)

Hatalar

GET/campaigns/{id}/report

curl "https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_…/report?page=1&pageSize=50" \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "items": [
    {
      "email": "a@x.com",
      "status": "delivered"
    },
    {
      "email": "b@y.com",
      "status": "pending"
    }
  ],
  "totalCount": 4980,
  "page": 1,
  "pageSize": 50
}

7'li özet rapor

GET/public/v1/campaigns/{id}/report/summaryscoperead

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

opened/clicked: tekil alıcı sayıları. unsubscribed: bu kampanyadan kullanılan abonelikten-çıkma sayısı. replied: kampanyaya bağlı yanıt thread'i sayısı.
Yol notu: GET /campaigns/{id}/report v1'in ilk gününden beri sayfalı alıcı listesi döner ve kırılamaz; özet rapor bu yüzden /report/summary yolundadır.

Hatalar

GET/campaigns/{id}/report/summary

curl https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_…/report/summary \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "sent": 4960,
  "delivered": 4700,
  "bounced": 180,
  "complained": 4,
  "opened": 2100,
  "clicked": 460,
  "unsubscribed": 12,
  "failed": 20,
  "replied": 8
}

Dönüşüm hunisi

GET/public/v1/campaigns/{id}/report/funnelscoperead

Oranlar 0–1 aralığında ondalıktır. bounced kalıcı/geçici kırılımıyla döner.

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

Hatalar

GET/campaigns/{id}/report/funnel

curl https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_…/report/funnel \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "totalRecipients": 5000,
  "sent": 4960,
  "delivered": 4700,
  "opened": 2100,
  "clicked": 460,
  "bounced": {
    "permanent": 150,
    "transient": 30
  },
  "complained": 4,
  "unsubscribed": 12,
  "failed": 20,
  "suppressed": 17,
  "deliveryRate": 0.9476,
  "openRate": 0.4468,
  "clickRate": 0.219
}

Alıcı dökümü

GET/public/v1/campaigns/{id}/recipientsscoperead

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

Sorgu parametreleri

Ad	Tip	Zorunlu	Açıklama
`page`	integer	hayır	Sayfa numarası, ≥ 1.
`pageSize`	integer	hayır	1–500 (varsayılan 20).
`status`	string	hayır	Ham alıcı durumu filtresi: `pending` \| `sending` \| `sent` \| `failed` \| `suppressed`.
`search`	string	hayır	E-posta içinde arar.

status filtresi ve satır değeri ham alıcı durumudur: pending | sending | sent | failed | suppressed — /report'un türetilmiş union'ından bilinçli farklı (detay/tanı görünümü).
Boş alanlar (failReason, sesMessageId, olay zamanları…) yazılmaz. search e-posta içinde arar.

Hatalar

GET/campaigns/{id}/recipients

curl "https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_…/recipients?page=1&pageSize=20&status=failed&search=%40gmail" \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "items": [
    {
      "email": "a@x.com",
      "status": "sent",
      "failReason": null,
      "sesMessageId": "…",
      "lastEventType": "delivery",
      "lastEventAt": "…",
      "openedAt": "…",
      "clickedAt": "…",
      "bounceType": null
    }
  ],
  "totalCount": 3,
  "page": 1,
  "pageSize": 20
}

CSV dökümü

GET/public/v1/campaigns/{id}/recipients/exportscoperead

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

Sorgu parametreleri

Ad	Tip	Zorunlu	Açıklama
`format`	string	evet	Yalnız `csv`; başka değer 422 `validation_error`.

Yanıt text/csv; charset=utf-8, UTF-8 BOM'lu (Excel Türkçe karakterleri doğru açar), streaming (boyut sınırı yok).
Başlık satırı: email,status,failReason,sesMessageId,lastEventType,lastEventAt,openedAt,clickedAt,bounceType. RFC 4180 kaçış + formül enjeksiyonu savunması uygulanır.
Kampanya yoksa 404 not_found.

Hatalar

GET/campaigns/{id}/recipients/export

curl -o alicilar.csv "https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_…/recipients/export?format=csv" \
  -H "Authorization: Bearer mm_live_..."

Yanıt200 · text/csv; charset=utf-8

email,status,failReason,sesMessageId,lastEventType,lastEventAt,openedAt,clickedAt,bounceType
a@x.com,sent,,…,delivery,2026-09-15T09:31:02Z,,,
b@y.com,failed,mailbox_full,,,,,,

İptal et

POST/public/v1/campaigns/{id}/cancelscopesend

Kampanyayı iptal eder; başarıda kampanyanın güncel public görünümünü döner.

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

Hatalar

POST/campaigns/{id}/cancel

curl -X POST https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_…/cancel \
  -H "Authorization: Bearer mm_live_..."

Kampanyanın güncel public görünümü200

{
  "campaignId": "…",
  "subject": "…",
  "status": "sending",
  "totalRecipients": 4980,
  "sentCount": 1200,
  "failedCount": 3,
  "suppressedCount": 17,
  "creditsCharged": 1200,
  "creditsRefunded": 0,
  "createdAt": "…",
  "scheduledAt": "…",
  "completedAt": null
}

Duraklat

POST/public/v1/campaigns/{id}/pausescopesend

Gönderimi duraklatır; başarıda kampanyanın güncel public görünümünü döner.

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

Hatalar

POST/campaigns/{id}/pause

curl -X POST https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_…/pause \
  -H "Authorization: Bearer mm_live_..."

Kampanyanın güncel public görünümü200

{
  "campaignId": "…",
  "subject": "…",
  "status": "sending",
  "totalRecipients": 4980,
  "sentCount": 1200,
  "failedCount": 3,
  "suppressedCount": 17,
  "creditsCharged": 1200,
  "creditsRefunded": 0,
  "createdAt": "…",
  "scheduledAt": "…",
  "completedAt": null
}

Devam ettir

POST/public/v1/campaigns/{id}/resumescopesend

Duraklatılmış kampanyayı sürdürür; başarıda kampanyanın güncel public görünümünü döner.

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

Hatalar

POST/campaigns/{id}/resume

curl -X POST https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_…/resume \
  -H "Authorization: Bearer mm_live_..."

Kampanyanın güncel public görünümü200

{
  "campaignId": "…",
  "subject": "…",
  "status": "sending",
  "totalRecipients": 4980,
  "sentCount": 1200,
  "failedCount": 3,
  "suppressedCount": 17,
  "creditsCharged": 1200,
  "creditsRefunded": 0,
  "createdAt": "…",
  "scheduledAt": "…",
  "completedAt": null
}

Açmayanlara yeniden gönder

POST/public/v1/campaigns/{id}/resend-to-unopenedscopesend

Açmayan alıcılara yeni (türev) bir kampanya oluşturur — yanıttaki campaignId türevin id'sidir. subject verilmezse "Re: <orijinal konu>" türetilir ("Re: Re:" birikmez). Açmayan alıcı yoksa 422 no_unopened_recipients.

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Kampanya id'si.

Gövde

Ad	Tip	Zorunlu	Açıklama
`subject`	string	hayır	Türev kampanyanın konusu (gövde opsiyonel).

Hatalar

POST/campaigns/{id}/resend-to-unopened

curl -X POST https://api.mailmaks.com/mail/api/public/v1/campaigns/cmp_…/resend-to-unopened \
  -H "Authorization: Bearer mm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Hatırlatma: Eylül bülteni"
  }'

Kampanyanın güncel public görünümü200

{
  "campaignId": "…",
  "subject": "…",
  "status": "sending",
  "totalRecipients": 4980,
  "sentCount": 1200,
  "failedCount": 3,
  "suppressedCount": 17,
  "creditsCharged": 1200,
  "creditsRefunded": 0,
  "createdAt": "…",
  "scheduledAt": "…",
  "completedAt": null
}