Skip to the documentation
SDK

Types and helpers

What else the package exports.

Runtime exports

ExportWhat it is
`init`, `openemail`Configure the shared client once, then import openemail anywhere. It builds itself from OPENEMAIL_API_KEY if init never ran.
`getClient`, `resetClient`The shared client itself, and a way to drop it so the next call builds a fresh one, which is what a test wants between cases.
`createOpenEmail`, `createClient`, `OpenEmail`A separate client. createOpenEmail reads the environment for anything you leave out (createClient is the same function), and new OpenEmail (also the default export) takes only what you pass.
`createTempMail`A disposable-inbox client that carries no API key, and the one part of the package that runs in a browser.
`OpenEmailApiError`, `OpenEmailNetworkError`The two error classes.
`verifyWebhookSignature`Constant-time, with a replay window. Resolves to the parsed payload and throws on any failure.
`toBase64`Chunked, for attachment bytes.
`isApiKey`Whether a string has the oe_live_ or oe_test_ shape. A shape check, not proof the key still works.
`isSealed`, `MESSAGE_ENCRYPTION_FORMATS`Whether a message’s body is ciphertext, and the five envelopes ingest can name. isSealed is false for the two SIGNED formats, whose bodies arrived in the clear, which is why it ships rather than being left to a caller to derive from the union.
`LANGUAGES`, `resolveLanguage`, `languageByCode`, `isRtlLanguage`The bundled language table, and the lookups a language picker needs.
`API_SCOPES`The scope vocabulary, for a key-creation screen.
`WEBHOOK_EVENTS`, `WEBHOOK_SIGNATURE_HEADERS`The events an endpoint can subscribe to, and the names of the headers a delivery carries.
`RULE_FIELDS`, `RULE_OPERATORS`, `RULE_ACTIONS`The vocabulary a rule’s conditions and actions are built from.
`PAGE_LIMITS`The largest and the default limit on a paged list: 100 and 25.
`ERROR_TYPES`The frozen error vocabulary.
`VERSION`The package version.

Types

Every request and response has one, and they are exported from the package root. There are no deep imports, so the file layout stays an implementation detail that can move without a major version. …Resource is what the API returns, …Create, …Patch, …Input and …Send are what you pass, and …Options holds filters and per-call options.

  • Client: ClientOptions, TempMailOptions, TransportOptions, RequestOptions, RequestScope, SendScope, InboxScope, ListOptions, Page, ApiKeyMode, FetchLike.
  • Errors: ErrorType, ApiErrorPayload, ApiErrorProps.
  • Emails: EmailSend, EmailListOptions, EmailTranslate, EmailResource, SentEmailResource, EmailRecipientResource, EmailEventResource, EmailStatus, EmailSource, EmailTransport, EmailTrackingSummary, EmailTranslationResource, TranslationResource, RecipientStatus, BatchItemResource, BatchResultResource.
  • Templates: TemplateCreate, TemplatePatch, TemplateContent, TemplateListOptions, TemplatePreviewInput, TemplateSend, TemplateResource, TemplateDetailResource, TemplateVersionResource, TemplatePreviewResource, SentTemplateEmailResource, DeletedTemplateResource, TemplateEngine, TemplateProp, TemplateSlot, TemplateStatus, TemplateValueKind.
  • Tracking: TrackingListOptions, TrackingStatsOptions, TrackingHitOptions, TrackingResource, TrackingSummary, TrackingRecipientResource, TrackingLinkResource, TrackingOpenResource, TrackingClickResource, TrackingStatsResource, TrackingGrain.
  • Threads and drafts: ThreadListOptions, ThreadPatch, ThreadResource, ThreadSummaryResource, UpdatedThreadResource, TrashedThreadResource, SnoozedThreadResource, DraftInput, DraftListOptions, DraftResource, DraftSummaryResource, SavedDraftResource, DeletedDraftResource.
  • Labels, contacts, domains and addresses: LabelInput, LabelColor, LabelResource, SavedLabelResource, DeletedLabelResource, ContactCreate, ContactPatch, ContactListOptions, ContactSource, ContactResource, ContactDetailResource, ContactAudienceResource, DeletedContactResource, DomainPatch, DomainResource, DomainDetailResource, DomainSendingState, DomainTracking, DomainTrackingState, AddressBookResource, AddressResource, SendableDomainResource.
  • Rules: RuleCreate, RulePatch, RuleListOptions, RuleRunListOptions, RuleTestInput, RuleResource, RuleRunResource, RuleTestResource, DeletedRuleResource, RuleCondition, RuleConditionInput, RuleAction, RuleActionType, RuleField, RuleOperator.
  • Webhooks: WebhookCreate, WebhookPatch, WebhookResource, CreatedWebhookResource, DeletedWebhookResource, WebhookDeliveryResource, WebhookTestResource, WebhookEvent, WebhookPayload, EmailOpenedData, EmailClickedData, EmailDownloadedData, VerifyWebhookProps, WebhookSignatureHeaders.
  • Calendar and settings: CalendarRangeOptions, CalendarOccurrenceResource, CalendarEventResource, CalendarAttendeeResource, SettingsPatch, SettingsResource.
  • Roles, members and keys: RoleCreate, RolePatch, RoleDeleteOptions, RoleResource, DeletedRoleResource, PermissionResource, MemberAdd, MemberPatch, MemberAddressGrant, MemberResource, MemberAddressResource, RemovedMemberResource, MemberAccess, KeyResource, PingResource.
  • Disposable inboxes: TempInboxCreate, TempMessageListOptions, TempInboxResource, CreatedTempInboxResource, DeletedTempInboxResource, TempDomainResource, TempMessageResource, TempMessagesResource, TempMessageDetailResource, DeletedTempMessageResource.
  • Shared: RecipientInput, AttachmentInput, AttachmentResource, MessageResource, MessageEncryption, MessageEncryptionFormat, TrackingRequest, TranslateOptions, SendTranslateOptions, LanguageResource, ApiScope, Permission, BuiltinRole, HitKind.

An endpoint this does not wrap yet

An SDK release should never be what stands between you and an endpoint that already works. openemail.raw.request() takes a path and options and resolves to the parsed body, with the client’s key, base URL, timeout and retry policy applied.

escape-hatch.ts
const result = await openemail.raw.request<Whatever>('/something-new', {  method: 'POST',  query: { dryRun: true },  body: { name: 'Invoices' },  repeatable: true,})

A GET is retried like any other read. Any other method is sent once unless you pass repeatable: true, which is your assertion that it may be sent twice. query skips values that are undefined, and signal works as it does on every other method.

What it deliberately does not do

  • It validates no request body. The server's schema is the only copy of the rules, and a second copy here would eventually refuse an address a newer server accepts, in a version somebody pinned two years ago.
  • It ships no zod and no runtime dependencies at all.
  • It reshapes a response in one way only: a collection’s data array is lifted out of its envelope. A paged list hands it back as items beside hasMore and nextCursor, emails.sendBatch as items beside sent and failed, tempMail.listMessages as items beside expiresAt, and addresses.list as addresses beside unrestricted and domains. Everywhere else it is a plain array. Every resource inside keeps the documented HTTP shape.

The package’s parity check keeps this honest. It fails the build when a documented operation has no method, when a method points at an operation the OpenAPI document does not have or sends a different request, and when a method declares scopes the operation does not require.