Magic-Mail — Email Providers

TL;DR

Magic-Mail supports 6 providers: Gmail, Microsoft 365, Yahoo (all OAuth 2.0), SMTP (universal), SendGrid, and Mailgun (both API key). OAuth providers are recommended — no passwords stored, easy rotation. Each provider has per-account rate limits and supports attachments (except Mailgun with API limitations).

Provider matrix

Provider	Auth method	Max send rate (default)	Attachments	Best for
Gmail	OAuth 2.0 (Google)	500/day (Free), 2000/day (Workspace)	Yes	Personal, small teams, OAuth required
Microsoft 365	OAuth 2.0 (Azure AD)	10,000/day	Yes	Enterprise, Office 365 tenants
Yahoo Mail	OAuth 2.0 (Yahoo)	500/day	Yes	Legacy Yahoo accounts
SMTP	Username / Password	Depends on server	Yes	Custom servers, legacy systems
SendGrid	API Key	100/sec, 100k/month (Free)	Encoded	Transactional, marketing, analytics
Mailgun	API Key	100/sec	Limited	Bulk sending, high volume

Gmail

OAuth 2.0 via Google Cloud Console. No passwords needed, revoke access anytime.

Setup

1. Create a Google Cloud Project at console.cloud.google.com.
2. APIs & Services → Library → enable the Gmail API.
3. Credentials → Create Credentials → OAuth 2.0 Client ID.
   • Application type: Web application.
   • Authorized redirect URI: https://YOUR-STRAPI-HOST/admin/plugins/magic-mail/oauth/gmail/callback.
4. Copy the Client ID and Client Secret.
5. In Magic-Mail admin → Email Accounts → Add Account → Gmail OAuth.
6. Paste the Client ID and Secret, click Connect to Gmail, authorize.

Limits

• Free Gmail: 500 emails/day, 100 recipients per email.
• Google Workspace: 2,000 emails/day (external), 10,000 (internal).
• Magic-Mail tracks daily/hourly/per-minute usage automatically.

Microsoft 365

OAuth 2.0 via Azure Active Directory.

Setup

1. In the Azure Portal, go to Azure Active Directory → App registrations → New registration.
2. Give it a name, set redirect URI to https://YOUR-STRAPI-HOST/admin/plugins/magic-mail/oauth/microsoft/callback.
3. On the app page, go to API permissions → Add permission → Microsoft Graph → Delegated:
   • Mail.Send
   • Mail.ReadWrite
   • User.Read
   • offline_access
4. Click Grant admin consent (requires tenant admin).
5. Certificates & secrets → New client secret → copy the value.
6. In Magic-Mail admin → Add Account → Microsoft 365 OAuth, paste Client ID, Client Secret, and Tenant ID (from Azure overview page).

Limits

• Standard licenses: 10,000 emails/day, 30 emails/minute per user.
• Shared mailboxes: same limits.

Yahoo

OAuth 2.0 via Yahoo Developer Network.

Setup

1. Create an app at developer.yahoo.com/apps.
2. Request Mail scope (read/send).
3. Redirect URI: https://YOUR-STRAPI-HOST/admin/plugins/magic-mail/oauth/yahoo/callback.
4. Copy Client ID and Client Secret.
5. In Magic-Mail admin → Add Account → Yahoo OAuth, authorize.

Notes

• Yahoo uses SMTP-OAuth2 under the hood.
• Limits similar to Gmail free (500/day).

SMTP (universal)

Works with any SMTP server: your own mail server, cPanel hosting, Office 365 SMTP, Mailtrap, MailHog, etc.

Setup

In Magic-Mail admin → Add Account → SMTP:

Field	Example	Notes
Host	smtp.gmail.com	Your SMTP server hostname
Port	587	587 for STARTTLS, 465 for SSL
Secure	false for port 587	Set to true for port 465
Username	noreply@example.com	Usually the full email address
Password	app-password	For Gmail use an App Password, not your Google password
From	noreply@example.com	Default sender

Common SMTP servers

Service	Host	Port	Secure
Gmail	smtp.gmail.com	587	false (STARTTLS)
Outlook.com	smtp.office365.com	587	false
Yahoo	smtp.mail.yahoo.com	587	false
Zoho	smtp.zoho.com	587	false
Amazon SES	email-smtp.REGION.amazonaws.com	587	false
Mailtrap (test)	sandbox.smtp.mailtrap.io	2525	false

SendGrid

API key based. Best for high-volume transactional and marketing email.

Setup

1. At sendgrid.com create an account (free tier: 100 emails/day).
2. Go to Settings → API Keys → Create API Key.
3. Give it Mail Send permission (Full Access works too).
4. Copy the key (you only see it once).
5. In Magic-Mail admin → Add Account → SendGrid, paste the key and set a From address. The from address must be verified under Sender Authentication.

Features

• Built-in email validation.
• Delivery analytics in the SendGrid dashboard.
• Template management (SendGrid-side templates also callable from Magic-Mail).

Mailgun

API key based. Designed for bulk sending and automated workflows.

Setup

1. Sign up at mailgun.com.
2. Verify a domain under Sending → Domains.
3. Copy the Private API Key from API security.
4. In Magic-Mail admin → Add Account → Mailgun, paste the key, domain, and region (us or eu).

Notes

• Mailgun's free tier is limited. Check current pricing at mailgun.com/pricing.
• Attachment support is limited compared to OAuth providers.

Choosing a provider

Use case	Recommended
SaaS transactional emails	SendGrid or Microsoft 365
Marketing newsletters	SendGrid (features) or Mailgun (volume)
Team-member invites	Gmail (personal touch) or SMTP
High-volume campaigns	Mailgun + SendGrid fallback
Enterprise with O365 licenses	Microsoft 365 (already paid for)
Self-hosted mail server	SMTP

Multi-provider strategy

Best practice is to register at least two providers and define routing rules with failover:

Primary:  SendGrid (API, fast, high-volume)
Fallback: Gmail OAuth (backup)
Emergency: SMTP (self-hosted server)

This way no email is lost even if a provider API goes down.

---

Next: Smart Routing Rules →