Skip to main content
Move an app that sends transactional email with a SendGrid SDK or SMTP to Nuntly, in TypeScript or Java. The four steps follow a real migration and keep a way back until the end.

Prerequisites

  • A Nuntly account. See account setup.
  • Access to the DNS records of the domain you send from.
SendGrid facts on this page come from Twilio SendGrid’s own documentation and SDKs, read on November 16, 2026. The code samples compile with @nuntly/sdk 2.0.0, @sendgrid/mail 8.1.6, @sendgrid/eventwebhook 8.0.0 and nodemailer 10.6.0 under TypeScript strict, and with com.nuntly:nuntly-java 2.0.0 and com.sendgrid:sendgrid-java 4.10.3 on Java 21.
An AI coding agent can make the code changes of step 2 for you, then list the calls it could not map. See Use Nuntly from an AI agent. The other steps stay with you.

Step 1: Set up Nuntly

Verify your sending domain

Add the domain you send from today. You do not need to remove anything from SendGrid first.
  1. In the Nuntly dashboard, go to Domains and click Add Domain.
  2. Add the DKIM, SPF and MX records Nuntly shows to your DNS provider. DMARC is recommended but never blocks verification. You can import all records at once with the zone file. See sending domains.
  3. The domain shows as verified once your DNS provider publishes the records, which takes from a few minutes to a few hours.
Keep SendGrid’s records in place. Nuntly’s DKIM, SPF and MX records use names of their own, so both sets work on the same domain without conflict. If you publish a DMARC record already, keep it: one _dmarc record covers both providers. If you track opens or clicks with SendGrid, turn on open and click tracking on the Nuntly domain once it is verified. Nuntly sets tracking per domain, for every email sent from it. See open and click tracking.

Create an API key

  1. In the dashboard, go to API Keys and click Create API Key.
  2. Pick Sending only for an app that only sends, and limit it to the domain above. Pick Full access only for code that also reads emails or manages domains, webhooks or keys.
  3. Copy the key. It starts with ntly_ and is shown once.
Store it next to your SendGrid key, under a new name:
.env
Keeping both keys during the migration lets you switch providers with a flag in step 4. See API keys for permissions and domain restrictions.

Step 2: Swap the SDK

Move over SMTP first

To move traffic before you touch the send code, point your SMTP settings at Nuntly first, then swap in the SDK once delivery looks right. Change the host to smtp.nuntly.com, the port to 587 with STARTTLS, the username to nuntly and the password to your Nuntly API key. With nodemailer, only the transport changes:
See SMTP for the supported ports and the common connection errors.

Swap the send call

Install the Nuntly SDK next to the SendGrid one. Remove the SendGrid SDK only after the cut-over.
The same order-shipped email, before and after. Categories and custom args both become tags, whose names and values accept letters, digits, _ and -:
Store the returned email ID with your order if you track email status: it is the data.id of every webhook event for that email. Two behaviors to know:
  • Idempotency is on by default. Without an idempotency key, the Nuntly SDKs generate one for each send and reuse it across their own retries, so an automatic retry cannot send twice. Pass your own key to deduplicate across calls. See idempotency keys.
  • Errors are typed. The client throws an APIError (TypeScript) or an ApiError subclass (Java) with the status and an error code. A network failure throws a connection error, which the TypeScript sample rethrows. See errors.

Personalizations

A SendGrid request with several personalizations becomes a bulk request with one email per recipient. Shared values move to fallback, and the HTML is rendered in your code:
Send more than 20 recipients in several calls. Escape any value you insert into HTML.

Step 3: Move your webhooks

In the Nuntly dashboard, go to Webhooks, click Create Webhook, enter your endpoint URL and select the events you handle. Each event and its payload are described in sending events. Copy the signing secret into NUNTLY_WEBHOOK_SECRET: it is shown once. See set up webhooks. The handler, before and after. Both read the raw body, so in Express register the route before any JSON body parser:
The Nuntly verification rejects a request whose signature does not match or whose timestamp is more than 5 minutes old. It returns a typed event: TypeScript narrows event.data in each case, and Java matches one record per event type. When your endpoint fails, Nuntly retries with exponential backoff, and you can replay a delivery from the webhooks observability view. Run both handlers during the migration: SendGrid keeps sending events for the emails it delivered, and Nuntly sends events for its own.

Carry over your suppressions

Before your first Nuntly send, export your SendGrid bounces, blocks, spam reports, invalid emails and unsubscribes, keep them in your app, and skip those addresses before you call the send. From then on, Nuntly adds permanent bounces and spam complaints to its own suppression list, and an email to a suppressed address triggers email.rejected.

Step 4: Test and cut over

Send a test

Send to an inbox you own, from the verified domain, with the new key:
  1. Send one email with the code from step 2.
  2. In the dashboard, open Emails, select the email by its ID, and open Email Timeline to see its events.
  3. Check that your webhook endpoint receives email.delivered, and that the signature check passes.
  4. Open the email in the inbox and check the headers: DKIM should pass for your domain.
Then run your existing test suite against the Nuntly client to catch any field you forgot to map.

Cut over

Switch providers with a configuration flag, and keep the SendGrid code until the cut-over is done:
  1. Read the provider from configuration, for example EMAIL_PROVIDER=nuntly, and keep both clients in the code.
  2. Move one message type at a time. Start with low-risk email such as notifications, watch bounces and complaints in the observability dashboard, then move password resets and receipts.
  3. Keep SendGrid’s DNS records, API key and Event Webhook active until no traffic has gone through SendGrid for a few days. Sends already scheduled on SendGrid still go out from SendGrid: cancel them there and schedule them again on Nuntly, or let them run out.
When you are done, remove the SendGrid DNS records, delete the SendGrid API key and Event Webhook, and remove the SendGrid SDK from your dependencies.

Next steps

Send email from Express

A full Express app with sending, webhooks and error handling

Send email from Spring Boot

The Spring Boot starter, sending and a verified webhook controller

Idempotency keys

Key formats, strategies and error codes

Migrate from Resend

The same steps for a Resend integration