PHP

E-posta gönderme

`emails->send`: tek mesaj, şimdi veya sonra.

emails->send

send_email.php

$email = $client->emails->send([    'from' => ['email' => '[email protected]', 'name' => 'Acme Billing'],    'to' => ['[email protected]', 'Grace <[email protected]>'],    'cc' => '[email protected]',    'bcc' => [['email' => '[email protected]']],    'replyTo' => '[email protected]',    'subject' => 'Your September invoice',    'html' => '<p>Invoice attached.</p>',    'text' => 'Invoice attached.',    'headers' => ['X-Campaign' => 'invoices'],    'attachments' => [['filename' => 'invoice.pdf', 'content' => new \SplFileInfo('invoice.pdf')]],    'threadId' => 'CAHk7pQ2x9LmZ4-mail.example.com',    'scheduledAt' => 'PT1H',    'tags' => ['order' => '4021'],    'tracking' => ['opens' => true, 'clicks' => true],]); echo $email['id'], ' ', $email['status'], PHP_EOL;

to, cc ve bcc bir alıcı ya da alıcılardan oluşan bir liste alır; tek bir alıcı sizin için sarılır. Her biri çıplak bir adres, Name <addr@host> ya da email ve name içeren bir dizi olabilir.

İleti, API'nin alan adlarıyla anahtarlanmış tek bir dizidir; replyTo ve scheduledAt alanlarının camelCase kalmasının nedeni budur. idempotencyKey: ve apiKey: ise çağrının adlandırılmış argümanlarıdır ve asla iletinin parçası değildir. Daha önce kurduğunuz bir iletinin tek bir alanını değiştirmek için onu yeni bir diziye yayın: $client->emails->send([...$message, 'subject' => 'Re: your invoice']) diğer tüm alanları korur ve konuyu değiştirir.

Parametreler

fromstring or arrayzorunlu: Gönderen. Çıplak bir adres, `Name <addr@host>` ya da `email` ve `name` içeren bir dizi. Bu anahtarın adına gönderebileceği bir adres olmalıdır; aksi hâlde çağrı 403 `from_address_forbidden` fırlatır. Yedek bir gönderen yoktur, bu yüzden bir gönderim her zaman hangi adresle çıkacağını belirtir.
tostring or arrayzorunlu: Bir alıcı ya da alıcılardan oluşan bir liste; tek bir alıcı sizin için sarılır. `to`, `cc` ve `bcc` toplamında en fazla 50; daha fazlası 422 `too_many_recipients` verir.
ccstring or array: 50 alıcı sınırına dahil edilir.
bccstring or array: Başka birinin aldığı baytlarda asla adı geçmez, çünkü her alıcı için ayrı bir zarf iletilir. Bu alıcılar da 50 sınırına dahildir.
replyTostring or array: Tek bir adres; Reply-To başlığı olarak gönderilir.
subjectstring: En fazla 998 karakter; bu, RFC 5322 satır sınırıdır. Varsayılan olarak boştur ve boş bir konu, şablonun ya da taslağın konusuna geri döner.
htmlstring: `html`, `text`, `draftId` veya `template` alanlarından biri zorunludur. `html` ve `text` birlikte verildiğinde alıcıların gördüğü HTML'dir. En fazla 1.000.000 karakter.
textstring: Düz metin kısmı, en fazla 1.000.000 karakter.
templatearray: Kayıtlı bir şablonu sunucu tarafında işleyin: bir kimlik ya da slug alan `id` ile isteğe bağlı `version` (bir int), `props` ve `slots` içeren bir dizi. `version` bir revizyonu sabitler. İstek kabul edildiğinde yayımlanmış olanı kullanmak için belirtmeyin. Bilinmeyen ya da eksik bir prop, iletide boşluk bırakmak yerine 422 verir.
draftIdstring: Kaydedilmiş bir taslağı yazıldığı hâliyle bu zarfla gönderin. `template` ya da `translate` ile birlikte kullanılamaz.
headersarray: Başlık adından dize değere eşleme; yalnızca `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority ve Feedback-ID ile sınırlıdır. Taşıma katmanının kendisinin ayarladığı her şey sessizce atılmaz, 422 `reserved_header` ile reddedilir.
attachmentsarray: Bir liste; her öğe `filename`, `content` ve isteğe bağlı `contentType` içeren bir dizi ya da yalnızca `fileId` içeren ve çalışma alanında zaten bulunan bir dosyayı (örneğin `files->upload` ile yüklenmiş bir dosyayı) belirten bir dizidir. `content` base64'tür: `fopen` ile açılmış bir akış, bir `SplFileInfo` ya da bir PSR-7 akışı sizin için okunur ve kodlanır; bir dize ise zaten base64 olmalıdır. En fazla 20 dosya; satır içi dosyalar çözüldükten sonra toplamda 5 MB ile sınırlıdır. Kayıtlı bir dosya daha büyük olabilir ve bir indirme bağlantısı olarak iletilir.
attachmentDeliverystring: `mime`, `link` veya `auto`. `auto`, etkin bir dosya alan adı olan bir alan adında dosyaları 2 MB'ı aştıklarında indirme bağlantısı olarak, aksi hâlde mesajın içinde taşır. Belirtilmezse posta kutusu ayarı geçerli olur ve onun varsayılanı `auto`'dur.
threadIdstring: Var olan bir konuşma dizisine yanıt verir. Taşıma katmanı In-Reply-To ve References başlıklarını yazar.
scheduledAtDateTimeInterface or string: UTC'de bir ISO 8601 anı olarak gönderilen bir `DateTimeInterface`, dize olarak bir ISO 8601 anı ya da `PT1H` gibi bir süre. En fazla bir yıl ileri, asla geçmişte değil. `cancellableForSeconds` ile birlikte kullanılamaz. `2027-01-01` gibi saat içermeyen bir tarih dizesi o günün UTC gece yarısı olarak okunur; bu yüzden saat önemliyse bir an geçirin.
cancellableForSecondsint: 0 ile 900 arası. Anlık bir gönderimde geri alma penceresi: yazma ekranının geri alma mekanizması, koda gömülmek yerine dışarı açılmış hâli.
tagsarray: En fazla 10 etiket; anahtarlar harf, rakam, `_` ya da `-` karakterlerinden 1 ile 64 karakter, dize değerler en fazla 256 karakter. Her okumada aynen geri döndürülür ve asla yorumlanmaz.
signaturebool: Bu iletinin gönderen adresin imzasını taşıyıp taşımayacağı: adresin kendi imzası, yoksa bir catch-all'un yakaladığı adres için catch-all'un imzası, o da yoksa OpenEmail alt bilgisi (o adres kapatmadıysa). Belirtilmezse `html` gövde yazıldığı gibi imzasız gider, yalnızca `text` olan gövde ise imzayı taşır. Bir programın birinin adına gönderdiği postada, örneğin bir makbuz, parola sıfırlama ya da özet için false verin; bunların hiçbiri altında bir kişinin imzasını istemez. Şablon gönderimleri ve şifreli gönderimler hiçbir zaman imza taşımaz.
trackingarray: İsteğe bağlı, her biri bool olan `opens` ve `clicks` içeren bir dizi: bu iletiye açılma pikseli eklenip bağlantılarının yeniden yazılıp yazılmayacağı. İletinin gönderildiği adres (ya da onu yakalayan catch-all) için izleme açılmadıkça kapalıdır ve burada belirtilen her iki anahtar da, adres nasıl ayarlanmış olursa olsun o tek ileti için kararı verir.
translatearray: Alıcının dilinde gönderir: `to` ve isteğe bağlı `from`, `subject` ve `includeOriginal` içeren bir dizi. `to` bir kod, İngilizce bir ad veya dilin kendi adını alır; `subject` ve `includeOriginal` varsayılan olarak true'dur. İstek kabul edildiğinde kesinleşir, dolayısıyla zamanlanmış bir ileti onaylanan sözcükleri taşır. `draftId` ile birlikte reddedilir.
idempotencyKeystring: İletinin bir alanı değil, çağrının adlandırılmış bir argümanı. Bu gönderim için kendi anahtarınız; harf, rakam, `_`, `.`, `:` ya da `-` karakterlerinden oluşan 1 ile 255 karakter. Anahtar yoksa istemci her çağrı için bir anahtar üretir, böylece kendi yeniden denemeleri asla iki kez göndermez; anahtar varsa başka bir süreçte yeniden çalışan bir gönderim tekrarlanmak yerine yeniden oynatılır.
apiKeystring: Bu da adlandırılmış bir argümandır. Birkaç çalışma alanı adına gönderim yapan bir süreç için, istemcinin anahtarı yerine bu anahtarla gönderir.

Yanıt

API'nin camelCase adlarıyla anahtarlanmış bir dizi; bu yüzden $email['status'] durumu okur.

idstring: Gönderim kimliği: `msg_` ve ardından 24 onaltılık karakter. Bunu `get`, `cancel`, `reschedule` ve `getTracking` için kullanın.
statusstring: queued, scheduled, sending, sent, partial, bounced, cancelled veya failed. Çağrının dönmüş olmasına değil buna bakın: anında bir gönderim istek içinde sevk edilir ve genellikle `sent`, `partial` ya da `failed` olarak döner; bekletilen bir gönderim ise `queued` ya da `scheduled` olarak döner. `partial` kendi başına bir durumdur: bazı alıcılar iletiyi almıştır ve bu geri alınamaz, dolayısıyla yeniden denemek yanlış, başarısızlık bildirmek ise yalandır.
modestring: `live` ya da `test`: iletiyi hangi tür anahtarın gönderdiği. Bir test gönderimi kaydedilir ve asla iletilmez. Durumu `sent` olarak görünür ve `transport` değeri `test` olur; bu yüzden doğrulamayı bir gelen kutusu üzerinde değil, yanıt üzerinde yapın.
fromstring: Gerçekte yetkilendirilen ve ağa konan adres; bu her zaman istenen adres değildir.
subjectstring or null: Gönderildiği hâliyle.
messageIdstring or null: RFC 5322 Message-ID. MIME oluşana kadar null. Gönderim hizmeti başlığı çıkışta yeniden yazar; bu yüzden hiçbir geri dönme ya da teslimat raporu bu değeri taşımaz. Bir olay `id` ile geri gelir.
threadIdstring or null: Düştüğü konuşma dizisi.
transportstring or null: İletinin nasıl çıktığı. Sevk edilene kadar null.
attemptsint: Gönderimin kaç kez denendiği.
lastErrorstring or null: Son denemenin neden başarısız olduğu, olduğu gibi.
scheduledAtstring or null: İletinin gitmesi gereken ISO 8601 anı.
cancellableUntilstring or null: Şu an bu andan önce olduğu sürece `cancel` hâlâ çalışır.
sentAtstring or null: İletinin çıktığı ISO 8601 anı.
tagsarray: Gönderdiğiniz şey, aynen geri döndürülür.
sourcestring: composer, api, mcp, ai veya queue: hangi yüzeyin istediği. `api` bu istemcidir.
createdAtstring: Kaydın yazıldığı ISO 8601 anı.
replayedbool: Bir Idempotency-Key zaten var olan bir gönderimle eşleştiğinde true. Yeni hiçbir şey gönderilmedi ve bu, asıl iletinin şu anki hâlidir.
translationarray: Yalnızca çevrilmiş bir iletide ve yalnızca saklanan isteğin tamamının taşındığı yerlerde bulunur: bu yanıtta ve `get` içinde. Tam dil satırları yerine kodlarla birlikte `language`, `languageName`, `detectedSourceLanguage`, `subject` ve `includeOriginal` içerir. Bir liste satırında asla bulunmaz, bu yüzden orada olmaması hiçbir şey ifade etmez.

Alıcının dilinde

translate, mesajı gitmeden önce bir başkasının dilinde yazar. Gövde ve (siz kapatmadıkça) konu, API isteği kabul ettiğinde çevrilir ve ortaya çıkan metin gidenin ta kendisidir: üretilemeyen bir çeviri, mesajı sizin yazdığınız dilde göndermek yerine gönderimi reddeder.

translate.php

$email = $client->emails->send([    'from' => '[email protected]',    'to' => '[email protected]',    'subject' => 'Your September invoice',    'html' => '<p>Invoice attached. Payment is due on the 14th.</p>',    'translate' => ['to' => 'de'],]); print_r($email['translation'] ?? []);

Bu durumda $email['translation'] içinde language değeri de, languageName değeri German, detectedSourceLanguage değeri en olur; subject ve includeOriginal ise ikisi de true'dur.

Bunu gitmeden önce kimse okumadı. emails->translate aynı gidiş dönüşün bir adım önce durdurulmuş hâlidir. Sonucu bir kişiye gösterin, değiştirmesine izin verin, ardından onayladığını çağrıda hiç translate olmadan gönderin. Onu yeniden geçirmek metni ikinci kez çevirir ve kişinin düzenlemelerini atar.

preview_translation.php

$preview = $client->emails->translate([    'subject' => 'Your September invoice',    'html' => '<p>Invoice attached. Payment is due on the 14th.</p>',    'to' => 'de',]); echo $preview['language']['native'], PHP_EOL, $preview['subject'], PHP_EOL, $preview['html'], PHP_EOL;echo 'Send it as it is? [y/N] '; $answer = fgets(STDIN); if ($answer !== false && strtolower(trim($answer)) === 'y') {    $client->emails->send([        'from' => '[email protected]',        'to' => '[email protected]',        'subject' => $preview['subject'],        'html' => $preview['html'],    ]);}

languages.php

use OpenEmail\Constants\Languages;use OpenEmail\OpenEmail; echo count(Languages::ALL), PHP_EOL; $current = $client->languages->list();echo count($current), PHP_EOL; echo OpenEmail::resolveLanguage('Deutsch')['code'] ?? 'none', PHP_EOL;echo OpenEmail::resolveLanguage('zh-TW')['code'] ?? 'none', PHP_EOL;echo OpenEmail::languageByCode('DE')['native'] ?? 'none', PHP_EOL;var_dump(OpenEmail::isRtlLanguage('ar'));

Bu satırlar önce 200'ü, yani bu sürümle gelen satır sayısını, ardından API'nin şu anda kaç satır tuttuğunu, ardından de, zh-Hant, Deutsch ve bool(true) değerlerini yazdırır. Tablo, seçici sırasıyla OpenEmail\Constants\Languages::ALL olarak pakete dahildir: code, label, native, flag ve rtl içeren dizilerden oluşan bir liste; böylece bir dil seçici ilk istekten önce doldurulabilir. languages->list aynı satırları ağdan düz bir liste olarak döndürür; bu sürümle gelenler yerine güncel satırları tercih eden çağıranlar içindir. OpenEmail::resolveLanguage() bir kod, İngilizce bir ad, dilin kendi adı ya da bir takma ad alır (zh-TW artık listelenmeyen bir kodun takma adıdır) ve hiçbir şey eşleşmezse null döndürür; OpenEmail::languageByCode() büyük/küçük harften bağımsız olarak tam bir kodu eşleştirir; OpenEmail::isRtlLanguage() ise bir dilin sağdan sola okunup okunmadığını söyler, satırlardan on altısında olduğu gibi. native, label ve code alanlarında birlikte arayın, önce native değerini gösterin ve kodu saklayın.

emails->translate otomatik olarak yeniden denenmez. Model çağrısı harcar ve hiçbir şey yazmaz; dolayısıyla idempotent kılınacak bir şey yoktur ve yanıtsız kalan bir isteğin ardından yeniden denemek yalnızca aynı yanıtı iki kez satın almak olur.

API'nin eşleştiremediği bir dil, hiçbir şey gönderilmeden önce translate.to üzerinde bir validation_error verir.
30.000 karakteri aşınca translation_too_long, kurulumda yapılandırılmış bir AI yoksa translation_not_configured, çalışma alanı bugünkü AI işlemlerini tükettiyse 429 ai_quota_exceeded (UTC gece yarısında sıfırlanır ve yeniden denenmez), sağlayıcı yanıt vermediyse translation_failed. Hiçbiri yedek olarak iletiyi çevrilmemiş hâlde göndermez.
template ile birlikte çalışır: çevrilen şey İŞLENMİŞ çıktıdır, dolayısıyla saklanan tek bir gövde, müşterilerinizin okuduğu her dile hizmet eder. Tam bir belge üreten bir şablon doctype'ını, <style> bloklarını ve @font-face kurallarını korur: modele yalnızca gövde gider, geri kalanı çevresine geri konur. Zaten hiçbir yerde görüntülenmeyen <title> öğesine dokunulmaz.
Yeniden denemenin ek bir maliyeti yoktur. Çeviri, idempotency parmak izinin parçası değildir (istek ise translate dahil parçasıdır); dolayısıyla yanıtsız kalan bir gönderimi aynı Idempotency-Key ile yeniden denemek, ikinci kez çevirip göndermek yerine zaten var olan mesajı yeniden oynatır.
Kuyruğa alınmış ya da zamanlanmış çevrilmiş bir ileti onaylanmış metnini korur. emails->reschedule onu yine de taşıyabilir, ancak emails->update yeni bir metni 409 translation_locked ile reddeder; bu yüzden içeriği değiştirmek, iptal edip yeniden göndermek anlamına gelir.

Ekler

content ağ üzerinde base64'tür. İstemciye okuyabileceği bir şey verin, baytları sizin için kodlar: fopen ile açılmış bir akış kaynağı, bir SplFileInfo ya da bir PSR-7 akışı veya yüklenmiş dosya. Bir dize olduğu gibi gönderilir, bu yüzden zaten base64 olmalıdır; bellekte tuttuğunuz baytlardan OpenEmail::toBase64() tam olarak bunu üretir.

attachments.php

use OpenEmail\OpenEmail; $attachments = [    ['filename' => 'invoice.pdf', 'content' => OpenEmail::toBase64(file_get_contents('invoice.pdf')), 'contentType' => 'application/pdf'],    ['filename' => 'report.csv', 'content' => new \SplFileInfo('report.csv')],    ['filename' => 'contacts.csv', 'content' => fopen('contacts.csv', 'rb')],    ['fileId' => 'file_6bb640f5b99e47deb758f1f5'],]; $client->emails->send([    'from' => '[email protected]',    'to' => '[email protected]',    'subject' => 'Your documents',    'text' => 'All three are attached.',    'attachments' => $attachments,]);

base64 olmayan bir dize content, hiçbir şey gönderilmeden önce OpenEmail\Exception\InvalidArgumentException fırlatır. Rastlantıyla base64 gibi okunan ham baytlar ise bozuk gider; bu yüzden bir dosyanın baytlarını asla olduğu gibi geçirmeyin: onları OpenEmail::toBase64() ile sarın ya da dosyanın kendisini geçirin.

Aynı kodlamaya başka bir yerde ihtiyacınız olursa OpenEmail::toBase64() kullanılabilir. Bir bayt dizesi, bir akış kaynağı, bir SplFileInfo ya da bir PSR-7 akışı alır ve satır sonu içermeyen base64 döndürür.