DaaS / Products / Complete Email Troubleshooting and Deliverability Workflow

Complete Email Troubleshooting and Deliverability Workflow

A developer experiencing email issues first resolves sending failures (550/SMTP errors), configures SPF/DKIM/DMARC authentication, optimizes deliverability for inbox placement, then troubleshoots why specific emails were still not received by recipients.

Products involved

Scenario

Use this workflow when your application’s outbound emails via Alibaba Mail fail with SMTP 550 or authorization errors, subsequently land in spam, or disappear after successful transmission. It chains failure resolution, DNS authentication, deliverability tuning, and recipient-side tracing into a single diagnostic pipeline.

Integration steps

  1. Resolve SMTP failures: Inspect Alibaba Mail logs for 550 5.7.1 or not authorized responses. Switch to smtp.qiye.aliyun.com:465 with STARTTLS and validate credentials. If SPF bounce occurs, proceed to DNS alignment.
  2. Register domain in Resend: Call POST https://api.resend.com/domains with {"name": "yourdomain.com", "region": "us-east-1"}. Store the returned id for subsequent verification.
  3. Publish authentication records: Fetch required DNS entries via GET https://api.resend.com/domains/{id}/records. Add the TXT (SPF: v=spf1 include:spf.resend.com ~all), CNAME (DKIM), and TXT (DMARC: v=DMARC1; p=quarantine; rua=mailto:[email protected]) records to your DNS provider.
  4. Verify domain status: Poll GET https://api.resend.com/domains/{id} until status returns "verified". If Resend returns 403 Forbidden, run dig yourdomain.com TXT to confirm propagation before retrying.
  5. Optimize inbox placement: Send via POST https://api.resend.com/emails with "tags": [{"name": "type", "value": "transactional"}] and "headers": {"X-Mailer": "Resend"}. Monitor Resend’s deliverability dashboard; if spam placement persists, reduce HTML payload size and add plain-text fallback.
  6. Trace missing deliveries: If Resend reports delivered but recipients report missing mail, invoke the alimail-troubleshoot-received routing path. Log into Alibaba Mail WebMail, check Settings > Anti-Spam > Quarantine, and verify recipient quota limits or local blocklists.
  7. Validate end-to-end: Execute curl -X POST https://api.resend.com/emails -H "Authorization: Bearer $RESEND_API_KEY" -H "Content-Type: application/json" -d '{"from":"[email protected]","to":"[email protected]","subject":"Workflow Test","html":"<p>Delivered</p>"}' and confirm inbox arrival.

Architecture

Alibaba Mail operates as the SMTP relay and recipient-side mailbox, enforcing inbound SPF/DKIM validation, applying anti-spam filtering, and managing WebMail routing. Resend acts as the API-driven sending layer and deliverability orchestrator, generating cryptographic signatures, tracking bounce/spam metrics, and managing domain verification. DNS bridges both: Resend supplies authentication records, while Alibaba Mail consumes them for inbound policy enforcement.

Prerequisites

Common pitfalls

Typical questions

FAQ

Q: How do I resolve email sending failures and 550 SMTP errors? A: Resolve sending failures and 550 SMTP errors by running the alimail-resolve-failure skill in Alibaba Mail. This initial step clears delivery blocks before you proceed to authentication setup.

Q: How can I configure SPF, DKIM, and DMARC to improve email deliverability and inbox placement? A: Configure SPF, DKIM, and DMARC authentication using the resend-optimize-deliverability skill to optimize inbox placement. This step improves overall deliverability after sending failures are resolved.

Q: What should I do if an email is sent but never received by the recipient? A: Troubleshoot missing messages by executing the alimail-troubleshoot-received skill once authentication and deliverability are configured. This final step identifies why specific emails fail to reach recipients.