Migrating to TagMail:
A Practical Handbook

Comparable terminology

Most transactional email platforms describe the same underlying concepts with different names. Before touching any code, it helps to know which TagMail term maps to the concept you already know from your current provider.

The mapping is rarely one-to-one in every detail — most platforms group a couple of these concepts differently — but this table covers the terms you'll run into most often while porting code and documentation references.

Quick start

The fastest path to a working send, before you migrate anything else over:

1. Add and verify a sending domain. Add the DNS records TagMail provides for SPF and DKIM. Verification typically completes once DNS propagates.
2. Generate an API key. Create a key scoped to the domain you just verified, and store it in your environment configuration — never in source code.
3. Send a test message. Use either the HTTP API or SMTP relay to send a single test email to an address you control, and confirm it lands and authenticates correctly.
4. Check the delivery log. Confirm the message shows as delivered, and that SPF/DKIM/DMARC all pass in the received headers.
5. Point one real code path at TagMail. Start with something low-risk — a password reset or a receipt — before moving your highest-volume mail over.

SMTP migration vs. API migration

There are two ways to connect to TagMail, and the right one depends on how your current sending is built.

SMTP relay

If your application currently sends mail through a standard mail library (most languages have one built in or widely used), SMTP migration is usually the smallest change. You update the SMTP host, port, and credentials to point at TagMail, and the rest of your sending code stays exactly as it is.

• Pros: minimal code changes; works with almost anything that already sends mail; fast to test.
• Cons: less control over advanced features like templating and structured event data; typically slightly higher latency than the API at very high volume.

HTTP API

If you're rebuilding your sending logic anyway, or you need features like server-side templating, batch sending, or detailed structured delivery events, migrating to the API directly is worth the extra integration work up front.

• Pros: full feature access, better performance at scale, structured responses that are easier to handle in code than parsing SMTP replies.
• Cons: requires actual code changes rather than a configuration swap.

A common pattern: migrate via SMTP first to get sending working quickly and confirm deliverability holds up, then move to the API over time for the sending paths that would benefit most from templating or webhook events.

Migration checklist

A reference list of what typically needs to move, roughly in the order it matters:

1. Sending domain(s) — added and verified, with SPF/DKIM/DMARC in place
2. API keys or SMTP credentials — generated and stored securely
3. Suppression list — exported from your previous provider and imported, so you don't re-mail bounced or unsubscribed addresses
4. Templates — recreated or ported, with a visual check across a few clients
5. Webhook endpoints — pointed at TagMail's event payloads, with field names updated per the terminology mapping above
6. Inbound routing rules — recreated if you rely on parsing incoming mail
7. Monitoring and alerting — updated to watch TagMail's delivery and bounce data instead of (or alongside) your previous provider's, during the transition window

Keep your old provider active in parallel until the new setup has run cleanly for at least a full billing cycle. Cutting over everything at once removes your fallback exactly when you're most likely to need it.

Setting up account security

A migration is a natural point to tighten security rather than just replicate however the old account was configured.

• Scope API keys narrowly. Use separate keys per domain or per environment (production vs. staging) instead of one key with access to everything.
• Rotate credentials on migration. Don't reuse old provider credentials anywhere — generate fresh TagMail keys, and set a reminder to rotate them periodically going forward.
• Enable two-factor authentication on the account that manages billing and domain configuration, since that account can add sending domains and change where your mail's reputation lives.
• Restrict who has account-level access. Give most team members API keys scoped to what they need; reserve full account access for a small number of people.
• Set up webhook signature verification so your endpoint rejects anything that isn't actually signed by TagMail, rather than trusting payloads based on URL secrecy alone.

Getting set up for good reputation from day one

Migrating providers effectively creates a new sending identity, even if your content and recipient list are unchanged — a fresh domain or IP has no sending history with mailbox providers yet. Set the account up correctly at the start rather than fixing reputation problems after they show up.

• Warm up gradually if you're on a dedicated IP. Start at a fraction of your eventual volume and increase over one to two weeks rather than sending full volume on day one.
• Migrate your cleanest traffic first. Move transactional mail (which typically has the best engagement) before bulk or marketing sends, so your new domain builds a positive history early.
• Validate your list before the first real send. Old lists accumulate bounced and disposable addresses over time — clean the list as part of migration, not after a bounce spike shows up on the new setup.
• Carry your suppression list over. Anyone who bounced, unsubscribed, or complained on your old provider should be suppressed on TagMail too — that history doesn't transfer automatically unless you import it.
• Watch inbox placement closely for the first few weeks. This is the period where problems are cheapest to catch and fix.

For a deeper look at maintaining reputation on an ongoing basis — not just during migration — see the deliverability guide.