Mandrill to Volanea Migration Guide for Developers

Mandrill to Volanea migration is more than replacing an API key: it is a controlled move of sending identity, delivery safeguards, application behavior, and operational visibility. The safest approach is to run the work in stages, prove every critical message type in a non-production path, and cut over only after DNS, webhook processing, and suppression handling are ready.

Mandrill—now Mailchimp Transactional Email—remains a capable transactional email service with a mature API, SMTP support, stored templates, merge variables, tags, inbound processing, and detailed event concepts. A move to Volanea should therefore begin with an inventory of the Mandrill features your application actually depends on, not an assumption that every field or workflow has an identical replacement.

This guide focuses on a developer-owned migration: moving application sends, preserving recipient safety, re-verifying domain authentication, translating operational behavior, and establishing a rollback plan. It does not assume that you must abandon every Mandrill capability on day one. In many cases, a short parallel period is the most responsible way to migrate.

Start with a migration inventory, not a send-call swap

The first task is to identify what Mandrill currently does for your product. A small application may have one password-reset send path and a single verified sender. A mature system may have receipts, alerts, account invitations, customer-support replies, batch notifications, scheduled sends, templates, inbound routes, metadata, tracking controls, and several sending domains.

Document each message type before changing infrastructure. Your inventory should answer four questions:

1. What triggers the email? For example: a password-reset request, a successful payment, a shipment update, a new team invitation, or an internal alert.
2. Which application owns the send? Record the service, queue worker, cron job, serverless function, or third-party integration that initiates it.
3. Which Mandrill-specific options are in use? Look for templates, merge variables, tags, metadata, custom headers, scheduled delivery, attachments, inline images, tracking flags, IP pools, subaccounts, or inbound routes.
4. What must happen after send? List the data stores and automations that react to delivered, bounced, opened, clicked, spam-complaint, rejected, or inbound events.

This inventory becomes your acceptance criteria. If an order-confirmation email used to contain a PDF attachment, track a receipt tag, store an order ID in metadata, and update a delivery record when a webhook arrives, the migration is not complete until the new path preserves the intended behavior—or until you have deliberately changed and documented it.

Separate critical and noncritical mail

Do not cut all traffic over at once merely because every message uses the same Mandrill account. Divide sends into tiers:

• Tier 1: password resets, verification codes, login alerts, payment receipts, invoices, security notices, and required account messages.
• Tier 2: invitations, onboarding messages, product notifications, shipping updates, and support follow-ups.
• Tier 3: lower-urgency reminders, product education, digests, and promotional or lifecycle mail.

Start validation with Tier 1, but do not use live customers as your test suite. Create controlled test recipients at major mailbox providers, use realistic content, and confirm the complete path from application event through inbox placement and webhook processing.

Choose the right cutover architecture

There are two common ways to perform a Mandrill to Volanea migration: a direct replacement or a staged provider abstraction. The right option depends on how much provider-specific logic already lives in your application.

Direct replacement

A direct replacement is appropriate when your Mandrill integration is narrow: perhaps one service sends a small set of messages, templates are rendered in your application, and the only provider integration is a simple API or SMTP call.

In that case, you can add Volanea credentials, verify a sending domain, replace the transport, deploy to a test environment, and then direct selected production message types to the new provider. Keep the Mandrill path available during the observation window so that you can roll back individual message classes without redeploying unrelated code.

Provider adapter

An adapter is safer when Mandrill calls are scattered throughout a monolith, multiple workers, or several services. Instead of calling an email vendor directly from business logic, route email through an internal interface such as sendEmail(message).

The adapter should normalize only the capabilities your product genuinely needs. For example:

export type OutboundEmail = {
  from: { email: string; name?: string };
  to: Array<{ email: string; name?: string }>;
  subject: string;
  html?: string;
  text?: string;
  replyTo?: string;
  headers?: Record<string, string>;
  tags?: string[];
  metadata?: Record<string, unknown>;
  attachments?: Array<{
    filename: string;
    contentType: string;
    contentBase64: string;
    contentId?: string;
  }>;
};

Your application can then preserve its business-level contract while the Mandrill adapter and the Volanea adapter handle transport-specific differences. This is especially useful if stored templates, recipient merge data, or event payloads differ enough that a one-for-one field translation would be misleading.

An adapter does not need to hide every provider feature. It should make tradeoffs explicit. If a Mandrill-only feature has no direct equivalent in your Volanea implementation, expose that as a migration decision instead of silently dropping it.

Before and after: Mandrill SDK call versus Volanea SMTP call

Mandrill supports both API and SMTP sending. If your Mandrill code uses the API, switching to Volanea over SMTP can be a practical first migration step because SMTP is broadly supported by standard libraries and lets you keep email construction in application code.

The example below uses the older node-mandrill package style on the left because it illustrates a common Mandrill SDK pattern: call messages.send() with a nested message object. On the right, the equivalent Volanea send uses Nodemailer. Do not hard-code SMTP hostnames, ports, usernames, or passwords from examples; copy the current Volanea SMTP credentials and TLS requirements from the email API reference and setup guides.

Before: Mandrill SDK send

const mandrill = require('node-mandrill')(process.env.MANDRILL_API_KEY);

function sendPasswordReset({ recipient, resetUrl, userId }) {
  return new Promise((resolve, reject) => {
    mandrill('/messages/send', {
      message: {
        from_email: 'security@example.com',
        from_name: 'Example App',
        to: [
          {
            email: recipient,
            type: 'to'
          }
        ],
        subject: 'Reset your password',
        html: `
          <p>We received a request to reset your password.</p>
          <p><a href="${resetUrl}">Reset password</a></p>
        `,
        text: `Reset your password: ${resetUrl}`,
        headers: {
          'Reply-To': 'support@example.com'
        },
        tags: ['password-reset'],
        metadata: {
          user_id: userId,
          message_kind: 'password_reset'
        },
        track_opens: false,
        track_clicks: false
      }
    }, (error, result) => {
      if (error) return reject(error);
      resolve(result);
    });
  });
}

After: Volanea SMTP send with Nodemailer

const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: process.env.VOLANEA_SMTP_HOST,
  port: Number(process.env.VOLANEA_SMTP_PORT),
  secure: process.env.VOLANEA_SMTP_SECURE === 'true',
  auth: {
    user: process.env.VOLANEA_SMTP_USERNAME,
    pass: process.env.VOLANEA_SMTP_PASSWORD
  }
});

async function sendPasswordReset({ recipient, resetUrl, userId }) {
  const result = await transporter.sendMail({
    from: 'Example App <security@example.com>',
    to: recipient,
    subject: 'Reset your password',
    html: `
      <p>We received a request to reset your password.</p>
      <p><a href="${resetUrl}">Reset password</a></p>
    `,
    text: `Reset your password: ${resetUrl}`,
    replyTo: 'support@example.com',
    headers: {
      'X-Message-Kind': 'password_reset',
      'X-Application-User-Id': String(userId)
    }
  });

  return result;
}

The two snippets intentionally show an important migration distinction: Mandrill fields such as tags, metadata, track_opens, and track_clicks are API-level provider features. Standard SMTP itself does not create equivalent delivery analytics or metadata semantics. If your application relies on those features, use Volanea’s supported REST API fields and webhook model as documented rather than assuming that custom SMTP headers automatically become filterable provider metadata.

That distinction is one reason a migration should not be measured by whether the application receives a successful sendMail() result. A successful handoff means the SMTP server accepted the message for processing; it does not prove inbox placement, delivery, or that your downstream event pipeline works.

Preserve idempotency above the provider

Neither a Mandrill-to-Volanea move nor a switch from API to SMTP removes the risk of duplicate sends. A timeout after the provider accepts a request can leave your application uncertain whether the recipient already received the message.

Store an application-owned message ID before attempting delivery. Associate it with a stable event ID—for example, password-reset-request:usr_123:request_456 or invoice:inv_912:paid. Before retrying a failed job, check whether that logical message was already accepted or finalized. This protects customers from duplicate receipts, duplicate reset emails, or multiple security alerts during transient failures.

Re-verify domain authentication before changing production traffic

Sending identity is the highest-risk part of the migration. Your From address may remain the same, but the underlying provider changes. DNS records that authenticated mail sent through Mandrill may not authorize mail sent through Volanea.

Treat Volanea domain setup as a fresh verification exercise. Do not delete Mandrill records until Volanea is verified, you have sent test messages, and you have confirmed that the authentication results align with your domain policy.

DNS and authentication checklist

Use the exact records Volanea provides for your domain. Record names and values are provider- and domain-specific, so avoid copying values from another account, environment, or provider guide.

• Add and verify the Volanea sending domain before routing production mail.
• Review the existing SPF TXT record at the organizational domain and any sending subdomain.
• Merge provider-authorized SPF mechanisms carefully; publish one SPF record per hostname rather than creating competing TXT records.
• Add the DKIM records Volanea supplies and confirm that they resolve publicly.
• Check that the visible From domain can achieve DMARC alignment through SPF and/or DKIM for the messages you intend to send.
• Review your DMARC policy before cutover, especially if it is set to quarantine or reject.
• Verify any custom return-path, bounce, tracking, or link-branding domains required by your Volanea configuration.
• Keep Mandrill authentication records in place until traffic is fully cut over and the rollback window has passed.
• Test a real message and inspect the received authentication results at more than one mailbox provider.

SPF deserves particular care. The typical error is not a typo—it is publishing multiple SPF TXT records or exceeding SPF lookup limits after adding another provider. A record that worked before can become invalid after an apparently harmless include change. Make SPF changes through the team or infrastructure-as-code process that owns DNS, and capture the pre-migration record so rollback is straightforward.

DKIM should be verified with actual received mail, not only DNS lookup. A DNS record can exist while the selected key is not used for a particular stream or sender. Check the message headers to confirm that DKIM passes and that the signing domain is appropriate for your DMARC alignment goals.

For a quick pre-send hygiene check, use an email address verification tool on test and imported addresses where appropriate. Address verification is not a replacement for suppression handling, consent, or bounce processing, but it can help reduce avoidable first-send failures.

Export and preserve Mandrill suppressions

Suppression migration is a recipient-protection task, not an optional data import. A recipient who hard-bounced, complained, unsubscribed from a relevant message class, or was manually suppressed in Mandrill should not suddenly begin receiving mail because the provider changed.

Mailchimp Transactional provides rejection-list and export capabilities, including an export for the rejection denylist. The exported data can include an address, reason, detail, creation time, expiry information, and the last event time. Preserve the source export securely because it is your evidence of why an address was not mailed.

Build a normalized suppression file

Before importing or recreating suppressions in Volanea, normalize the export into a controlled format. Do not blindly treat every historical row as equally permanent.

A useful internal schema looks like this:

email,suppression_scope,reason,source,created_at,expires_at,notes
hardbounce,global,hard_bounce,mandrill,2024-02-10T12:30:00Z,,"mailbox unavailable"
complaint,global,spam_complaint,mandrill,2024-03-11T09:15:00Z,,"recipient marked spam"
manual,global,manual_block,mandrill,2024-04-21T08:00:00Z,,"support request"

In practice, the email column contains the recipient address; the labels above illustrate how you might classify records in your internal transformation. Keep the original Mandrill reason and detail as audit data even if Volanea uses a different set of reason labels.

Make explicit policy decisions for temporary failures, expired entries, and product-level opt-outs. A transient soft bounce years ago may not deserve a permanent global block. A complaint, explicit do-not-contact request, or hard bounce usually needs more conservative treatment. Your compliance, deliverability, and customer-support owners should agree on the policy before import.

What makes large suppression lists harder to migrate

Large historical suppression lists are among the hardest parts of a provider move for several reasons:

• Data quality varies. Older rows may lack useful reason codes, expiry dates, or a clear distinction between a complaint and a transient failure.
• Semantics differ. A Mandrill rejection entry, a marketing unsubscribe, an account preference, and a legal do-not-contact request are not the same kind of restriction.
• Import rules may differ. Providers may accept different formats, limit batch sizes, deduplicate differently, or distinguish account-level and list-level suppressions.
• A bad import has consequences. Importing too little can cause unwanted mail and reputation damage. Importing too broadly can prevent legitimate transactional messages from reaching customers.

For a large list, build an import pipeline that validates addresses, deduplicates case-insensitively, records source rows, reports failed imports, and produces counts by reason. Reconcile these counts before and after import. Do not declare success based solely on a request returning HTTP success; compare the intended number of eligible suppression records with the number actually accepted.

Rebuild webhooks as an event-processing system

Mandrill webhooks may already power delivery status updates, bounce handling, engagement analytics, CRM updates, or internal alerts. During a migration, webhook code often breaks not because the endpoint is unreachable, but because event names, JSON shape, identifiers, signature validation, retry behavior, or timestamps differ.

Build the Volanea webhook receiver as a provider-specific ingestion layer followed by provider-neutral business logic. The ingestion layer validates the request and translates it into an internal event. The business layer decides what a bounce, complaint, delivery, open, click, or unsubscribe means for your product.

Webhook migration checklist

• Create a dedicated Volanea webhook endpoint or add provider routing to the existing endpoint.
• Store the raw request body securely for a limited diagnostic retention period.
• Verify webhook authenticity using Volanea’s documented signing or verification method.
• Make processing idempotent using the provider event ID when available, plus a safe fallback deduplication key.
• Return a successful response only after validation and durable enqueueing or storage.
• Process slow tasks asynchronously; do not make the provider wait for CRM calls, data warehouse writes, or customer-notification workflows.
• Map each Volanea event to your internal event names and states.
• Test retry behavior, out-of-order events, duplicate events, and malformed payloads.
• Monitor endpoint errors, queue depth, retry volume, and events that cannot be mapped.

A durable internal event could look like this:

{
  provider: 'volanea',
  providerEventId: 'provider-specific-id',
  providerMessageId: 'provider-specific-message-id',
  type: 'email.bounced',
  occurredAt: '2026-08-03T12:34:56Z',
  recipient: 'person@example.net',
  messageKind: 'password_reset',
  metadata: {
    applicationMessageId: 'msg_01H...'
  },
  raw: { /* encrypted or access-controlled provider payload */ }
}

Do not assume event order. A delivery event can be delayed, an open can arrive long after the underlying send, and retries can duplicate an event. Your state transitions should therefore be monotonic where possible: for example, a hard bounce should not be overwritten by a later delayed “processed” event.

Map Mandrill features deliberately

Mandrill’s API supports a broad set of message controls. Some map naturally to an application-owned email model; others need redesign, provider-specific implementation, or a temporary hybrid approach.

Features that usually translate cleanly

The following concepts can generally be represented regardless of whether the new transport is SMTP or REST:

• From name and email address
• To, CC, and BCC recipients
• Subject line
• HTML and plain-text alternatives
• Reply-to address
• Custom headers
• Attachments and inline assets, when supported by the selected transport
• Application-level message type, correlation ID, and business metadata

For portability, keep these values in your own application object rather than constructing them separately inside each provider call.

Mandrill-specific features that may not map 1:1

Audit these carefully before cutover:

The important point is not that every feature must be identical. It is that the difference must be visible to the people who own the resulting product behavior.

Template migration: test rendering, not just source files

Template syntax differences are another honest migration cost. Mandrill templates can use merge tags, merge-language settings, global merge variables, and recipient-level merge variables. Even if two systems both support Handlebars-like syntax, their helpers, escaping rules, fallback behavior, conditional behavior, and treatment of missing values may differ.

For critical transactional mail, the most reliable initial strategy is often to render the final HTML and text in your application. That gives you version control, unit tests, code review, and a single rendering system independent of the sending provider.

A practical template test matrix

For every migrated template, render at least these cases:

1. A normal recipient with complete data.
2. A recipient with optional fields omitted.
3. A recipient whose name or product data contains HTML-sensitive characters.
4. A long value that could affect layout or line wrapping.
5. A locale, currency, date, or timezone variation if the template supports localization.
6. A message with an attachment or inline image, where applicable.
7. Plain-text output as well as HTML output.

Then send the rendered output to real test inboxes. Browser preview alone is not enough for email. Check the visible sender, reply-to behavior, link URLs, unsubscribe or preference links where applicable, image loading, mobile rendering, spam-folder placement, and authentication headers.

Keep a screenshot or rendered artifact for each Tier 1 template. That makes post-cutover regressions easier to diagnose and gives support teams a reference when a customer reports an unexpected email.

Run a controlled parallel test and cutover

A migration should have measurable gates. The goal is not “Volanea sent an email once.” The goal is “the migrated send path performs the required product behavior without weakening recipient protections or observability.”

Suggested rollout sequence

1. Prepare configuration. Add Volanea secrets to your secret manager, create a non-production configuration, and ensure no test environment can mail arbitrary real users.
2. Verify the domain. Publish and validate the required DNS records, then inspect authentication results from actual test sends.
3. Implement the adapter. Preserve a stable internal email contract, build the Volanea transport, and log application message IDs.
4. Create the webhook ingestion path. Verify signatures, persist or enqueue safely, map events, and make handling idempotent.
5. Import suppressions. Reconcile counts, failures, and policy decisions before production sends begin.
6. Migrate one low-risk message type. Prefer a message with enough volume to observe behavior but low enough risk that rollback is manageable.
7. Move Tier 1 messages only after passing tests. Confirm message construction, authentication, receipt, and event handling for each class.
8. Increase traffic gradually. Monitor delivery failures, complaints, customer tickets, webhook errors, and application retry rates.
9. Keep Mandrill available for rollback. Maintain the old credentials and routing path only for the defined rollback window, then revoke them deliberately.

Define rollback before deployment

A rollback plan should specify who can make the decision, what signal triggers it, and how routing changes without creating duplicate messages. Examples of rollback conditions include an authentication failure, sustained webhook verification failures, unexpected suppression import gaps, elevated hard-bounce rates, or a Tier 1 message not reaching controlled test inboxes.

Avoid a rollback that simply resends all queued jobs through Mandrill. If Volanea accepted some messages before the failure was detected, blind retries can duplicate customer communications. Use your application message IDs and delivery ledger to identify only messages that truly require another attempt.

Operational tradeoffs: what stays easier and what gets harder

Mandrill has strengths that may be deeply embedded in an existing implementation. Its stored templates, merge-variable model, message options, rejection-list workflows, and established reporting concepts can make a long-running integration convenient. If your teams are productive with those tools and the integration meets your requirements, there is no technical virtue in changing providers merely for novelty.

Volanea can be a better fit when you want a unified transactional and campaign email platform, a new API or SMTP integration path, or a simpler way to consolidate email infrastructure. But migration introduces real work: DNS verification, event-model translation, suppression reconciliation, template testing, and a new operational runbook.

The difficult areas are predictable:

• Large historical suppression lists require policy decisions, data cleanup, careful importing, and reconciliation—not just CSV upload.
• Template syntax differences can expose undocumented assumptions about missing fields, escaping, helpers, or conditional content.
• Provider analytics differences may change how your team interprets accepted, delivered, bounced, opened, and clicked events.
• Inbound mail and reply workflows may need separate architecture if they relied on Mandrill inbound domains or routes.
• Dedicated infrastructure assumptions should be validated before moving high-volume or reputation-sensitive traffic.
• Operational muscle memory changes: alerting, log searches, support troubleshooting, and incident response procedures must be updated.

Being clear about these tradeoffs is not a reason to delay forever. It is how you budget time realistically and avoid turning an email migration into an inbox-placement incident.

Conclusion: treat the move as email infrastructure work

A successful Mandrill to Volanea migration preserves more than the ability to send a message. It protects your domain authentication, avoids mailing suppressed recipients, keeps critical webhooks reliable, preserves application correlation data, and proves that important emails arrive as expected.

Start with an inventory, introduce a provider adapter where it reduces risk, verify DNS independently, move suppressions with an auditable process, test templates with realistic data, and cut over message types gradually. Keep Mandrill available only long enough to support a defined rollback period, then retire old credentials and DNS records through a deliberate change process.

FAQ

Can I keep my existing From address when moving from Mandrill to Volanea?

Usually, yes, if you verify the relevant sending domain in Volanea and publish the DNS records it requires. Do not assume existing Mandrill authentication records authorize Volanea; validate SPF, DKIM, and DMARC alignment with real received test messages.

Is SMTP or REST API better for a Mandrill to Volanea migration?

SMTP can be a fast path when your application already uses a standard mail library or when you want to avoid tying business logic to a new SDK. Use the REST API when you need provider-supported features such as structured metadata, tags, templates, or event correlation that cannot safely be represented by generic SMTP headers alone.

Should I import every Mandrill rejection-list entry?

Not automatically. Preserve the original export, then classify records by reason and policy. Hard bounces, spam complaints, and explicit do-not-contact requests generally deserve conservative handling; temporary or expired failures may require a separate decision.

Can Mandrill templates move directly to Volanea?

Sometimes the HTML can move, but template logic should be tested rather than assumed compatible. Compare merge syntax, escaping, conditional rules, default values, localization, and per-recipient data. For critical mail, application-side rendering is often the most portable approach.

How long should I keep Mandrill enabled after cutover?

Keep it only for a defined rollback and reconciliation window. During that period, monitor Volanea sends, authentication, webhook processing, suppression behavior, and customer reports. Once the new path is stable, revoke unused Mandrill credentials and remove records only after confirming they are no longer needed.