# Migrate from a CPaaS email stack

Source: https://developer.nylas.com/docs/cookbook/use-cases/build/migrate-from-cpaas/

Communications platforms like Twilio SendGrid and Amazon SES are built to push messages out. They sign your mail, hand it to recipient servers, and report delivery. That covers transactional blasts well, but the moment your product needs to read replies, sync threads, or schedule a meeting off the back of an email, a send-only stack runs out of road. You end up bolting an IMAP poller and a separate calendar integration onto a tool that was never meant to do either.

This guide covers why teams make the move, how send-only concepts map to a unified email and calendar API, the steps to migrate without breaking your existing sends, and the gotchas worth planning for before you cut over.

## Why move from a send-only CPaaS to a unified API?

Send-only platforms handle outbound mail, but they don't read inboxes, sync threads, or touch calendars. A unified API gives you 1 integration that sends, reads, and schedules across 6 providers, so reply handling and meeting booking stop being separate projects you wire up by hand.

The split shows up fast. SendGrid and SES both deliver mail and expose webhooks for bounces and opens, which is most of what transactional sending needs. But neither reads a user's inbox, so two-way features (a support thread, a reply-to-book flow, an assistant that drafts responses) mean adding IMAP polling, OAuth token plumbing, and per-provider quirks on the side. Calendar is a separate vendor again. A unified API folds outbound send, inbound sync, and calendar into 1 surface, so a single grant covers reading and writing a user's mailbox and events. You trade some of the raw bulk-throughput tuning of a dedicated CPaaS for a far smaller surface to build and maintain across email and calendar together.

## How do CPaaS concepts map to a unified email API?

Most send-only concepts have a direct equivalent. A verified sending domain maps to a verified domain on the transactional route. A connected user mailbox is the new piece: it unlocks two-way email and calendar, which has no equivalent in a pure send-only stack. The table below covers the common pairings across both routes.

The mapping isn't 1-to-1 everywhere, and that's the point of the migration. Your existing transactional sends move over with minimal change, while the inbound and calendar features are genuinely new capability rather than a renamed version of something you already had. Roughly 90% of a typical SES or SendGrid integration is outbound, so most of your code maps cleanly and the new work is additive.

| CPaaS concept (SendGrid / SES) | Unified API equivalent | Notes |
|---|---|---|
| Verified sending domain | Verified domain on the transactional route | Same DNS verification model |
| API key auth | API key auth | Bearer token on every request |
| Send a transactional message | `POST /v3/domains/{domain_name}/messages/send` | No user account involved |
| Send as a real user (limited) | `POST /v3/grants/{grant_id}/messages/send` | Sends from the user's own mailbox |
| Event webhooks (bounce, delivered) | `message.transactional.bounced`, `.delivered`, `.complaint`, `.rejected` | Bounced, complaint, delivered, rejected |
| Read inbound mail | Message list and read on a grant | New two-way capability |
| Calendar (separate vendor) | Calendar and events on the same grant | One integration, one auth |

## What are the steps to migrate from a CPaaS?

Migrate in 4 stages: verify your domain, move transactional sends to the domain route, add user grants for two-way features, then layer in calendar. Run old and new paths side by side and shift traffic gradually so no production mail depends on an untested route.

Start by verifying your sending domain so outbound mail keeps its sender reputation. Then point your existing transactional sends at `POST /v3/domains/{domain_name}/messages/send`, which mirrors a classic send-only call: no user account, just your API key and a verified domain. See [transactional send from a domain](/docs/cookbook/email/transactional-send/) for the request shape and domain setup. Keep your old provider live during this phase and route a small slice of traffic (say 5%) through the new path while you watch the delivery webhooks.

Once transactional mail is stable, add the parts a send-only stack never had. Connect user accounts to create grants, then send from a real mailbox with `POST /v3/grants/{grant_id}/messages/send`, which the [send email without SMTP](/docs/cookbook/use-cases/build/send-email-without-smtp/) guide walks through. From the same grant you read inbound mail and access calendar events, so reply handling and scheduling come online without a second vendor.

## What gotchas should I plan for before cutting over?

Plan for 3 differences: per-user send limits on grant sends, the DNS propagation wait on domain verification, and the conceptual shift from fire-and-forget sending to managing live user mailboxes. None block migration, but each changes how you size and sequence the work.

Domain verification depends on DNS, so build in up to 48 hours of propagation time before you expect domain sends to work. Don't schedule the cutover for the same day you add the records. Grant sends behave differently from a CPaaS firehose: because mail goes through the user's real mailbox, every send counts against that provider's per-user ceiling. Gmail consumer accounts sit near 500 recipients per day, so grant sends suit per-user mail, not bulk campaigns. Keep bulk transactional volume on the domain route, which has no per-user cap.

The bigger shift is conceptual. A send-only stack is stateless: you hand off a message and forget it. A grant is a living connection to someone's mailbox, so you handle token lifecycle (the API refreshes tokens for you) and account disconnects. That's the cost of two-way features, and it's worth weighing honestly. If your product only ever sends and never reads or schedules, a dedicated CPaaS may still fit; the unified API earns its place once inbound or calendar enters the picture. New to the platform? Start with the [getting started guide](/docs/v3/getting-started/) to set up your first project.

## What's next

- [Send transactional email from a domain](/docs/cookbook/email/transactional-send/) for the send-only equivalent path
- [Send email without SMTP](/docs/cookbook/use-cases/build/send-email-without-smtp/) for grant sends through a real mailbox
- [Getting started with Nylas](/docs/v3/getting-started/) to create a project and API key