Migrating email infrastructure is more than replacing an API key. To migrate from Elastic Email to Volanea safely, preserve the systems around sending too: authenticated domains, recipient suppression history, template rendering, event-driven application logic, and the operational controls that prevent duplicate or unwanted mail.

Elastic Email provides a broad platform that includes transactional sending, SMTP, campaigns, contacts, templates, webhooks, inbound routes, suppressions, subaccounts, and reporting. Volanea is designed around developer-facing transactional and campaign email infrastructure. That makes the code cutover approachable, but it does not make every Elastic Email feature a one-for-one transfer. The safest plan separates the work into inventory, parallel validation, a controlled production cutover, and post-migration monitoring.

This guide uses Node.js examples, but the migration principles apply to any language or framework.

Start with an inventory, not a key swap

Before creating a Volanea integration, document how your application actually uses Elastic Email. A quick scan for elasticemail, x-elasticemail-apikey, SMTP credentials, template names, webhook URLs, and Elastic Email dashboard exports will usually reveal more dependencies than the primary send call.

Create an inventory that answers four questions:

What sends email? List every service, worker, cron job, admin tool, serverless function, and third-party integration that sends through Elastic Email.
What kind of email is sent? Separate password resets, verification codes, receipts, alerts, invitations, lifecycle email, newsletters, and large campaign sends. Their urgency, consent requirements, and expected volume differ.
What state lives in Elastic Email? Identify templates, contacts, lists, segments, suppression data, webhooks, inbound routing rules, files, API keys, SMTP credentials, subaccounts, and scheduled campaigns.
What consumes email events? Find downstream jobs that change user state after an open, click, bounce, complaint, unsubscribe, or delivery event.

Do not assume your application is the only sender. A common migration failure is moving the main web app while a background billing worker, legacy CMS plugin, or support tool continues sending through the old account. That fragments deliverability data and can make debugging confusing.

Classify sending paths by risk

Give each mail stream an owner and a migration priority. Password resets and login codes should normally move only after successful staging and canary testing. Receipts and order status messages are also high priority because a missing or duplicated message creates customer-support work. Marketing campaigns may be lower urgency, but they often have the largest suppression and consent-management implications.

A useful classification looks like this:

Critical transactional: authentication, payment confirmations, password resets, security alerts.
Important transactional: invitations, product notifications, account changes, support updates.
Lifecycle or campaign: onboarding series, announcements, newsletters, re-engagement.
Operational: internal alerts, test messages, exports, monitoring notifications.

This classification lets you move low-risk traffic first while retaining a simple rollback option for critical paths.

Understand the scope of the Elastic Email migration

Elastic Email’s REST API v4 covers more than sending messages. Its documented resources include transactional and bulk email, contacts, campaigns, lists, segments, templates, suppressions, bounce and complaint lists, events, webhooks, SMTP credentials, domains, files, inbound routes, and subaccounts. Your migration should explicitly decide which of those resources move, which remain in another system of record, and which are retired.

For a typical product-email workload, the essential migration scope is:

Sending domain authentication and sender identities.
API or SMTP integration.
Transactional templates and personalization data.
Event webhooks and event-to-user-state mappings.
Global and application-level suppression handling.
Message identifiers, logs, retries, and observability.

For teams that use Elastic Email for newsletters, contact storage, segmentation, automations, or a visual campaign workflow, the scope is larger. Volanea may become your delivery layer while your CRM, product database, or marketing automation platform remains responsible for audiences and campaign orchestration. That can be an improvement in ownership clarity, but it requires a deliberate design rather than an assumption that provider-managed contacts and segments will appear automatically.

Decide where the source of truth belongs

A robust architecture keeps product consent and recipient state in your own database or a dedicated customer-data system. The email provider then enforces a synchronized suppression layer rather than becoming the only record of whether a person opted out.

For example, an application might keep these fields on a contact record:

email
marketing_opt_in
marketing_opt_in_at
transactional_email_allowed
global_suppressed_at
suppression_reason
last_email_provider_message_id

This does not eliminate provider suppressions. It ensures that a provider migration does not accidentally erase your organization’s record of opt-out intent. It also gives your application a consistent answer when a user asks to unsubscribe, resubscribe, or delete their data.

Prepare Volanea before changing production code

Set up Volanea as an independent, testable sending environment before touching production traffic. Create the credentials and verified sender domain required for the mail streams you intend to move. Keep the new credential scoped to the application or environment that needs it; avoid sharing one long-lived key across development, staging, workers, and production.

Use an environment-variable strategy such as:

VOLANEA_API_KEY=replace-with-production-secret
EMAIL_FROM=Acme <notifications@mail.example.com>
EMAIL_REPLY_TO=support@example.com
EMAIL_PROVIDER=volanea

Store these values in your platform’s secret manager. Do not commit provider keys into application configuration, browser code, client-side bundles, screenshots, or ticket comments.

Read the current API reference and setup guides when creating the production integration. In particular, confirm the current endpoint, authentication header, supported message fields, attachment format, idempotency behavior, webhook signing scheme, and event payload before implementing the Volanea client. Those details are integration contracts, not values to infer from a different provider.

Use a provider adapter

If your application calls Elastic Email directly from many files, first introduce a small internal mail interface. This turns a provider migration into one implementation change instead of a repository-wide edit.

type OutboundEmail = {
  to: string[];
  from: string;
  replyTo?: string;
  subject: string;
  html?: string;
  text?: string;
  tags?: Record<string, string>;
  idempotencyKey?: string;
};

type SendResult = {
  providerMessageId: string;
};

interface EmailProvider {
  send(message: OutboundEmail): Promise<SendResult>;
}

Keep business logic above this boundary. A password-reset flow should ask emailProvider.send() to deliver a message; it should not need to know whether the provider uses an Elastic Email SDK object, an HTTP request, or SMTP.

That boundary also makes rollback much safer. A feature flag can choose elasticEmailProvider or volaneaProvider for a narrow group of messages without changing the password-reset, order, or invitation application code.

Side-by-side code comparison: Elastic Email SDK to Volanea

Elastic Email’s official JavaScript client is published as @elasticemail/elasticemail-client and its v4 API uses an API key. A typical transactional call builds an EmailTransactionalMessageData object and sends it through the transactional email resource.

The exact Volanea REST endpoint and authentication details should be taken from your Volanea account documentation at implementation time. The comparison below therefore shows the migration at the application adapter boundary: the left side is an Elastic Email SDK call; the right side is the equivalent Volanea send operation implemented in your Volanea provider adapter. Keeping the provider-specific request inside that adapter prevents Elastic-specific models from leaking into the rest of your code.

Before: Elastic Email SDK	After: Volanea provider adapter
```ts
import * as ElasticEmail from '@elasticemail/elasticemail-client';

const client = ElasticEmail.ApiClient.instance; client.authentications.apikey.apiKey = process.env.ELASTIC_EMAIL_API_KEY!;

const emailsApi = new ElasticEmail.EmailsApi();

const message = new ElasticEmail.EmailTransactionalMessageData(); message.recipients = [ new ElasticEmail.EmailRecipient('ada@example.com') ]; message.content = new ElasticEmail.EmailContent( 'Acme notifications@mail.example.com', 'Reset your password', [ new ElasticEmail.BodyPart( 'HTML', '<p>Use this link to reset your password.</p>' ), new ElasticEmail.BodyPart( 'PlainText', 'Use this link to reset your password.' ) ] );

const response = await emailsApi.emailsTransactionalPost(message); const providerMessageId = response.messageid; |ts // volanea-provider.ts export async function sendViaVolanea( message: OutboundEmail ): Promise<SendResult> { // Build this request using the current Volanea API contract // from your account documentation. Keep it isolated here. const response = await volaneaTransport.send({ from: message.from, to: message.to, replyTo: message.replyTo, subject: message.subject, html: message.html, text: message.text, tags: message.tags, idempotencyKey: message.idempotencyKey });

return { providerMessageId: response.providerMessageId }; }

// password-reset.ts const result = await sendViaVolanea({ from: 'Acme notifications@mail.example.com', to: ['ada@example.com'], subject: 'Reset your password', html: '<p>Use this link to reset your password.</p>', text: 'Use this link to reset your password.', tags: { type: 'password-reset' }, idempotencyKey: password-reset:${resetRequestId} });


The important migration is not merely converting property names. It is preserving the message’s meaning: the same visible From identity, recipient list, reply-to behavior, HTML and text alternatives, metadata, and application correlation key.

### Why the adapter is more useful than a direct rewrite

An SDK call often encourages provider-specific objects throughout a codebase. For example, an Elastic Email `EmailRecipient`, content model, template reference, or channel can become entwined with application logic. A provider-neutral `OutboundEmail` makes the change auditable.

It also lets you test the same application behavior against a fake mail provider. In unit tests, assert that a reset flow requests an email to the correct address with a valid reset URL. In integration tests, verify that the Volanea adapter maps the normalized message into the provider’s accepted request shape.

### Preserve idempotency at the application level

A timeout does not prove that a send failed. The provider might have accepted and queued the message just before your HTTP client lost the response. Retrying blindly can send duplicate receipts or reset links.

Generate a stable key from the business event, not from the retry attempt. Good examples include `invoice:12345:receipt`, `user:42:verify-email:v3`, or `password-reset:request_abc`. Store the result of the send attempt with that key. If Volanea supports an idempotency mechanism, pass the same key according to its documented contract; if not, keep the deduplication decision in your own database or job queue.

## Re-authenticate domains without breaking existing mail

A provider change requires fresh domain authentication. Elastic Email’s SPF and DKIM authorizations are provider-specific. They do not authorize Volanea to send just because the visible From address is unchanged.

Add the DNS records Volanea generates for your sending domain, then verify them in Volanea before routing production traffic. Do not copy record names or values from a generic example, an old provider, or this guide. DNS values, selectors, and tracking-domain records are account- and provider-specific.

### DNS and identity checklist

Use this checklist during the cutover:

- [ ] Verify the exact From domains and subdomains used by every mail stream.
- [ ] Add Volanea’s provided DKIM records exactly as generated.
- [ ] Update the existing SPF TXT record rather than creating a second SPF record at the same hostname.
- [ ] Keep Elastic Email’s SPF authorization temporarily if any application, campaign, or fallback path still sends through Elastic Email.
- [ ] Confirm the resulting SPF record stays within SPF lookup limits and contains only legitimate senders.
- [ ] Confirm DKIM passes for a real message sent through Volanea.
- [ ] Check that SPF or DKIM alignment satisfies your domain’s DMARC policy using the visible From domain.
- [ ] Preserve the existing DMARC record unless you intentionally change policy or reporting.
- [ ] Add or migrate any custom tracking-domain DNS record only after considering link continuity and analytics consequences.
- [ ] Verify reply-to inboxes, return-path behavior, and any branded bounce domain requirements.
- [ ] Remove Elastic Email DNS authorizations only after all Elastic sending has stopped and a defined observation period has passed.

SPF deserves special care. A domain must not publish multiple independent TXT records beginning with `v=spf1`; receivers may treat that as a permanent SPF error. Merge legitimate mechanisms into one record and remove provider mechanisms only when they are no longer needed.

### Avoid a same-minute DNS and traffic cutover

DNS propagation and verification timing are not a dependable release mechanism. Authenticate Volanea in advance, send test messages, inspect their headers, and verify authentication before changing application routing. Then move traffic independently through a deployment or feature flag.

For a high-volume sender, start with a controlled portion of a low-risk transactional stream. Monitor acceptance, bounces, complaints, and user reports. Increase gradually only when the provider event data and mailbox results match expectations.

## Migrate templates, content, and personalization deliberately

Do not assume stored templates can be copied as files and behave identically. HTML itself is portable, but template systems frequently differ in variable syntax, conditional logic, loops, escaping defaults, helper functions, unsubscribe tokens, and how missing variables are handled.

Elastic Email supports templates and campaign-oriented content management. If your product currently calls an Elastic Email template by name or ID, choose one of two migration designs:

1. **Render in your application.** Store templates in your repository or content system, render them with your application’s templating engine, and send HTML plus plain text through Volanea.
2. **Use Volanea templates where appropriate.** Recreate transactional templates in Volanea and map your application variables to the template’s documented data model.

The first approach gives stronger version control, local testing, code review, and portability. The second can be convenient for non-engineering edits, but requires careful governance around template publication and variable changes.

### Template migration checklist

For every template, record:

- Template name or identifier and its business purpose.
- Subject-line logic and preview text.
- HTML and plain-text versions.
- Every variable, its data type, and its fallback behavior.
- Conditional sections and loops.
- Locale and currency formatting rules.
- Links, UTM parameters, tracking settings, and unsubscribe placement.
- Attachments, inline images, and hosted assets.
- Legal footer and sender identity.

Then create rendered snapshots for representative cases: a normal recipient, a recipient with a long name, missing optional data, non-ASCII characters, a mobile-width layout, and every supported locale. Compare the old and new message visually and inspect the MIME source where possible.

### What is harder to migrate

Template syntax differences are one of the genuinely harder parts of this move. A variable expression that works in Elastic Email may not work in Volanea or in your application renderer. Even familiar double-brace syntax can differ in escaping, filters, fallback values, HTML safety, or whitespace handling.

Do not do a blind find-and-replace across templates. Translate one template, establish a test fixture for its input data and expected output, then use that pattern for the rest. Treat email HTML changes as production UI changes: review them in real email clients, not only in a browser preview.

Campaign automations, visual designer-only constructs, stored lists, and segments may also have no direct transactional-provider equivalent. Export the content and audience logic, then decide whether the right destination is your application, CRM, CDP, or separate marketing tool.

## Export suppressions and protect recipient intent

The most important data to preserve is often not the contact list. It is the list of addresses that must **not** receive a given class of email.

Elastic Email exposes suppressions as well as bounce, complaint, and unsubscribe resources. Export the relevant data before cutover, retain a secure backup, and document the export timestamp, source, volume, and reason categories. Normalize addresses consistently before import, but do not “clean” the list by dropping ambiguous records without a documented policy.

### A practical suppression policy

At minimum, keep separate concepts for:

- **Marketing unsubscribes:** never add these recipients back to marketing sends merely because the delivery provider changed.
- **Spam complaints:** treat as high-risk suppression records; do not reactivate automatically.
- **Hard bounces or permanent delivery failures:** suppress unless the address is corrected through an explicit, verified process.
- **Temporary failures:** do not confuse a transient failure with a permanent opt-out.
- **Application-level blocks:** fraud, account closure, legal requests, or user-specific communication preferences.

Before importing into Volanea, map each category to its documented suppression capabilities. If a provider-level import cannot retain every reason category or timestamp, preserve the complete canonical export in your own secure data store and enforce additional blocks in the application before calling the send API.

Large historical suppression lists are harder to migrate than they sound. Files may contain duplicates, invalid formatting, stale temporary bounces, inconsistent casing, identifiers from different subaccounts, or records with no clear reason. Import operations may be asynchronous or rate-limited. Start early, validate counts after import, and reconcile samples across categories.

Never send a “reconfirmation” email to addresses on a complaint or unsubscribe list solely because you have changed platforms. A migration is an infrastructure event, not renewed consent.

## Rebuild webhook processing as an event pipeline

Elastic Email can send event notifications through webhooks, and Volanea event payloads should be treated as a new contract rather than assumed to match Elastic Email’s format. Event names, identifiers, batching behavior, retry behavior, signature validation, timestamps, and fields may differ.

Build a translation layer between Volanea’s webhook payload and your internal event model. Your application should consume normalized events such as:

```ts
type EmailEvent = {
  provider: 'elastic-email' | 'volanea';
  providerMessageId: string;
  eventType: 'accepted' | 'delivered' | 'bounced' | 'complained' |
             'opened' | 'clicked' | 'unsubscribed';
  recipient?: string;
  occurredAt: string;
  rawEventId?: string;
};

This keeps downstream systems from relying on a provider’s raw event schema.

Webhook re-verification checklist

Do not make business-critical actions depend only on opens or clicks. Privacy protections, image blocking, and mailbox-provider behavior can make engagement events incomplete. Delivery, bounce, complaint, unsubscribe, and your own product events are generally more appropriate for operational decisions.

Run a staged cutover with a rollback path

A controlled migration minimizes both deliverability risk and debugging time. Avoid a big-bang switch unless the volume is negligible and the sending path is extremely simple.

Suggested cutover sequence

Build and test the Volanea adapter in development. Use safe test recipients and verify content, authentication, logs, and response handling.
Deploy with sending disabled. Confirm credentials load only on the server and that the feature flag defaults to Elastic Email.
Send internal canaries through Volanea. Cover common mailbox providers and inspect headers for From identity, DKIM, SPF, DMARC, reply-to, links, and plain text.
Move one low-risk transactional stream. Use a small percentage or a narrow internal cohort.
Validate webhooks and suppression behavior. Trigger a controlled bounce or use test scenarios where permitted; verify that your application handles the resulting events correctly.
Move critical transactional traffic gradually. Monitor duplicate sends, delivery failures, support tickets, and latency.
Move campaign or lifecycle sends only after audience and unsubscribe processes are proven.
Keep Elastic Email available for rollback during the observation window. Do not delete credentials, templates, or DNS authorization prematurely.
Decommission deliberately. Remove old credentials from applications, revoke them in Elastic Email, retire unneeded DNS records, and preserve required exports according to your retention policy.

Define rollback before the first production send

Rollback should be a configuration change, not an emergency code rewrite. Define the trigger conditions in advance: unexpected authentication failures, elevated bounce or complaint rate, broken webhook processing, missing receipts, duplicate sends, or a sustained provider/API error pattern.

A rollback may mean routing new sends back to Elastic Email, but it should not mean discarding events already accepted by Volanea. Track provider message IDs and idempotency keys so that the fallback path does not resend messages already queued by the new provider.

Compare operational tradeoffs honestly

Elastic Email may be the better fit for teams that rely on its integrated campaign-management, contact, list, segment, automation, subaccount, inbound-route, or visual-email features. Moving away from those features can require replacing workflow and data-management capabilities, not just delivery infrastructure.

Volanea can be a better fit when a team wants a developer-centered sending integration with a clean separation between application data, sending, deliverability operations, and campaign orchestration. That separation can simplify deployments and make email behavior easier to test in code, but it also places more responsibility on your team to own templates, consent state, segmentation, and analytics if those previously lived in the provider.

Cost comparison should also be based on actual behavior rather than headline volume. Include message volume, peak throughput, attachment usage, event retention, dedicated IP or deliverability needs, support expectations, campaign workloads, and engineering time. Review sending plans and email costs with the same message categories and projected monthly volume used in your migration inventory.

Validate deliverability after the code works

A successful API response means the provider accepted a request. It does not prove inbox placement, authentication alignment, content quality, or recipient experience.

During the first weeks after cutover, monitor:

API acceptance and error rates.
Queueing and delivery latency for time-sensitive messages.
Hard and soft bounce rates by mail stream and domain.
Complaint and unsubscribe rates.
Authentication results in real message headers.
Recipient support tickets about missing, duplicate, malformed, or delayed email.
Template rendering errors and missing personalization values.
Webhook delivery, signature-verification, and processing failures.

Compare equivalent streams, not aggregate account totals. Password reset email behaves differently from a newsletter, and an invoice recipient population behaves differently from a new-user cohort. A sudden change in one stream may be hidden inside an account-wide average.

Keep a migration log with deployment times, configuration changes, DNS changes, API key rotations, webhook changes, and traffic-percentage adjustments. When an anomaly appears, this timeline is often more useful than guessing whether a provider change caused it.

Final migration checklist

Before declaring the move complete, confirm all of the following:

FAQ

How long does it take to migrate from Elastic Email to Volanea?

A simple transactional integration with one authenticated domain and application-rendered templates can often be implemented in days. A migration involving campaigns, contact lists, segments, automations, historical suppressions, custom tracking domains, multiple subaccounts, or inbound routing needs more planning and validation.

Can I keep Elastic Email and Volanea active during the migration?

Yes. Keeping both active during a staged cutover is usually safer. Authenticate Volanea first, route a controlled set of messages through it, and retain Elastic Email as a rollback option until monitoring confirms the new path is stable.

Do I need to change my SPF and DKIM records?

Yes. Volanea needs its own current authorization records. Add the Volanea-generated records, preserve Elastic Email authorization only while Elastic Email still sends for that domain, and avoid publishing multiple SPF records.

Can I import Elastic Email suppressions directly?

Export and preserve them first, then import or enforce them according to Volanea’s documented suppression workflow. Reconcile counts and categories, especially unsubscribes, complaints, and permanent failures. Large or messy historical lists often require normalization and a documented policy for ambiguous records.

What is the biggest migration risk?

The biggest risk is treating the migration as an API-key replacement. The code change is only one component; authentication, template rendering, consent history, webhook behavior, retries, and operational monitoring determine whether recipients receive the right email exactly once.

Migrate from Elastic Email to Volanea: Developer Guide