# Groundmail

> Groundmail is a transactional email API that runs on mail servers and IPs we own and operate. Send with a REST API, an official SDK (Node, Python, Go, PHP, Ruby), SMTP or MCP; Dedicated plans add your own mail servers and IPs.

## Key facts
- Infrastructure: we own and run the sending infrastructure (mail servers, IPs, warmup, reputation). Free, Pro and Scale send over our shared transactional network, which carries no marketing or cold email. Dedicated gives you dedicated IPs on your own dedicated mail servers, which we provision, warm and manage.
- Plans: Free ($0: 3,000 emails/month, 100/day, 3 domains) · Pay as you go ($15/month with 20,000 emails included, then $0.70 per 1,000 up to 100,000, $0.50 up to 1M, $0.30 above; sent and received count the same; every feature included) · Dedicated (from $299/month, your own servers and IPs, scoped on a demo). Overage on paid plans is billed per 1,000 emails. Every tier as JSON: https://docs.groundmail.dev/pricing.json
- Every tier (emails a month): Free $0/month for 3,000 · Pay as you go: $15/month with 20,000 included, then $0.70 per 1,000 up to 100,000, $0.50 up to 1M, $0.30 above · Dedicated from $299/month for 250,000.
- Log retention (email content, events and inbound emails; aggregate stats are kept): Free 7 days · Pay as you go 90 days · Dedicated up to 1 year. Store webhook events to keep history longer. Details: https://docs.groundmail.dev/emails#data-retention
- New accounts ramp up: paid accounts start at 1,000 product and 3,000 transactional recipients a day, doubling each day they use at least half of it with bounces under 2% and complaints under 0.1%, until the plan's monthly volume. A 429 `daily_ramp_limit` means wait until `details.resets_at` (next 00:00 UTC); upgrading does not lift it. Details: https://docs.groundmail.dev/sending-limits#new-account-ramp-up
- Card required to send: sending to anyone other than your own account email needs a verified domain and a payment method on file, on every plan. The Free plan is never charged. Pricing: https://groundmail.dev/pricing/
- Test before DNS: send from noreply@mail.groundmail.dev to your own account email only (no card, no domain). Any other recipient gets a 403.
- Test without delivering: simulator addresses (delivered@, bounce@, block@, complaint@, suppressed@, delayed@simulator.groundmail.dev; bounce+tag@ works) give that outcome and its webhooks with any key, and test keys (`gm_test_…`) run every check but deliver nothing. Both are marked `test: true` and count toward nothing. Details: https://docs.groundmail.dev/testing
- Tenants (for platforms that send for their own customers): one tenant per customer, each with its own domains, suppression list, stats, sending ramp and pause switch. Send with `tenant`; API keys and webhook endpoints can be limited to tenants. Included on Scale (up to 1,000 tenants) and Dedicated (up to 10,000), with no per-tenant fee; other plans get 403 `tenants_not_enabled`. A tenant can have its own dedicated IP at $25/IP/month. Details: https://docs.groundmail.dev/tenants
- API: https://api.groundmail.dev, auth `Authorization: Bearer gm_…`. Keys are created in the dashboard at https://app.groundmail.dev.
- SDKs: Node.js `npm install groundmail` · Python `pip install groundmail` · Go `go get github.com/Groundmail/groundmail-sdks/go` · PHP `composer require groundmail/groundmail` · Laravel `composer require groundmail/laravel` · Symfony Mailer `composer require groundmail/symfony-mailer` · Ruby `gem install groundmail`
- SMTP relay: smtp.groundmail.dev:587 (STARTTLS), username `groundmail`, password is an SMTP credential (`gmsmtp_…`)
- MCP: hosted at https://mcp.groundmail.dev/mcp (OAuth), or `npx -y groundmail-mcp` with an API key
- OpenAPI: https://docs.groundmail.dev/openapi.yaml
- Errors: every error has a stable `code`, a `message`, a `hint` and a `docs_url` (https://docs.groundmail.dev/errors)
- Retries: send `Idempotency-Key` on POST /emails and reuse it on retries (kept 24 hours).

## Product
- Home: https://groundmail.dev/
- Pricing: https://groundmail.dev/pricing/
- Features: https://groundmail.dev/features/
- MCP server and AI agents: https://groundmail.dev/features/mcp/
- SMTP relay: https://groundmail.dev/features/smtp/
- Inbound email: https://groundmail.dev/features/inbound/
- Email testing: https://groundmail.dev/email-testing/
- Templates: https://groundmail.dev/features/templates/
- Automations: https://groundmail.dev/features/automations/
- Deliverability: https://groundmail.dev/features/deliverability/
- Tenants for platforms: https://groundmail.dev/features/tenants/
- For developers: https://groundmail.dev/features/developers/
- Integrations: https://groundmail.dev/features/integrations/
- Integrations hub: https://groundmail.dev/integrations/

## API
- Base URL: https://api.groundmail.dev
- Auth: Authorization: Bearer gm_…
- Dashboard: https://app.groundmail.dev
- OpenAPI: https://docs.groundmail.dev/openapi.yaml
- Plans, prices and limits (JSON): https://docs.groundmail.dev/pricing.json
- Errors and recovery hints: https://docs.groundmail.dev/errors
- Test sends and idempotency: https://docs.groundmail.dev/ai/safe-defaults
- Sandbox sender (to your own account email only): noreply@mail.groundmail.dev
- SMTP relay: smtp.groundmail.dev:587
- Hosted MCP: https://mcp.groundmail.dev/mcp

## Packages
- Node SDK (npm): groundmail
- Go module: github.com/Groundmail/groundmail-sdks/go
- Python: `pip install groundmail`
- PHP: `composer require groundmail/groundmail`
- Laravel: `composer require groundmail/laravel`
- Symfony Mailer: `composer require groundmail/symfony-mailer`
- Ruby: `gem install groundmail`
- CLI (npm): groundmail-cli
- MCP server (npm): groundmail-mcp

## Start
- Introduction: https://docs.groundmail.dev
- Quickstart: https://docs.groundmail.dev/quickstart
- Set up with an AI agent: https://docs.groundmail.dev/ai/one-prompt-setup
- Authentication: Authentication: https://docs.groundmail.dev/authentication
- Authentication: Azure managed identity: https://docs.groundmail.dev/authentication/azure-managed-identity
- Testing: Testing: https://docs.groundmail.dev/testing
- Testing: Email testing: https://docs.groundmail.dev/email-testing
- Migrate: Import from another provider: https://docs.groundmail.dev/migrations
- Migrate: From Resend: https://docs.groundmail.dev/migration
- Migrate: From SendGrid: https://docs.groundmail.dev/migration/sendgrid
- Migrate: From Postmark: https://docs.groundmail.dev/migration/postmark
- Migrate: From Amazon SES: https://docs.groundmail.dev/migration/ses
- Migrate: From Mailgun: https://docs.groundmail.dev/migration/mailgun
- Migrate: From Azure Communication Services: https://docs.groundmail.dev/migration/azure-communication-services

## Sending
- Send email: https://docs.groundmail.dev/emails
- SMTP: SMTP relay: https://docs.groundmail.dev/smtp
- SMTP: Tools with SMTP settings: https://docs.groundmail.dev/smtp/tools
- Templates: Templates: https://docs.groundmail.dev/templates
- Templates: Free email templates: https://docs.groundmail.dev/guides/email-templates
- Templates: React Email: https://docs.groundmail.dev/guides/react-email
- Content scanning: https://docs.groundmail.dev/content-scanning
- Send for your customers: Tenants: https://docs.groundmail.dev/tenants
- Send for your customers: Send for your customers: https://docs.groundmail.dev/guides/platforms
- Auth email: Password reset emails: https://docs.groundmail.dev/guides/password-reset-emails
- Auth email: Supabase Auth: https://docs.groundmail.dev/guides/supabase
- Auth email: Better Auth: https://docs.groundmail.dev/guides/better-auth
- Auth email: Auth.js / NextAuth: https://docs.groundmail.dev/guides/authjs
- Auth email: Clerk: https://docs.groundmail.dev/guides/clerk
- Auth email: Payload CMS: https://docs.groundmail.dev/guides/payload

## Receiving
- Inbound email: https://docs.groundmail.dev/inbound
- Test inbox API: https://docs.groundmail.dev/test-inbox

## Events
- Webhooks: https://docs.groundmail.dev/webhooks
- Events: https://docs.groundmail.dev/events
- Automations: https://docs.groundmail.dev/automations
- Integrations: https://docs.groundmail.dev/integrations

## Deliverability
- Domains and DNS: https://docs.groundmail.dev/domains
- Deliverability insights: https://docs.groundmail.dev/deliverability
- DMARC monitoring: https://docs.groundmail.dev/dmarc
- Bounces and suppressions: https://docs.groundmail.dev/suppressions
- Email validation: https://docs.groundmail.dev/validation

## SDKs and frameworks
- SDKs: Node.js: https://docs.groundmail.dev/frameworks/node
- SDKs: Python: https://docs.groundmail.dev/sdks/python
- SDKs: Go: https://docs.groundmail.dev/sdks/go
- SDKs: PHP: https://docs.groundmail.dev/sdks/php
- SDKs: Ruby: https://docs.groundmail.dev/sdks/ruby
- SDKs: CLI: https://docs.groundmail.dev/cli
- Frameworks: Next.js: https://docs.groundmail.dev/frameworks/nextjs
- Frameworks: NestJS: https://docs.groundmail.dev/frameworks/nestjs
- Frameworks: AdonisJS: https://docs.groundmail.dev/frameworks/adonisjs
- Frameworks: Strapi: https://docs.groundmail.dev/frameworks/strapi
- Frameworks: Medusa: https://docs.groundmail.dev/frameworks/medusa
- Frameworks: Convex: https://docs.groundmail.dev/frameworks/convex
- Frameworks: Rails: https://docs.groundmail.dev/frameworks/rails
- Frameworks: Laravel: https://docs.groundmail.dev/frameworks/laravel
- Frameworks: Symfony Mailer: https://docs.groundmail.dev/frameworks/symfony
- Frameworks: C# / .NET: https://docs.groundmail.dev/frameworks/dotnet
- Frameworks: Java / Spring Boot: https://docs.groundmail.dev/frameworks/java
- Background jobs: Trigger.dev: https://docs.groundmail.dev/integrations/trigger-dev
- Background jobs: Inngest: https://docs.groundmail.dev/integrations/inngest
- Background jobs: Upstash QStash: https://docs.groundmail.dev/integrations/qstash
- No-code: n8n: https://docs.groundmail.dev/guides/n8n
- No-code: Activepieces: https://docs.groundmail.dev/integrations/activepieces
- No-code: Zapier: https://docs.groundmail.dev/integrations/zapier
- No-code: Apprise: https://docs.groundmail.dev/integrations/apprise
- No-code: HTTP step (Make, Pabbly, Pipedream): https://docs.groundmail.dev/integrations/http
- No-code: WordPress and WooCommerce: https://docs.groundmail.dev/integrations/wordpress
- No-code: Google Sheets: https://docs.groundmail.dev/integrations/google-sheets
- No-code: MailCheap: https://docs.groundmail.dev/integrations/mailcheap
- Platforms: Firebase: https://docs.groundmail.dev/integrations/firebase
- Platforms: Railway: https://docs.groundmail.dev/integrations/railway
- Platforms: Netlify: https://docs.groundmail.dev/integrations/netlify
- Platforms: Laravel Cloud: https://docs.groundmail.dev/integrations/laravel-cloud
- Platforms: Coolify: https://docs.groundmail.dev/integrations/coolify
- Platforms: Appwrite: https://docs.groundmail.dev/integrations/appwrite
- Platforms: Auth0: https://docs.groundmail.dev/integrations/auth0
- Platforms: Kinde: https://docs.groundmail.dev/integrations/kinde
- Platforms: DigitalOcean: https://docs.groundmail.dev/integrations/digitalocean
- Platforms: DNSimple: https://docs.groundmail.dev/integrations/dnsimple

## AI and agents
- MCP server: https://docs.groundmail.dev/ai/mcp
- MCP clients: GitHub Copilot (VS Code): https://docs.groundmail.dev/ai/mcp-github-copilot
- MCP clients: Zed: https://docs.groundmail.dev/ai/mcp-zed
- MCP clients: Warp: https://docs.groundmail.dev/ai/mcp-warp
- MCP clients: Google Antigravity: https://docs.groundmail.dev/ai/mcp-antigravity
- Agent Skills: Agent Skills: https://docs.groundmail.dev/ai/agent-skills
- Agent Skills: Agent skill notes: https://docs.groundmail.dev/ai/agent-skill
- Agent Skills: Cursor rules: https://docs.groundmail.dev/ai/cursor-rules
- Test sends and idempotency: https://docs.groundmail.dev/ai/safe-defaults
- For LLMs: llms-full.txt: https://docs.groundmail.dev/llms-full.txt
- For LLMs: pricing.json: https://docs.groundmail.dev/pricing.json
- AI app builders: Overview: https://docs.groundmail.dev/builders
- AI app builders: Lovable: https://docs.groundmail.dev/builders/lovable
- AI app builders: Replit: https://docs.groundmail.dev/builders/replit
- Cursor rule file: https://docs.groundmail.dev/ai/groundmail.mdc
- Agent skill (markdown): https://docs.groundmail.dev/ai/markdown/agent-skill
- Any docs page as markdown: add .md to its URL (https://docs.groundmail.dev/quickstart.md)
- Agent Skills index (JSON): https://docs.groundmail.dev/.well-known/agent-skills/index.json

## Reference
- API explorer: https://docs.groundmail.dev/api-explorer
- OpenAPI: https://docs.groundmail.dev/openapi.yaml
- API keys: https://docs.groundmail.dev/api-keys
- Errors: https://docs.groundmail.dev/errors
- Sending limits: https://docs.groundmail.dev/sending-limits

## Help
- Troubleshooting: https://docs.groundmail.dev/troubleshooting
- Support: https://groundmail.dev/support/
- System status: https://status.groundmail.dev
- Changelog: https://groundmail.dev/changelog/

## Core endpoints
- POST /emails (send; supports Idempotency-Key)
- POST /emails/batch
- GET /emails
- GET /emails/{id}
- POST /emails/test (simulated webhook event, no email sent)
- POST /domains
- GET /domains/{id}
- POST /domains/{id} action=apply|verify
- POST /webhooks
- POST /templates
- POST /events (supports Idempotency-Key)
- GET /deliverability

## Learn
- Learn hub: https://groundmail.dev/learn/
- Compare: https://groundmail.dev/compare/
- vs Resend: https://groundmail.dev/compare/resend/
- vs Postmark: https://groundmail.dev/compare/postmark/
- vs SendGrid: https://groundmail.dev/compare/sendgrid/
- vs Amazon SES: https://groundmail.dev/compare/amazon-ses/
- vs Mailgun: https://groundmail.dev/compare/mailgun/
- Migrate: https://groundmail.dev/migrate/
- Migrate from SendGrid: https://groundmail.dev/migrate/sendgrid/
- Migrate from Amazon SES: https://groundmail.dev/migrate/amazon-ses/
- Guides: https://groundmail.dev/guides/
- Blog: https://groundmail.dev/blog/
- Blog RSS feed: https://groundmail.dev/blog/feed.xml