Formlar nasıl çalışır

Bir form, ziyaretçilerin gördüklerinin iki kopyasını tutar. document düzenlediğiniz taslaktır; publishedDocument ise barındırılan sayfanın, yerleştirilmiş formun ve abonelik uç noktasının kullandığı kopyadır. Kaydetmek yalnızca taslağı değiştirir; POST /forms/{id}/publish ise onu yayındaki kopyaya aktarır. hasUnpublishedChanges ikisinin farklı olduğunu söyler.

• —draft: hiç yayımlanmadı. Kimse onu göremez ya da onun üzerinden kaydolamaz.
• —live: yayımlandı ve kayıt alıyor.
• —paused: yayımlandı ama kapalı. Sayfa, metinlerindeki form kapalı mesajını gösterir ve kayıtlar reddedilir.

settings ise farklıdır: kayıtların nereye gideceği, çift onay, gönderen, kayıttan sonra ne olacağı ve her kayıttan kimin haberdar edileceği. Bunlar, form yayımlanmış olsun ya da olmasın, kaydedildikleri anda geçerli olur.

Bir belge; bir fields listesinden, bunları çevreleyen copy metinlerinden ve bir style değerinden oluşur. Her giriş alanının, yanıtının gönderildiği ad olan bir key değeri vardır: küçük bir harf ve ardından en fazla 39 küçük harf, rakam ya da alt çizgi; formda benzersizdir ve asla oe_ ile başlamaz. Her formda, anahtarı email olan ve zorunlu olan tam olarak bir email alanı vardır.

• —Giriş alanları: email, text, textarea, number, phone, url ve date.
• —Seçimler: her biri options içeren select, radio ve checkboxes.
• —Evet ya da hayır için checkbox ve zorunlu olduğunda işaretlenmesi gereken bir kutu için consent.
• —audiences kişinin liste seçmesini sağlar: her seçeneğin value değeri bu çalışma alanındaki bir kitle id'sidir.
• —hidden, ziyaretçinin hiç görmediği bir değer taşır: sayfanızın gönderdiği değer ya da o yoksa kampanya adı gibi defaultValue değeri.
• —heading, paragraph ve divider yalnızca formun düzenini kurar ve hiçbir şey göndermez.

Bir metin alanında mapsTo değerini firstName, lastName ya da name yapın; yanıt, kaydın oluşturduğu kişinin adı olur. Zaten var olan bir kişi adını korur. Her yanıt, o anki etiketiyle birlikte gönderimde saklanır; böylece eski gönderimler form değiştikten sonra da doğru okunur.

Önce yayımlayın. Ardından üç yoldan sayfaya hangisi uyuyorsa onu kullanın. Hepsi aynı forma ulaşır ve aynı kayıtları sayar. Görüntülemeler yalnızca barındırılan sayfada ve yerleştirilmiş formda sayılır; bu yüzden kendi HTML'iniz ya da kodunuz üzerinden gelen kayıtlar dönüşüm oranını yükseltir.

• —url adresindeki barındırılan sayfa: her yerden bağlantı verebileceğiniz, kendine ait bir sayfa.
• —Formu sayfanıza, boyutunu kendi ayarlayan bir çerçeve içinde koyan yerleştirme script'i.
• —Yanıtları subscribeUrl adresine gönderen kendi HTML'iniz ya da kodunuz.

<script src="https://openemail.uk/embed/form.js" data-openemail-form="frm_3b9d2e7a1c4f80d56e2a9b14" async></script>

<form action="https://api.openemail.uk/subscribe/frm_3b9d2e7a1c4f80d56e2a9b14" method="post">  <input type="email" name="email" required>  <div style="position:absolute;left:-9999px" aria-hidden="true">    <input type="text" name="oe_website" tabindex="-1" autocomplete="off">  </div>  <button type="submit">Subscribe</button></form>

Düz bir HTML formu teşekkür sayfasına ya da settings.redirectUrl adresine yönlendirilir. JSON gönderen kod ise bunun yerine, abonelik sayfasında açıklanan bir JSON yanıtı alır.

settings.doubleOptIn açıkken bir kayıt pending olarak saklanır ve kişiye, bu çalışma alanının bir adresi olan settings.senderAddress adresinden bir bağlantı e-postayla gönderilir. Kişi bağlantıyı açtığında kitlelere katılır. Bağlantı yedi gün geçerlidir. Daha önce bir kitlenin aboneliğinden çıkmış bir kişi yalnızca bu yolla yeniden abone edilir, çift onayı olmayan bir formla asla. Onaylamadan önce yeniden kaydolmak başka bir kayıt eklemek yerine bekleyen kaydı günceller.

E-posta gönderdiğiniz kişileri korumak için bir adres, form başına on dakikada en fazla bir onay ve çalışma alanı genelinde günde en fazla beş onay alır. Bekleyen bir kaydı kendiniz onaylayabilir ya da ona yeni bir bağlantı gönderebilirsiniz.

• —Okumak forms:read, değiştirmek forms:write gerektirir. Bir kaydı onaylamak, bir kişi eklediği için ayrıca contacts:write gerektirir.
• —Bir formun posta göndermesine yol açan her şey ayrıca emails:send gerektirir: çift onayı açmak, göndereni ya da onay e-postasını ayarlamak, çift onaylı bir formu yayımlamak ya da sürdürmek ve bir onayı yeniden göndermek.
• —Bir API anahtarı ve sahip, çalışma alanındaki her formu görür. Bir üyenin bağladığı uygulama yalnızca o üyenin oluşturduğu formları, kitlelerden de yalnızca o üyenin oluşturduklarını ve yerleşik olanları görür.
• —Göndereni ya da bildirim adresleri, sınırlı bir anahtarın ya da uygulamanın erişebildiklerinin dışında kalan bir formu oluşturur, günceller, yayımlar, sürdürür ya da çoğaltırsanız yanıt 422 capability_unsupported olur.
• —Bazı adreslerle sınırlı bir anahtar ya da uygulama, gönderen ve bildirim adresi olarak yalnızca sahip olduğu adresleri ayarlayabilir.
• —Bir formu silmek, diğer yıkıcı değişikliklerde olduğu gibi bir OAuth uygulamasından doğrulama kodu ister. Bir API anahtarının buna asla ihtiyacı olmaz.

form.submitted ve form.confirmed webhook'ları sistemlerinize her kaydı bildirir. Bazı adreslerle sınırlı bir webhook bunları asla almaz, çünkü kayıtlar tüm çalışma alanına aittir.

• —oe_website adlı bir alan botlar için bir tuzaktır: yukarıdaki HTML'nin yaptığı gibi onu boş ve ekran dışında tutun. Onu dolduran bir kayıt normal bir yanıt alır ve atılır.
• —Barındırılan sayfa ve yerleştirilmiş form ayrıca imzalı bir başlangıç zamanını denetler; bir insanın doldurabileceğinden daha hızlı geri gönderilen bir form da aynı şekilde atılır.
• —Bir ağ, tüm formlarınız genelinde ve sonuç ne olursa olsun on dakikada 40 kayıt gönderebilir. Bundan sonra JSON ile çağıranlar 429 form_rate_limited alır, düz bir HTML formu ise ?outcome=limited ile barındırılan sayfaya gider.
• —Bir çalışma alanı varsayılan olarak 100 form tutar.

Buradaki her şey SDK'da openemail.forms, CLI'da openemail forms olarak da bulunur ve MCP sunucusunda form araçları vardır; böylece bir ajan bir form oluşturabilir, yayımlayabilir ve izleyebilir. MCP üzerinden tasarımı istemcinin kendisi yazar ve document olarak geçirir.

Kendi kodunuzdan subscribeUrl adresine veri göndermek kimlik bilgisi gerektirmez. Yanıtları JSON olarak gönderin, formun bulunduğu sayfayı oe_source olarak ekleyin, oe_started değerini dışarıda bırakın ve oe_website değerini boş gönderin ya da hiç göndermeyin. Tek bir ağdan gelen tüm kayıtlar on dakikada 40 kayıtlık aynı sınırı paylaşır; bu yüzden birçok kişi adına kayıt ileten bir sunucu bu sınıra çabucak ulaşır: zaten tanıdığınız kişileri bunun yerine kitle içe aktarımıyla ekleyin.