Zamanlanmış E-postalar

Bir E-posta Zamanlama

POST https://api.mail.land/v1/transactional/scheduled

Schedule an email

curl -X POST https://api.mail.land/v1/transactional/scheduled \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "[email protected]",
      "name": "Your App"
    },
    "to": {
      "email": "[email protected]",
      "name": "Jane Doe"
    },
    "subject": "Your trial expires tomorrow",
    "html": "<h1>Hi Jane,</h1><p>Your free trial expires tomorrow. Upgrade now to keep access.</p>",
    "text": "Hi Jane, Your free trial expires tomorrow. Upgrade now to keep access.",
    "scheduledAt": "2026-02-18T09:00:00Z",
    "timeZone": "America/New_York",
    "tags": ["trial-expiry", "reminder"]
  }'

İstek Alanları

Alan	Tür	Zorunlu	Açıklama
`from`	object	Evet	Gönderici adresi (`email` ve isteğe bağlı `name`)
`to`	object	Evet	Tek alıcı (`email` ve isteğe bağlı `name`)
`subject`	string	Evet	E-posta konu satırı
`html`	string	Koşullu	HTML içeriği (`html` veya `text`'ten biri zorunludur)
`text`	string	Koşullu	Düz metin içeriği
`replyTo`	string	Hayır	Yanıt adresi
`cc`	array	Hayır	CC alıcıları (`email` ve isteğe bağlı `name`)
`bcc`	array	Hayır	BCC alıcıları (`email` ve isteğe bağlı `name`)
`attachments`	array	Hayır	Dosya ekleri (tek gönderimle aynı format)
`headers`	object	Hayır	Özel e-posta başlıkları
`tags`	array	Hayır	Analitik için etiketler
`scheduledAt`	datetime	Evet	Gönderim zamanı. Her zaman UTC olarak yorumlanır, `Z` veya açık bir ofsetle gönderin
`timeZone`	string	Hayır	IANA saat dilimi (örn. `America/New_York`). Yalnızca görüntüleme için saklanır ve geri döndürülür, gerçek gönderim zamanını etkilemez

scheduledAt gelecekte olmalı ve en fazla 7 gün ileriye ayarlanmalıdır. timeZone ayarlamak scheduledAt değerini o dilime dönüştürmez: zaman damgası her zaman UTC olarak okunur. Geçmişteki bir zaman 400 VALIDATION_FAILED ile reddedilir; 7 günden fazla ileri bir zaman 400 INVALID_REQUEST ile reddedilir ("Cannot schedule email more than 7 days in advance"). Aynı 7 günlük pencere, zamanlama burada, gönderme uç noktası üzerinden veya yeniden zamanlama ile oluşturulsa da geçerlidir.

Gönderme uç noktasından alan adı farklılıklarına dikkat edin: zamanlanmış e-postalar html/text kullanır (htmlContent/textContent değil) ve to tek bir nesnedir (dizi değil).

Yanıt

Durum: 201 Created

Schedule response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "scheduledAt": "2026-02-18T09:00:00Z",
  "timeZone": "America/New_York",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": null,
  "messageIds": [],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

Zamanlanmış E-posta Durumları

Durum	Açıklama
`pending`	Gelecekteki teslim için kuyruğa alındı
`processing`	Gönderim için işleniyor
`sent`	Başarıyla gönderildi
`failed`	Gönderim başarısız oldu (`error` alanını kontrol edin)
`cancelled`	Göndermeden önce iptal edildi

Zamanlanmış E-postaları Listeleme

GET https://api.mail.land/v1/transactional/scheduled?limit=20

List scheduled emails

curl https://api.mail.land/v1/transactional/scheduled?limit=20 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Duruma göre filtrele:

GET https://api.mail.land/v1/transactional/scheduled?status=pending

List scheduled emails by status

curl "https://api.mail.land/v1/transactional/scheduled?status=pending" \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

List response

{
  "items": [
    {
      "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "pending",
      "scheduledAt": "2026-02-18T09:00:00Z",
      "timeZone": "America/New_York",
      "to": "[email protected]",
      "recipientCount": 1,
      "subject": "Your trial expires tomorrow",
      "createdAt": "2026-02-17T10:00:00Z",
      "processedAt": null,
      "messageIds": [],
      "rejectedRecipients": [],
      "reasonCode": null,
      "error": null
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Sorgu parametreleri:

Parametre	Tür	Varsayılan	Açıklama
`cursor`	string	-	Önceki sayfanın `nextCursor` değerinden alınan opak imleç. İlk sayfa için belirtmeyin.
`limit`	int	20	Sayfa başına öğe (maks. 100)
`status`	string	-	Duruma göre filtrele: `pending`, `processing`, `sent`, `failed`, `cancelled`

Zamanlanmış Bir E-posta Alma

GET https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Get a scheduled email

curl https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Detail response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "sent",
  "scheduledAt": "2026-02-18T09:00:00Z",
  "timeZone": "America/New_York",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": "2026-02-18T09:00:02Z",
  "messageId": "t_a1b2c3d4e5f6...",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

Gönderdikten sonra yanıt processedAt (gönderildiği zaman) ve messageId (teslimat olaylarını izlemek için) içerir.

Zamanlanmış Bir E-postayı İptal Etme

DELETE https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Cancel a scheduled email

curl -X DELETE https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Başarıda 204 No Content döner. Yalnızca pending durumundaki e-postaları iptal edebilirsiniz. processing, sent veya failed durumundaki bir e-postayı iptal etmeye çalışmak 400 Bad Request döndürür.

Bir E-postayı Yeniden Zamanlama

Bekleyen bir e-postanın teslim zamanını değiştirin:

PATCH https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Reschedule an email

curl -X PATCH https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "2026-02-19T14:00:00Z",
    "timeZone": "Europe/London"
  }'

Reschedule response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "scheduledAt": "2026-02-19T14:00:00Z",
  "timeZone": "Europe/London",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": null,
  "messageIds": [],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

Aynı zamanlama kısıtlamaları geçerlidir: yeni zaman gelecekte ve şimdiden itibaren en fazla 7 gün ileride olmalıdır, aksi hâlde istek 400 INVALID_REQUEST ile reddedilir.

Saat Dilimi İşleme

timeZone sağlasanız da sağlamasanız da scheduledAt her zaman UTC olarak yorumlanır, Z veya açık bir ofsetle gönderin. timeZone, yanıtlarda yalnızca görüntüleme amacıyla saklanır ve geri döndürülür; MailLand scheduledAt değerini o dilime dönüştürmez. Görüntüleme için kaydedilmesini istiyorsanız IANA saat dilimi tanımlayıcılarını kullanın:

America/New_York
Europe/London
Asia/Tokyo
Australia/Sydney

Gönderme Uç Noktası Üzerinden Zamanlama

scheduledAt alanını ekleyerek e-postaları doğrudan normal gönderme uç noktası üzerinden de zamanlayabilirsiniz:

Schedule via send endpoint

{
  "from": { "email": "[email protected]" },
  "to": [{ "email": "[email protected]" }],
  "subject": "Scheduled email",
  "htmlContent": "<p>This will be sent later.</p>",
  "scheduledAt": "2026-02-18T09:00:00Z"
}

Gönderme uç noktasından dönen 202 yanıtı scheduleId ve scheduledAt içerir. Bu zamanlama, bu sayfadaki uç noktaların üzerinde çalıştığı aynı tür satırdır: doğrudan /v1/transactional/scheduled üzerinden oluşturulan bir zamanlama gibi, yukarıda açıklanan uç noktalarla listelenebilir, alınabilir, iptal edilebilir ve yeniden zamanlanabilir. 7 günlük pencere (yukarıdaki uyarıya bakın) burada da geçerlidir: 7 günden fazla ileri bir scheduledAt, 400 INVALID_REQUEST ile reddedilir.

Sonraki Adımlar

REST API: anlık e-posta gönderimi
Şablonlar: scheduledAt ile /v1/transactional/send üzerinden şablon kullanımı
Toplu Gönderim: toplu gönderimleri zamanlama

Zamanlanmış E-postalar

Bir E-posta ZamanlamaBölüm bağlantısını kopyala

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

YanıtBölüm bağlantısını kopyala

Zamanlanmış E-posta DurumlarıBölüm bağlantısını kopyala

Zamanlanmış E-postaları ListelemeBölüm bağlantısını kopyala

Zamanlanmış Bir E-posta AlmaBölüm bağlantısını kopyala

Zamanlanmış Bir E-postayı İptal EtmeBölüm bağlantısını kopyala

Bir E-postayı Yeniden ZamanlamaBölüm bağlantısını kopyala

Saat Dilimi İşlemeBölüm bağlantısını kopyala

Gönderme Uç Noktası Üzerinden ZamanlamaBölüm bağlantısını kopyala

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

Bu sayfada