Email Notifications

Mushu supports email as a notification channel alongside push notifications. Send emails from your own domain with automatic DKIM signing for reliable delivery.

How It Works

Email works like industry-standard services (SendGrid, Postmark, Resend):

1. Add your domain to Mushu
2. Add DNS records we provide to verify ownership
3. Register user email contacts (like device tokens)
4. Send emails via the unified notify API

Setting Up Email

Step 1: Add Your Domain

CLI

mushu email add-domain acme.com --from-name "Acme Inc"

API

POST /tenants/{tenant_id}/email/domains
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "domain": "acme.com",
  "from_name": "Acme Inc"
}

Response includes DNS records to add:

{
  "domain": "acme.com",
  "status": "pending",
  "dns_records": [
    {
      "type": "CNAME",
      "name": "xxx._domainkey.acme.com",
      "value": "xxx.dkim.amazonses.com",
      "purpose": "dkim"
    },
    ...
  ]
}

Step 2: Add DNS Records

Add the CNAME records to your DNS provider. These records authenticate Mushu to send email on behalf of your domain.

DNS propagation typically takes 15 minutes to 24 hours.

Step 3: Verify Domain

CLI

mushu email verify-domain acme.com

API

POST /tenants/{tenant_id}/email/domains/acme.com/verify

{
  "domain": "acme.com",
  "status": "verified",
  "verified_at": "2024-01-15T10:30:00Z"
}

Registering Email Contacts

Like device tokens for push, you register email addresses for users:

CLI

mushu email add-contact --user USER_ID --email user@example.com

API

POST /tenants/{tenant_id}/contacts
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "user_id": "user-123",
  "email": "user@example.com"
}

Sending Email

CLI

mushu email send \
  --user USER_ID \
  --subject "Your Receipt" \
  --html "<h1>Thanks for your purchase!</h1>"

API (Unified Endpoint)

POST /tenants/{tenant_id}/notify/unified
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "user_id": "user-123",
  "channel": "email",
  "email_subject": "Your Receipt",
  "email_body_html": "<h1>Thanks for your purchase!</h1>",
  "email_body_text": "Thanks for your purchase!",
  "email_from": "billing@acme.com"
}

Email Options

Field	Type	Description
user_id	string	Required. User with registered email contact.
channel	string	Required. Set to "email" (or "all" for push + email).
email_subject	string	Required. Email subject line.
email_body_html	string	Required. HTML email body.
email_body_text	string	Plain text fallback (recommended).
email_from	string	Sender address (must be @your-verified-domain).

Multi-Channel Notifications

Send to both push and email with a single request:

POST /tenants/{tenant_id}/notify/unified
{
  "user_id": "user-123",
  "channel": "all",

  "alert": {
    "title": "Order Shipped",
    "body": "Your order #12345 is on its way!"
  },

  "email_subject": "Your Order Has Shipped",
  "email_body_html": "<h1>Order #12345 Shipped</h1>...",
  "email_from": "orders@acme.com"
}

Response includes results for each channel:

{
  "success": true,
  "user_id": "user-123",
  "channel": "all",
  "push": {
    "success": true,
    "message_id": "abc-123"
  },
  "email": {
    "success": true,
    "message_id": "def-456"
  }
}

Unsubscribing

Users can be unsubscribed from email notifications:

mushu email unsubscribe user@example.com

Or via API:

DELETE /tenants/{tenant_id}/contacts/user@example.com

Unsubscribed contacts remain in the system but won't receive emails.

FAQ

What domains can I use?

Any domain you own and can add DNS records to. You must verify ownership by adding the CNAME records we provide.

How long does verification take?

DNS propagation typically takes 15 minutes to 24 hours. Some DNS providers are faster than others.

What if a user has multiple email addresses?

You can register multiple email contacts for a user. All subscribed contacts will receive the email.

What about deliverability?

Mushu uses AWS SES with proper DKIM signing. Emails are sent from your domain, so your domain reputation matters. Follow standard best practices: don't spam, honor unsubscribes, keep bounce rates low.

Can I use email without push?

Yes! Tenants can be email-only. Just skip the APNs configuration when creating your tenant.

How much does email cost?

Email is charged at $0.005 per notification (billed in micro-dollars). Using "all" channel charges for both push and email separately.