Versioning

How the wemail API is versioned: v3 is pinned in the URL, additive changes ship continuously, breaking changes get a new version supported for 18 months.

The current version of the wemail API is v3, and the version is part of the URL: https://api.wemail.io/v3/messages. There is no version header to send and no per-account version setting — the path you call is the contract you get. This page explains what can change under v3 without notice, what cannot, and how a future version would be introduced.

Backwards-compatible changes

These ship continuously, are listed in the changelog, and never require action on your side. Your integration should be written to tolerate them. They are: new optional request fields and query parameters; new fields in responses and webhook payloads; new event types delivered to endpoints that subscribed to *all events*; new error codes under existing HTTP statuses; new endpoints; new enum values on fields documented as extensible (for example a new sub_status in verification results); longer strings and ids within documented limits; and changes to the order of keys in a JSON object.

Breaking changes

A breaking change is anything that could make a correct integration stop working: removing or renaming a field, endpoint or event type; changing a field's type or meaning; making an optional field required; tightening validation so previously accepted requests fail; changing authentication; or changing the shape of the error body. Breaking changes are never made to v3. They ship as a new version at a new path, with v3 continuing to work unchanged alongside it.

Deprecation policy

When a new version is released, the previous one is supported for at least 18 months from the day it is marked deprecated. During that period it receives security fixes and keeps its documented behaviour; new features land only in the current version. Deprecations and the sunset date are announced in the changelog at wemail.io/changelog, in the Console under What's new, and on the affected pages of this documentation. Within a version, individual fields are occasionally deprecated the same way — they keep working and are flagged in the reference until the next major version removes them.

Pinning in practice

Because the version lives in the path, pinning is automatic: a client configured for /v3/ keeps talking to v3 until you change it. The official SDKs bind to one API version per SDK major version, so upgrading the SDK major is how you move; a minor or patch SDK release never changes the API version it calls. The OpenAPI document at https://wemail.io/openapi.json describes the current version and is the source the SDKs, the CLI and the MCP server are generated from.

// The base URL is the pin. Change it deliberately, together with an SDK major upgrade.
const wemail = new WemailClient(process.env.WEMAIL_API_KEY, {
  baseUrl: 'https://api.wemail.io/v3',
});

Writing a change-tolerant client

Ignore unknown fields when parsing responses and webhooks instead of failing on them. Switch on event type with a default branch that logs and acknowledges. Treat enums as open sets. Read limits such as page sizes and attachment caps from the Rate limits and Attachments pages rather than hard-coding them, and rely on the request_id in every error body when contacting support. Clients built this way have never needed a change for a v3 release.

Provider bridges and SMTP

The drop-in bridges for Mailgun, SendGrid, Brevo, Postmark, Mailjet, MailerSend, SparkPost and Mandrill clients follow the versioning of the provider API they imitate, not wemail's; they translate to v3 internally. The SMTP relay is protocol-versioned by the RFCs it implements and is not affected by API versions.