ヘルパーと定数
クライアント以外に gem が定義しているもの。
モジュールメソッド
| メソッド | 内容 |
|---|---|
| OpenEmail.init, OpenEmail.client | 共有クライアントを一度設定すれば、あとはどこからでも使えます。init が一度も実行されていない場合は OPENEMAIL_API_KEY から自身を組み立てます。 |
| OpenEmail.emails、OpenEmail.threads とその他すべての名前空間 | 共有クライアントの名前空間へのショートカット。 |
| OpenEmail.reset_client | 共有クライアントを破棄し、次の呼び出しで新しく組み立てさせます。テストのケース間で必要になるのはこれです。 |
| OpenEmail.create_client, OpenEmail::Client.new, OpenEmail.new | 独立したクライアント。create_client は省略された項目を環境変数から読み取り、Client.new（または OpenEmail.new）は渡された値だけを使います。 |
| OpenEmail.create_temp_mail | API キーを持たない使い捨て受信箱用のクライアント。 |
| OpenEmail.verify_webhook_signature | 配信の署名を一定時間で比較して検証し、リプレイ許容ウィンドウを備えます。パース済みのイベントを返し、失敗時には OpenEmail::WebhookSignatureError を送出します。 |
| OpenEmail.to_base64 | 添付ファイルのバイト列を、バイナリの String、IO、Pathname から Base64 にします。 |
| OpenEmail.api_key? | String が oe_live_ または oe_test_ の形をしているかどうか。形式の検査であり、そのキーがまだ有効であることの証明ではありません。 |
| OpenEmail.access_token? | String が OAuth アクセストークンの形をしているかどうか：1〜512 文字で、oe_ で始まらないこと。 |
| OpenEmail.sealed? | メッセージのボディが暗号文かどうか。2 つの署名形式では、ボディが平文で届いているため false です。 |
| OpenEmail.resolve_language, OpenEmail.language_by_code, OpenEmail.rtl_language? | 言語ピッカーに必要な検索メソッドで、同梱の OpenEmail::LANGUAGES テーブルを対象とします。 |
定数
TypeScript SDK がエクスポートする値の集合は、どれも同じ名前をキーとする凍結された Hash として OpenEmail 上にあります。そのため OpenEmail::WEBHOOK_EVENTS[:EMAIL_DELIVERED] は "email.delivered" です。一覧が必要な場合は .values を、外部から来た値を確認するには .value? を使ってください。
events = OpenEmail::WEBHOOK_EVENTS.values scopes = [OpenEmail::API_SCOPES[:EMAILS_SEND], OpenEmail::API_SCOPES[:THREADS_READ]] puts events.size, scopes.join(","), OpenEmail::PAGE_LIMITS[:MAX_LIMIT]| 定数 | 内容 |
|---|---|
| OpenEmail::VERSION | gem のバージョン。 |
| OpenEmail::API_SCOPES | キー作成画面のためのスコープ語彙。 |
| OpenEmail::WEBHOOK_EVENTS, OpenEmail::WEBHOOK_SIGNATURE_HEADERS | エンドポイントが購読できるイベントと、配信に付くヘッダーの名前。 |
| OpenEmail::ERROR_TYPES | ApiError#type が取るエラーの語彙。 |
| OpenEmail::PAGE_LIMITS | ほとんどのページ分割される一覧における limit: の最大値と既定値：100 と 25。それより多く受け付ける一覧もいくつかあり、各メソッドのリファレンスにそう書かれています。 |
| OpenEmail::RULE_FIELDS, OpenEmail::RULE_OPERATORS, OpenEmail::RULE_ACTIONS | ルールの条件とアクションを組み立てるための語彙。 |
| OpenEmail::MESSAGE_ENCRYPTION_FORMATS | 受信処理が識別できる 5 つのエンベロープ。そのうち 3 つは封緘されています。 |
| OpenEmail::CREDENTIAL_KINDS, OpenEmail::STEP_UP_METHODS, OpenEmail::STEP_UP_ERROR_CODES | me.get と me.ping が表す資格情報の種類、確認コードの確認方法、そして確認が失敗するときのコード。 |
| OpenEmail::THREAD_SORTS、OpenEmail::PEOPLE_SORTS、OpenEmail::FILE_SORTS とその他の *_SORTS | 一覧を並べ替えられる順序。 |
| OpenEmail::FORM_STATUSES、OpenEmail::BROADCAST_STATUSES、OpenEmail::SUPPRESSION_REASONS とその他の集合 | リソースのフィールドが取り得る値。各集合は、保持するものにちなんで名付けられています。 |
オブジェクト
レスポンスは、パースされた JSON を Symbol キーの Hash にしたものです。gem が独自のオブジェクトを作るのは答えの形を整える場合だけで、それぞれ不変の Data です。
| クラス | 持っているもの |
|---|---|
| OpenEmail::Page | items、has_more?、next_cursor。ページ分割されるすべての list から返ります。 |
| OpenEmail::PeoplePage | 同じものに seen を加えたもの。contacts.list_people から返ります。 |
| OpenEmail::TempMessagesPage | 同じものに expires_at を加えたもの。temp_mail.list_messages から返ります。 |
| OpenEmail::AddressBookPage, OpenEmail::AddressBook | unrestricted、addresses、domains。addresses.list（has_more? と next_cursor 付き）と addresses.list_all から返ります。 |
| OpenEmail::BatchResult | items、sent、failed。emails.send_batch から返ります。 |
| OpenEmail::TemplateSends | items、total、page、page_size。templates.list_sends から返ります。 |
| OpenEmail::HttpRequest, OpenEmail::HttpResponse | adapter: が受け取り、返すもの。リクエストは Authorization ヘッダーを [redacted] として表示します。 |
gem が意図して送出するエラーはすべて OpenEmail::Error を継承します：ApiError とそのサブクラス、NetworkError、WebhookSignatureError です。誤った引数は代わりに ArgumentError になります。それは rescue すべきものではなく、呼び出し側のコードの誤りだからです。
まだラップされていないエンドポイント
gem のリリースが、すでに動作しているエンドポイントとの間に立ちはだかってはなりません。client.raw.request はパスとキーワード引数のオプションを受け取り、クライアントの資格情報、ベース URL、タイムアウト、リトライポリシーを適用したうえで、パース済みのボディを返します。
result = client.raw.request( "/something-new", method: :post, query: {dryRun: true}, body: {name: "Invoices"}, repeatable: true) p resultGET は他の読み取りと同様にリトライされます。それ以外のメソッドは、2 回送信されてもよいという宣言である repeatable: true を渡さない限り 1 回だけ送信されます。query: は nil や空の値を除外し、api_key: は他のすべてのメソッドと同じように動作します。
あえて行わないこと
- リクエストボディの検証は行いません。ルールの唯一の写しはサーバーのスキーマであり、ここに 2 つ目の写しを置けば、いずれ 2 年前に誰かが固定したバージョンが、新しいサーバーなら受け入れるアドレスを拒否することになります。
- 実行時の依存関係はなく、標準ライブラリ以外の JSON や HTTP の gem すら使いません。
- レスポンスの形を変えるのは 1 つの方法だけです：コレクションの
data配列をエンベロープから取り出し、上のオブジェクトのいずれかにします。それ以外のレスポンスはすべて、API が送ったとおりに、API の camelCase のキーのまま返ります。
gem のパリティチェックがこれを保証します。TypeScript のメソッドに対応する Ruby のメソッドがない場合、異なるオプションを受け取る場合、または異なるリクエストを送る場合に、ビルドを失敗させます。