Posta kutusu bağlama

Bir Gmail ya da Outlook posta kutusu bağlayın; gelen e-postaları GET /emails/get-email için kullanılabilir olur. Bağlama OAuth kullanır: posta kutusunun sahibi erişimi kendi tarayıcısında verir ve siz parolasını asla görmezsiniz.

Aşağıdaki her yoldaki provider, gmail ya da outlook’tur.

Backend’iniz oauth/start ve oauth/result’ı API anahtarınızla çağırır. Kullanıcının tarayıcısı yalnızca yönlendirmeleri takip eder. Anahtarınız ona asla ulaşmaz.

1. Akışı backend’inizden başlatın.

   curl

   curl -G https://api.clearance.rest/emails/gmail/oauth/start \
     -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
     --data-urlencode "return_url=https://app.example.com/settings/mailboxes" \
     --data-urlencode "client_state=user-42"

   Node.js

   const { authorize_url } = await clearanceRest.emails.oauthStart({
     provider: 'gmail',
     returnUrl: 'https://app.example.com/settings/mailboxes',
     clientState: 'user-42',
   });

   PHP

   $authorizeUrl = $client->emails->oauthStart(
       'gmail',
       'https://app.example.com/settings/mailboxes',
       'user-42',
   )['authorize_url'];

   return_url zorunludur ve mutlak bir http(s) URL’i olmalıdır. Projeniz izin verilen dönüş origin’lerini kısıtlıyorsa bunlardan birinde olmalıdır; aksi halde çağrı 400 döndürür. client_state, seçtiğiniz opak bir değerdir ve sonda değişmeden geri gelir; böylece sonucun hangi kullanıcıya ait olduğunu anlarsınız.

2. Kullanıcının tarayıcısını authorize_url’e yönlendirin.

   Google ya da Microsoft’ta oturum açıp erişimi verirler. Sağlayıcı sonra clearance.rest’e yönlendirir, o da tarayıcıyı iki query parametresiyle return_url’inize yönlendirir:

   https://app.example.com/settings/mailboxes?result_token=…&client_state=user-42

   Yönlendirme başarıda ve başarısızlıkta olur ve sonucun kendisini asla taşımaz. Bir sonraki adım bunun içindir.

3. Sonucu backend’inizden okuyun.

   curl -G https://api.clearance.rest/emails/gmail/oauth/result \
     -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
     --data-urlencode "token=$RESULT_TOKEN"

   { "success": true, "email": "user@gmail.com", "client_state": "user-42" }

   Başarısız bir bağlantı da HTTP 200’dür; success: false olur ve neden error’da yer alır. Token tek kullanımlıktır: ilk okumada harcanır, ikinci okuma 404 döndürür ve yaklaşık 10 dakika sonra geçersiz olur.

Posta kutusunu kullanma

Bağlandıktan sonra o adrese gelen postalar get-email için kullanılabilir:

curl -G https://api.clearance.rest/emails/get-email \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  --data-urlencode "email_account=user@gmail.com" \
  --data-urlencode "code_regex=\d{6}"

Bir adres yalnızca tek bir projeye bağlanabilir. Başka bir projeye ait bir adresi bağlamak başarısız olur ve oauth/result nedenini bildirir.

Listeleme ve bağlantıyı kesme

curl https://api.clearance.rest/emails/gmail/accounts \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY"

curl -X POST https://api.clearance.rest/emails/gmail/accounts/disconnect \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "email": "user@gmail.com" }'

Liste yalnızca projenizin posta kutularını gösterir ve token döndürmez. Her birinin, varsa en son senkronizasyon sorununu tutan bir last_error alanı vardır. disconnect, sağlayıcı tarafındaki watch’ı durdurur (erişim zaten iptal edilmişse hatayı yok sayar) ve bağlantıyı kaldırır. O posta kutusu projenize bağlı değilse 404 döndürür.

Bağlantının watch ya da subscription’ı otomatik olarak yenilenir; sizin yenilemeniz gerekmez.