Short answer
To move a Laravel app from SendGrid, install composer require groundmail/laravel, set MAIL_MAILER=groundmail with a groundmail mailer in config/mail.php (your Mailables, notifications and queued mail stay as they are), and add GROUNDMAIL_API_KEY. Then verify your sending domain in Groundmail, leaving SendGrid's DNS records in place until you cut over.
SendGrid's webhook events map onto Groundmail's email.* events, signed with HMAC-SHA256 in a Groundmail-Signature header. The free email migration scanner finds every place your repo sends through SendGrid and writes the pull request for your coding agent.
On this page
Before and after: the Laravel mail config
Laravel sends through SendGrid with a mail driver, so the move is a config change: the Groundmail package replaces the driver, and the code that builds and sends your email stays as it is.
Install the package
composer require groundmail/laravelBefore: SendGrid (Laravel)
# .env: SendGrid through Laravel's SMTP mailer
MAIL_MAILER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=SG.…
MAIL_FROM_ADDRESS=no-reply@acme.comAfter: Groundmail (Laravel)
# .env
MAIL_MAILER=groundmail
GROUNDMAIL_API_KEY=gm_…
MAIL_FROM_ADDRESS=no-reply@acme.com
// config/mail.php, under 'mailers'
'groundmail' => [
'transport' => 'groundmail',
],
// Your Mailables, notifications and queued mail don't change:
Mail::to($user)->send(new ResetPasswordMail($user));If you also call SendGrid's API directly
The Groundmail Laravel package maps from, to, cc, bcc, reply-to, subject, HTML, text and attachments for you. If some code also calls SendGrid's API directly, for example to send a stored template, its fields map like this.
| SendGrid | Groundmail |
|---|---|
personalizations[].to[] (or to in the helper) | to: a string or an array |
from: { email, name } | from: "you@example.com" or { email, name } |
content[] with type and value (or html / text) | html and text |
templateId + dynamicTemplateData | template: { id: "<alias>", variables: { … } } |
replyTo | reply_to |
categories, customArgs | tags: up to 10 { name, value } pairs, returned on every webhook |
attachments[] (content, filename, type) | attachments[]: content and filename as they are, type becomes contentType |
Using SendGrid templates? Send them by alias with template: { id: "<alias>", variables: { … } }. The importer converts your SendGrid templates and publishes them under an alias. More field detail: SendGrid migration docs and Laravel docs.
Environment variables
| Today | On Groundmail |
|---|---|
MAIL_MAILER=smtp | MAIL_MAILER=groundmail |
MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD | Remove after cutover, unless another mailer uses them |
| (new) | GROUNDMAIL_API_KEY (a gm_… key) |
Your webhook secret, e.g. SENDGRID_WEBHOOK_PUBLIC_KEY | GROUNDMAIL_WEBHOOK_SECRET: the signing secret shown once when you create the webhook |
Create the key under API keys in the dashboard: the Send only preset is enough for the app. Leave the SendGrid variables set until you cut over, so rolling back is a config change.
DNS: add Groundmail's records, keep SendGrid's until cutover
Add the domain you send from in the dashboard, or with POST /domains. Groundmail gives you these records; on Cloudflare, GoDaddy and Vercel one click writes them for you.
| Record | Type | Host | Value |
|---|---|---|---|
| Ownership | TXT | _groundmail.example.com | Token from the dashboard |
| DKIM | TXT | <selector>._domainkey.example.com | Public key from the dashboard |
| Return path | CNAME | rp.example.com | rp.groundmail.dev (DNS only, not proxied) |
| SPF | TXT | example.com | Add include:spf.groundmail.dev to your existing SPF record |
| DMARC | TXT | _dmarc.example.com | Keep yours; the dashboard suggests one if you have none |
Ownership, DKIM, the return path and SPF must resolve before the domain verifies.
SendGrid records to remove after cutover
- The
s1._domainkeyands2._domainkeyDKIM CNAMEs - The
em…return-path CNAME, for exampleem1234.example.com - Take
include:sendgrid.netout of your SPF record.
Wait a few days after the last email goes out through the old provider, in case you need to roll back. Background on each record: SPF, DKIM and DMARC for transactional email.
Webhooks: what changes
| SendGrid | Groundmail | |
|---|---|---|
| Delivery | A JSON array of events, batched, per POST | One JSON object per POST: type, created_at and data |
| Checking it came from them | Optional Signed Event Webhook: ECDSA signature in X-Twilio-Email-Event-Webhook-Signature, checked with a public key | Groundmail-Signature: t=…,v1=…: HMAC-SHA256 of t.rawBody with the endpoint's secret |
If your endpoint doesn't return a 2xx, Groundmail retries the delivery 4 more times: after 5 seconds, 30 seconds, 2 minutes and 2 minutes. Subscribe an endpoint to these events to replace the ones you handle today:
| SendGrid event | Groundmail event |
|---|---|
processed | email.sent |
delivered | email.delivered |
deferred | email.delivery_delayed |
bounce | email.bounced and email.failed (data.bounce_type is hard or block) |
dropped | email.suppressed |
spamreport | email.complained |
open | email.opened |
click | email.clicked |
unsubscribe, group_unsubscribe | contact.unsubscribed |
Check the signature against the raw request body, before you parse it. In Laravel:
Verify a Groundmail webhook (Laravel controller)
use Illuminate\Http\Request;
class GroundmailWebhookController
{
public function __invoke(Request $request)
{
$ok = $this->verifyGroundmailSignature(
$request->getContent(),
(string) $request->header('Groundmail-Signature'),
config('services.groundmail.webhook_secret'), // env('GROUNDMAIL_WEBHOOK_SECRET')
);
abort_unless($ok, 401);
$event = $request->json()->all(); // ['type' => 'email.delivered', 'data' => [...]]
return response()->noContent();
}
private function verifyGroundmailSignature(string $rawBody, string $header, string $secret): bool
{
$parts = [];
foreach (explode(',', $header) as $part) {
[$key, $value] = array_pad(explode('=', $part, 2), 2, '');
$parts[$key] = $value;
}
$t = $parts['t'] ?? '';
$v1 = $parts['v1'] ?? '';
if (!ctype_digit($t) || $v1 === '' || abs(time() - (int) $t) > 300) {
return false;
}
return hash_equals(hash_hmac('sha256', $t . '.' . $rawBody, $secret), $v1);
}
}Use Send test event on the webhooks page, or POST /emails/test from CI, to try your handler before real mail flows. Payloads and every event: webhooks.
SendGrid and Groundmail at 50k, 100k and 1M emails
| Monthly volume | SendGrid | Groundmail |
|---|---|---|
| Free option | 60-day trial, 100 emails/day | 3,000 emails/month (100/day), no time limit |
| 50,000 emails/month | $19.95 (Essentials 50k) | $20 (Pro) |
| 100,000 emails/month | $34.95 (Essentials 100k) | $35 (Pro) |
| 1,000,000 emails/month | $799 (Pro 1.5M) | $650 (Scale) |
USD per month, monthly billing, cheapest published plan that covers each volume. SendGrid prices as of October 2026 from twilio.com/en-us/products/email-api/pricing; Groundmail prices from our pricing page.
Last checked on each vendor's public page.
Up to 100,000 emails a month the two list prices are within five cents, so price isn't the reason to move. At 1 million Groundmail is $650 against $799, the free plan doesn't end after 60 days, and overage rates are published.
Plans, overage and what each includes: SendGrid pricing. Everything else side by side: Groundmail vs SendGrid.
Cut over without losing mail
- 1
Put the provider behind a flag
Keep the SendGrid settings next to Groundmail's and choose between them with an env var, so rolling back is a config change and a restart.
- 2
Send to yourself first
Trigger a password reset and a receipt to your own addresses, and check the headers show DKIM passing for your domain.
- 3
Move a small share
Send 5 to 10% of real mail through Groundmail for a day, and watch bounces and complaints on the dashboard next to what you see today.
- 4
Ramp to 100%
Then switch everything over, and keep SendGrid configured for a week in case you need to switch back.
- 5
Clean up
Remove the SendGrid package, its env vars and its DNS records, and cancel the plan.
Let the migration tool find every send
Then bring your SendGrid setup across with the importer: paste a SendGrid API key under Import and Groundmail copies your suppressions, templates, sending domains (with the DNS changes) and webhooks (created switched off until your handler is ready). Nothing changes in your SendGrid account, and the key is used for the import only. From a terminal:
Import from SendGrid with the CLI
npm install -g groundmail-cli
groundmail login
export SENDGRID_API_KEY=…
groundmail migrate sendgrid --dry-run # preview, nothing written
groundmail migrate sendgrid # importFrequently asked questions
How long does it take to move a Laravel app from SendGrid?
The code change is usually under an hour: one package, one mailer setting and one env var. Domain verification takes as long as your DNS host takes to publish the records, and is one click on Cloudflare, GoDaddy and Vercel. Plan a few days of partial sending before you turn SendGrid off.
Can I keep sending over SMTP instead?
Yes. If your app sends through smtp.sendgrid.net today, point it at smtp.groundmail.dev on port 587 with STARTTLS (or 2525 if your host blocks 587), username groundmail, and an SMTP credential (gmsmtp_…) from the dashboard as the password. Same verified domains, limits and suppressions as the API. See SMTP.
What happens to my SendGrid suppression list?
The importer copies hard bounces, spam complaints and unsubscribes onto your Groundmail suppression list. Bounces that were blocks on SendGrid's servers are left off, because those addresses are fine.
Why do teams move from SendGrid to Groundmail?
A free plan instead of a 60-day trial, published overage rates, lower prices from 500,000 emails a month, and support from the people who run the mail servers.
Sources
Facts on this page about other companies' products, prices and policies come from these public pages. They change, so check them before you decide.