Auxiliares e constantes
O que mais a gem define além do cliente.
Métodos do módulo
| Método | O que é |
|---|---|
| OpenEmail.init, OpenEmail.client | Configure uma vez o cliente partilhado e depois aceda-lhe a partir de qualquer lado. Constrói-se a partir de OPENEMAIL_API_KEY se init nunca tiver corrido. |
| OpenEmail.emails, OpenEmail.threads e todos os outros espaços de nomes | Atalhos para os espaços de nomes do cliente partilhado. |
| OpenEmail.reset_client | Descarta o cliente partilhado, para que a chamada seguinte construa um novo, que é o que um teste quer entre casos. |
| OpenEmail.create_client, OpenEmail::Client.new, OpenEmail.new | Um cliente separado. create_client lê do ambiente tudo o que deixar de fora, e Client.new (ou OpenEmail.new) recebe apenas o que lhe passar. |
| OpenEmail.create_temp_mail | Um cliente de caixas descartáveis que não leva chave de API. |
| OpenEmail.verify_webhook_signature | Verifica a assinatura de uma entrega em tempo constante, com uma janela de repetição. Devolve o evento analisado e lança OpenEmail::WebhookSignatureError em qualquer falha. |
| OpenEmail.to_base64 | Base64 para os bytes de anexos, a partir de uma String binária, um IO ou um Pathname. |
| OpenEmail.api_key? | Se uma String tem a forma oe_live_ ou oe_test_. Uma verificação de forma, não uma prova de que a chave ainda funciona. |
| OpenEmail.access_token? | Se uma String tem a forma de um token de acesso OAuth: de 1 a 512 caracteres, sem começar por oe_. |
| OpenEmail.sealed? | Se o corpo de uma mensagem é texto cifrado. É false para os dois formatos assinados, cujos corpos chegaram em claro. |
| OpenEmail.resolve_language, OpenEmail.language_by_code, OpenEmail.rtl_language? | As procuras de que um seletor de idioma precisa, sobre a tabela OpenEmail::LANGUAGES incluída na gem. |
Constantes
Cada conjunto de valores que o SDK de TypeScript exporta é um Hash congelado em OpenEmail, com as mesmas chaves, por isso OpenEmail::WEBHOOK_EVENTS[:EMAIL_DELIVERED] é "email.delivered". Use .values quando precisar da lista, e .value? para verificar um valor vindo de fora.
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]| Constante | O que contém |
|---|---|
| OpenEmail::VERSION | A versão da gem. |
| OpenEmail::API_SCOPES | O vocabulário de âmbitos, para um ecrã de criação de chaves. |
| OpenEmail::WEBHOOK_EVENTS, OpenEmail::WEBHOOK_SIGNATURE_HEADERS | Os eventos que um endpoint pode subscrever, e os nomes dos cabeçalhos que uma entrega transporta. |
| OpenEmail::ERROR_TYPES | O vocabulário de erros que ApiError#type pode assumir. |
| OpenEmail::PAGE_LIMITS | O limit: máximo e o predefinido na maioria das listas paginadas: 100 e 25. Algumas listas aceitam mais, e a referência de cada método indica-o. |
| OpenEmail::RULE_FIELDS, OpenEmail::RULE_OPERATORS, OpenEmail::RULE_ACTIONS | O vocabulário a partir do qual as condições e as ações de uma regra são construídas. |
| OpenEmail::MESSAGE_ENCRYPTION_FORMATS | Os cinco envelopes que a ingestão pode indicar. Três deles são selados. |
| OpenEmail::CREDENTIAL_KINDS, OpenEmail::STEP_UP_METHODS, OpenEmail::STEP_UP_ERROR_CODES | Que credencial me.get e me.ping descrevem, como é verificado um código de verificação e os códigos com que uma verificação pode falhar. |
| OpenEmail::THREAD_SORTS, OpenEmail::PEOPLE_SORTS, OpenEmail::FILE_SORTS e os outros *_SORTS | As ordens pelas quais uma lista pode ser ordenada. |
| OpenEmail::FORM_STATUSES, OpenEmail::BROADCAST_STATUSES, OpenEmail::SUPPRESSION_REASONS e os outros conjuntos | Os valores que um campo de um recurso pode assumir. Cada conjunto tem o nome do que contém. |
Objetos
Uma resposta é o JSON analisado como um Hash com chaves Symbol. A gem só constrói um objeto próprio quando dá forma à resposta, e cada um é um Data imutável.
| Classe | O que contém |
|---|---|
| OpenEmail::Page | items, has_more? e next_cursor, de cada list paginado. |
| OpenEmail::PeoplePage | O mesmo, mais seen, de contacts.list_people. |
| OpenEmail::TempMessagesPage | O mesmo, mais expires_at, de temp_mail.list_messages. |
| OpenEmail::AddressBookPage, OpenEmail::AddressBook | unrestricted, addresses e domains, de addresses.list (com has_more? e next_cursor) e de addresses.list_all. |
| OpenEmail::BatchResult | items, sent e failed, de emails.send_batch. |
| OpenEmail::TemplateSends | items, total, page e page_size, de templates.list_sends. |
| OpenEmail::HttpRequest, OpenEmail::HttpResponse | O que um adapter: recebe e devolve. Um pedido mostra o seu cabeçalho Authorization como [redacted]. |
Todos os erros que a gem lança de propósito herdam de OpenEmail::Error: ApiError e as suas subclasses, NetworkError e WebhookSignatureError. Um argumento errado dá antes um ArgumentError, porque é um erro no código que faz a chamada e não algo a apanhar.
Um endpoint que isto ainda não envolve
Uma versão da gem nunca deve ser o que se interpõe entre si e um endpoint que já funciona. client.raw.request recebe um caminho e opções como argumentos nomeados e devolve o corpo analisado, com a credencial, o URL base, o timeout e a política de repetição do cliente aplicados.
result = client.raw.request( "/something-new", method: :post, query: {dryRun: true}, body: {name: "Invoices"}, repeatable: true) p resultUm GET é repetido como qualquer outra leitura. Qualquer outro método é enviado uma só vez, a menos que passe repeatable: true, que é a sua afirmação de que pode ser enviado duas vezes. query: ignora valores nil ou vazios, e api_key: funciona como em todos os outros métodos.
O que deliberadamente não faz
- Não valida nenhum corpo de pedido. O esquema do servidor é a única cópia das regras, e uma segunda cópia aqui acabaria por recusar um endereço que um servidor mais recente aceita, numa versão que alguém fixou há dois anos.
- Não tem dependências de execução, nem sequer uma gem de JSON ou de HTTP além da biblioteca padrão.
- Só altera a forma de uma resposta de uma maneira: o array
datade uma coleção é retirado do seu envelope para um dos objetos acima. Todas as outras respostas voltam tal como a API as enviou, com as chaves em camelCase da API.
A verificação de paridade da gem garante que isto se mantém verdade. Faz falhar a build quando um método de TypeScript não tem equivalente em Ruby, aceita opções diferentes ou envia um pedido diferente.