Guides & Support

Quick Start Guides

Get up and running quickly with these integration guides for popular languages and frameworks.

PHP Quick Start Example

$ch = curl_init('https://api.cascade-mail.net/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'from'    => ['email' => 'hello@yourdomain.com', 'name' => 'Your App'],
        'to'      => [['email' => 'user@example.com']],
        'subject' => 'Welcome aboard!',
        'html'    => '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);

Deliverability Best Practices

Inbox placement depends on a combination of authentication, sending practices, content quality, and list hygiene. Follow these guidelines to maximize deliverability.

Authentication Is Non-Negotiable

Every sending domain must have properly configured SPF, DKIM, and DMARC records. Cascade Mail will not allow sending from a domain without at least SPF and DKIM verification. Misconfigured authentication is the single most common reason emails land in spam.

Monitor Your Metrics

Keep a close eye on your complaint rate and bounce rate, as these are the two metrics ISPs care about most. Your complaint rate should stay below 0.1% (1 complaint per 1,000 emails). Your hard bounce rate should stay below 2%. If either metric exceeds these thresholds, pause sending and clean your list before continuing.

Content Guidelines

Avoid spam trigger patterns in your emails: excessive use of capital letters, overuse of exclamation marks, misleading subject lines, and image-only emails with no text content. Maintain a healthy text-to-image ratio and always include a plain text version alongside HTML.

Consistent Sending Patterns

ISPs favor predictable sending behavior. Sudden spikes in volume — especially from a new domain or IP — can trigger spam filters. If you need to increase volume significantly, follow the IP Warmup Guide below.

DNS Setup Guide

Proper DNS configuration is the foundation of good email deliverability. This guide walks through each record you need to configure.

Step 1: Add Your Domain

In your Cascade Mail dashboard, navigate to Settings → Sending Domains and click "Add Domain." Enter your domain name and click Add. The system will generate your required DNS records.

Step 2: Configure SPF

Add or update your domain's SPF TXT record. If you already have an SPF record, add include:spf.cascade-mail.net to your existing record rather than creating a second one (multiple SPF records will cause failures).

v=spf1 include:spf.cascade-mail.net ~all

Step 3: Configure DKIM

Add the CNAME record provided in your dashboard. This publishes your DKIM public key through Cascade Mail's DNS:

cm._domainkey.yourdomain.com  CNAME  cm._domainkey.cascade-mail.net

Step 4: Configure DMARC

If you don't already have a DMARC record, start with a monitoring policy to collect reports before enforcing:

_dmarc.yourdomain.com  TXT  "v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com"

Once you've verified alignment, tighten the policy to p=quarantine or p=reject for maximum protection.

Step 5: Verify

Return to the Cascade Mail dashboard and click "Verify DNS." Propagation typically takes a few minutes but can take up to 48 hours depending on your DNS provider's TTL settings.

IP Warmup Guide

When you begin sending on a new dedicated IP address, ISPs have no sending history to judge your reputation. Warming up an IP means gradually increasing your sending volume so ISPs can build trust over time.

Recommended Warmup Schedule

Start with your most engaged subscribers (those who opened or clicked in the last 30 days) and gradually expand to your full list over 2–4 weeks:

• Days 1–3: 200–500 emails per day to your most engaged contacts.
• Days 4–7: 1,000–2,500 per day, expanding to contacts active in the last 60 days.
• Week 2: 5,000–10,000 per day, expanding to contacts active in the last 90 days.
• Week 3: 15,000–30,000 per day, beginning to include your broader list.
• Week 4+: Continue doubling volume every few days until you reach your target sending rate.

List Hygiene

Maintaining a clean subscriber list is critical for deliverability and compliance. Stale, invalid, or unengaged addresses drag down your sender reputation and waste sending resources.

Regular Cleaning

Remove hard bounces immediately (Cascade Mail does this automatically). Review and suppress soft bounces that have failed 3+ consecutive times. Implement a sunset policy for unengaged subscribers — if a contact hasn't opened or clicked in 90–180 days, move them to a re-engagement segment or remove them.

Re-engagement Campaigns

Before removing inactive subscribers, send a re-engagement campaign asking if they'd like to continue receiving email. This gives subscribers a chance to opt back in while cleaning out addresses that are truly disengaged. Remove anyone who doesn't respond to the re-engagement within 30 days.

Never Purchase Lists

Purchased, rented, or scraped lists violate our Terms of Service and virtually guarantee high bounce and complaint rates. Every address on your list must have been collected through legitimate opt-in methods.

Troubleshooting

Emails Going to Spam

If your emails are landing in the spam folder, check your authentication first — verify that SPF, DKIM, and DMARC are all passing by examining message headers. Next, review your content for spam trigger patterns. Check your sending domain and IP against major blocklists (MXToolbox is a good free tool). Finally, review your sending metrics in the Cascade Mail dashboard for elevated bounce or complaint rates.

High Bounce Rates

A spike in bounces typically indicates list quality issues. Common causes include sending to a stale list that hasn't been mailed recently, imported addresses that were not properly validated, typo domains (e.g., gmial.com instead of gmail.com), or role-based addresses (info@, admin@) that frequently reject mail. Clean your list and consider using an email validation service before importing.

Messages Deferred / Slow Delivery

Deferrals mean the receiving server asked Cascade Mail to try again later. This is normal behavior, especially when sending to large ISPs with rate limits. Cascade Mail automatically retries deferred messages with intelligent backoff. If deferrals persist for more than 24 hours, check whether your sending domain or IP has been blocklisted.

API Errors

For API-specific troubleshooting, see the error handling section in our Documentation. Common issues include expired or invalid API keys (401 errors), malformed JSON in request bodies (400 errors), and rate limiting during high-volume sending (429 errors).

Frequently Asked Questions

What's the difference between transactional and marketing email?

Transactional emails are triggered by a user action — order confirmations, password resets, shipping notifications, account alerts. Marketing emails are sent in bulk to promote products, share content, or nurture leads. Both types can be sent through Cascade Mail, but they have different compliance requirements and are best sent from separate sending streams.

Do I need a dedicated IP?

For most senders, shared IPs are fine and benefit from the collective good reputation of all Cascade Mail customers. Dedicated IPs are recommended if you send more than 100,000 emails per month consistently, need full control over your IP reputation, or have specific compliance requirements that mandate IP isolation. Keep in mind that dedicated IPs require a proper warmup period.

How do I migrate from another ESP?

Start by exporting your subscriber lists and suppression lists from your current provider. Import both into Cascade Mail — the suppression list is critical to avoid re-mailing addresses that have previously bounced or complained. Update your DNS records to point to Cascade Mail's sending infrastructure. If using a dedicated IP, follow the warmup guide. We recommend running both providers in parallel for a brief overlap period to ensure no disruption.

What are feedback loops (FBLs)?

Feedback loops are programs offered by major ISPs (Gmail, Yahoo, Outlook, etc.) that notify senders when recipients mark their messages as spam. Cascade Mail is registered with all major FBL programs and automatically processes complaints by adding the complaining address to your suppression list.

Contact Support

Need help with something not covered here? Our support team is available to assist.