API

SMTP üzerinden gönderme

POST /emails ile aynı gönderim, SMTP konuşan yazılımlar için.

Bağlantı

Bir SMTP sunucusu üzerinden posta gönderen her şey OpenEmail üzerinden gönderebilir: bir framework'ün e-posta bileşeni, bir CMS, bir izleme aracı, bir yazıcı. Kullanıcı adı olarak openemail, parola olarak da bir API anahtarıyla oturum açın. Anahtarın emails:send kapsamına sahip olması gerekir ve teslim ettiği bir ileti, o anahtarla yapılan POST /emails ile aynı gönderimdir.

Ayar	Değer
Sunucu	`smtp.openemail.uk`
Port	SSL/TLS ile `465` ya da STARTTLS ile `587`
Kullanıcı adı	`openemail`
Parola	`emails:send` kapsamına sahip bir API anahtarı
Oturum	Çoğu yazılımın normal parola dediği PLAIN ya da LOGIN

Şifresiz hiçbir şey kabul edilmez ve 587 numaralı bağlantı noktasında oturum açma ancak STARTTLS'ten sonra açılır. Bir API anahtarı yalnızca göndermek için oturum açar. Bir posta kutusunu IMAP ya da POP3 üzerinden okumak için uygulama parolası gerekir.

Test iletisi gönderme

Bir iletiyi message.eml olarak kaydedin ve curl ile teslim edin. From, anahtarın adına gönderim yapabileceği bir adres olmalıdır.

message.eml

From: Acme <[email protected]>To: [email protected]Subject: Hello over SMTPMessage-ID: <[email protected]> It works.

Port 465

curl --url "smtps://smtp.openemail.uk:465" \  --user "openemail:$OPENEMAIL_API_KEY" \  --mail-from "[email protected]" \  --mail-rcpt "[email protected]" \  --upload-file message.eml --crlf

Port 587

curl --ssl-reqd --url "smtp://smtp.openemail.uk:587" \  --user "openemail:$OPENEMAIL_API_KEY" \  --mail-from "[email protected]" \  --mail-rcpt "[email protected]" \  --upload-file message.eml --crlf

Kabul edilen bir iletiye verilen yanıt 250 2.0.0 OK queued as ve ardından iletinin kimliğidir. Bu kimlik GET /emails/{id} çağrısının aldığı kimliktir, bu yüzden ileti, olayları ve izlemesi diğer her gönderimdeki gibi okunur.

Bir ileti nasıl gönderime dönüşür

İleti bir REST gönderimiyle aynı yoldan okunup gönderilir, bu yüzden parçalarından yeniden kurulur ve baytı baytına aktarılmaz.

İletide	Gönderimde
From	`from`. Zorunludur ve anahtarın denetlendiği gönderen budur. `MAIL FROM` içindeki adresin yalnızca bulunması yeterlidir.
RCPT TO	İletinin kime teslim edileceği, en fazla 50. `To` içinde adı geçen bir alıcı `to`, `Cc` içinde adı geçen bir alıcı `cc`, ikisinde de adı geçmeyen ise `bcc` olur. En az biri `To` içinde olmalıdır.
Reply-To	`replyTo`, ilk adres.
Subject	`subject`.
Metin ve HTML bölümleri	`text` ve `html`. HTML'in `cid:` olarak kullandığı görsel, göründüğü yere gömülür.
Ekler	`attachments`: en fazla 20 dosya ve toplam 5 MB.
Diğer başlıklar	`X-`, `List-`, Precedence, Auto-Submitted, Importance, Priority ve Feedback-ID korunur. Diğer bütün başlıklar dışarıda bırakılır.
X-OpenEmail-Stream	`stream`: `transactional` ya da `broadcast`. Başlık, ileti yola çıkmadan önce kaldırılır.

Geçerli olanlar

Bir REST gönderiminin tabi olduğu her şey burada da geçerlidir, çünkü yol tektir.

Anahtarın kapsamları ve sınırlı olduğu adresler ile alan adları.
Gönderen denetimi: From, gönderim yapabilen bir alan adındaki ve anahtarın adına gönderim yapabileceği bir adrestir.
Çalışma alanının gönderim kotası ve engelleme listesi.
Gönderildiği adresin imzası ile açılma ve tıklama izlemesi, ne signature ne de tracking ayarlayan bir REST gönderimindeki gibi.
Şerit: toplu gönderim şeridi duraklatılmışken X-OpenEmail-Stream: broadcast taşıyan bir ileti reddedilir.
İletiyi 250 yanıtındaki kimlikle adlandıran webhook'lar ve teslim olayları.

Yeniden denemeler

Message-ID taşıyan bir ileti bir kez gönderilir. Aynı Message-ID aynı alıcılar için yeniden teslim edilirse yanıt ilk iletinin kimliğiyle gelir ve hiçbir şey gönderilmez. Böylece kopan bir bağlantıdan sonra yeniden deneyen yazılım onu iki kez gönderemez. Başka alıcılar için aynı ileti ayrı bir gönderimdir. Bkz. İdempotanlık.

Yanıtlar ve sınırlar

Yanıt	Ne zaman
250 2.0.0	İleti kuyruğa alınır ve ardından kimliği gelir.
535 5.7.8	Oturum açma başarısız oldu: yanlış, iptal edilmiş ya da süresi dolmuş bir anahtar, `emails:send` taşımayan bir anahtar ya da başka bir kullanıcı adıyla verilen bir API anahtarı.
452 4.5.3	Tek iletide 50'den fazla alıcı. Posta yazılımı kalanları kendiliğinden başka bir iletiyle gönderir.
552 5.3.4	İleti 25 MB'tan büyük.
550 5.6.0	İleti yazıldığı haliyle gönderilemez: `From` yok, `To` içinde kimse yok, ekler çok fazla ya da çok büyük, şerit bilinmiyor. Hangisi olduğunu metin söyler.
550 5.7.1	Gönderim reddedildi: anahtar o adres adına gönderim yapamaz, alan adı henüz gönderim yapamıyor ya da toplu gönderim şeridi duraklatılmış.
452 4.7.0	Çalışma alanının gönderim kotası tükendi.
451 4.7.1	Bir anahtardan bir dakikada 300'den fazla ileti. Posta yazılımı bekler ve yeniden dener.
451 4.3.0	Bizim tarafımızda bir hata. Kısa süre sonra yeniden deneyin.

Gönderecek bir şeyi olmayan bağlantı beş dakika sonra kapanır. Tek bir bağlantı art arda istenildiği kadar ileti taşıyabilir.

İstek günlüğünde

Bir anahtarın teslim ettiği her ileti, istek günlüğünde bir satırdır. Yöntemi SMTP, yolu /emails, durumu ise bir REST gönderiminin alacağı durumdur: kuyruğa alındığında 202, reddedildiğinde aynı hata code değeriyle 403, 422 ya da 429. GET /keys/{id}/requests?path=/emails bunları REST gönderimlerinin yanında listeler. Gerçek bir anahtarla başarısız olan bir oturum açma, o anahtarın etkinliğinde görünür.