Yapay zekâ ajanları için

openemail agents, Claude Code ya da Codex gibi bir yapay zekâ ajanı veya CI'daki bir betik için Markdown biçiminde kısa bir kılavuz yazdırır: bir insan olmadan oturum açmayı, çıktıyı okumayı, komutları bulmayı, bir şeyleri güvenle değiştirmeyi ve listelerde sayfa sayfa ilerlemeyi, bir doğrulama kodu ya da kapsam eksik olduğunda ne yapılacağını ve kopyalanacak beş tarifi anlatır. openemail agent aynı komuttur.

openemail agentsopenemail agents --json | jq -r '.recipes[].commands[]'

--json ile kılavuz; schemaVersion, title, intro, { id, title, points } öğelerinden oluşan sections, exitCodes ve { id, title, commands } öğelerinden oluşan recipes içeren tek bir belgedir. Bu kuralları her istemin içine yapıştırmak yerine, projenizin ajana zaten verdiği talimat dosyasında ona bir kez, CLI'yi kullanmadan önce openemail agents komutunu çalıştırmasını söyleyin.

• —Bir API anahtarı kullanın. OPENEMAIL_API_KEY değişkenini ayarlayın ya da tek bir komuta --api-key verin. Anahtarı Ayarlar → API anahtarları (openemail open api-keys) bölümünden, yalnızca ajanın ihtiyaç duyduğu kapsamlarla oluşturun. Bir anahtar asla tarayıcı açmaz ve asla doğrulama kodu gerektirmez.
• —Ya da bir insanın bu makinede bir kez openemail login ile açtığı tarayıcı oturumunu yeniden kullanın ve onu --profile <name> ile seçin. CLI token'larını kendisi yeniler.
• —Terminal olmadan hiçbir şey sorulmaz. --json, --no-input ya da CI altında veya bağlı bir terminal yokken, CLI'nin soracağı bir değer 2 çıkış koduyla durur ve verilmesi gereken bayrağı adıyla söyler.
• —Bir tarayıcı oturumunu bir insanın onaylaması gerekir, bu yüzden gözetimsiz bir openemail login hiçbir şeyi kaydetmeden önce 2 çıkış kodu ve unattended koduyla durur ve openemail login --with-token komutunu gösterir.
• —openemail whoami --json çalışma alanını, oturum türünü ve onun scopes alanını gösterir.

Her komuta --json verin. O zaman stdout tam olarak tek bir JSON belgesi ya da --ndjson ile satır başına bir nesne içerir, ilerleme de stderr'de kalır. Bir hata stderr'e tek bir {"error":{...}} satırı yazdırır: çıkış koduna ve onun code değerine göre dallanın, next değerini bir insana gösterin ve ifadesi değişebilecek olan message değerini asla ayrıştırmayın. Betikler sayfası her alanı ve her çıkış kodunu listeler.

--help --json, yardımı CLI'nin ayrıştırırken kullandığı aynı komut kayıt defterinden oluşturulmuş tek bir JSON belgesi olarak yazdırır, bu yüzden her zaman kurulu sürümle eşleşir. Kökte, bir grupta ya da bir komutta çalışır ve openemail help <command> --json aynısını yazdırır.

openemail send --help --jsonopenemail domains delete --help --json | jq '.commands[0] | {scopes, destructive}'openemail help domains --json | jq -r '.commands[0].subcommands[].command'openemail --help --json | jq -r '.commands[].command'

Ağacın tamamı yaklaşık bir megabayttır ve neredeyse tamamı 198 kaynak komutudur, bu yüzden ihtiyacınız olan komutu isteyin ya da ağacı jq ile süzün. Metin ters tırnaklarını korur ve renk kodu içermez; security gibi gizli komutlar da hidden değeri true olarak dahil edilir.

--dry-run, mcp serve dışındaki her komutta çalışır. Okumalar her zamanki gibi çalışır, sonra bir şeyi değiştirecek ilk istek gönderilmek yerine yazdırılır ve komut başka hiçbir şey yapmadan 0 koduyla çıkar. Hiçbir şey gönderilmediği için onaylar atlanır; böylece bir ajan, yıkıcı bir komutun ne yapacağını --yes vermeden görebilir.

openemail domains delete <domain-id> --dry-runopenemail send --from [email protected] --to [email protected] --subject "Hi" --text "Hello" --dry-run --json

{  "dryRun": true,  "request": {    "method": "POST",    "url": "https://api.openemail.uk/emails",    "headers": {      "accept": "application/json",      "authorization": "Bearer [redacted]",      "content-type": "application/json",      "idempotency-key": "58e6fb61-ad2e-401e-b141-7a0546c7c749",      "user-agent": "openemail-cli/0.0.1 openemail-sdk/0.0.5"    },    "body": {      "from": "[email protected]",      "to": [        "[email protected]"      ],      "subject": "Hi",      "text": "Hello"    },    "raw": null  }}

• —Bir değişiklik; GET ve HEAD dışındaki her istek, bir MCP aracı çağrısı ve login ile logout komutlarının oturum açma ve kapatma istekleridir. Token yenileme ve docs ask yine de çalışır.
• —Plan; yöntemi, tam URL'yi, Authorization değeri Bearer [redacted] olarak kısaltılmış başlıkları ve Resend anahtarı gibi gizli alanları maskelenmiş JSON gövdesini gösterir. Bir yükleme yalnızca boyutunu ve içerik türünü gösterir.
• —profile use, login --with-token ya da kayıtlı bir API anahtarını unutmak gibi bu makinede kalan bir değişiklik {"dryRun":true,"local":{"action","profile"}} yazdırır ve hiçbir şey kaydetmez.
• —İlk değişikliğinden önce okuduğunu yazdıran bir komut bunu önce gösterir: read konuşmayı, ardından onu okundu olarak işaretleyecek isteği yazdırır. İkincisini dışarıda bırakmak için --no-mark-read verin.
• —mcp serve, --dry-run seçeneğini 2 çıkış koduyla reddeder, çünkü ne gönderileceğine istemcisi karar verir. Bunun yerine tek bir araç çağrısını openemail mcp call <tool> --dry-run ile önizleyin.

Her komut her zaman ihtiyaç duyduğu API kapsamlarını bilir ve yardımı bunları listeler. Kayıtlı bir oturumda bunlardan biri eksik olduğunda komut güncel listeyi API'den bir kez ister, böylece oturum açıldıktan sonra web sitesinde verilen erişim hemen geçerli olur. Kapsam hâlâ eksikse, bir şey sormadan ya da bir istek göndermeden önce 4 çıkış kodu ve insufficient_scope koduyla durur:

{"error":{"type":"cli_error","code":"insufficient_scope","message":"This sign-in does not have the emails:send permission, which openemail send needs.","hint":null,"next":"Give this app more access in Account settings, Connected apps (openemail open apps, then Edit access), or run openemail login --force and choose more access.","status":null,"requestId":null,"param":null,"docUrl":null,"exitCode":4}}

• —Bir tarayıcı oturumu için next, uygulamaya Hesap → Komut satırı bölümünden daha fazla erişim vermenizi (openemail open cli, ardından Erişimi düzenle) ya da openemail login --force çalıştırıp daha fazla erişim seçmenizi söyler. Bir tarayıcı oturumuna asla keys:write ya da keys:manage verilmez, bu yüzden bunlar için bir API anahtarına yönlendirir.
• —Bir API anahtarı için next, o kapsama sahip bir anahtar kullanmanızı söyler.
• —--api-key ya da OPENEMAIL_API_KEY ile gelen bir anahtar önceden denetlenmez ve kararı API verir. API bir çağrıyı eksik kapsam yüzünden reddettiğinde hata aynı next değerini taşır.

Bir API anahtarı asla doğrulama kodu gerektirmez. Bir tarayıcı oturumu ise bir webhook eklemek, bir kural oluşturmak, bir üyeyi değiştirmek ya da bir alan adını kaldırmak gibi hassas bir değişiklikten önce kod gerektirir ve bir ajan bu kodu yazamaz. Bu yüzden ajan çalışmadan önce bir insan ya aynı profille bir terminalde openemail verify çalıştırır ya da Hesap → Komut satırı bölümünde o oturum için 60 dakika boyunca değişikliklere izin ver seçeneğini seçer. İkisi de sonraki 60 dakikayı kapsar.

openemail verifyopenemail verify --status --json

verify --status --json, ajana profilin doğrulanıp doğrulanmadığını elevated alanında, ne zamana kadar doğrulandığını da elevatedUntil alanında söyler. Doğrulama olmadan değişiklik 4 çıkış kodu ve step_up_required koduyla durur ve hiçbir şey değişmez:

{"error":{"type":"cli_error","code":"step_up_required","message":"This action needs a verification code, and there is no interactive terminal to ask for one.","hint":null,"next":"Run openemail verify in an interactive terminal first, then run this again within 60 minutes. An API key never needs a code.","status":403,"requestId":"req_9Qm4tV","param":null,"docUrl":"https://openemail.uk/docs/api/errors#step_up_required","exitCode":4}}

MCP konuşan bir ajan bunun yerine OpenEmail MCP sunucusunu kullanabilir. openemail mcp config --client claude-code ya da codex, cursor ve listelediği diğer istemciler kurulumu yazdırır; openemail mcp serve ise bu CLI'nin tarayıcı oturumunu yeniden kullanan yerel bir köprüdür. API anahtarları MCP sunucusuna ulaşamaz. Ayrıntılar Yapay zekâ ve MCP sayfasında.