Troubleshoot API errors
A comprehensive reference for all error codes returned by the Mailpipe API, with explanations and resolution steps.
All API errors return a JSON body with an error field:
{
"error": "Validation failed: to.0.email: Invalid email"
}| Code | Status | Description |
|---|---|---|
200 | OK | Request succeeded |
400 | Bad Request | Invalid request body, missing required fields, or validation error |
401 | Unauthorized | Missing or invalid API key / session token |
403 | Forbidden | API key lacks required scope or doesn't belong to the organization |
404 | Not Found | Resource doesn't exist (mailbox, domain, message) |
429 | Too Many Requests | Rate limit exceeded — check Retry-After header |
500 | Internal Error | Unexpected server error — retry or contact support |
502 | Bad Gateway | Email provider returned an error (Resend, Postmark, etc.) |
You forgot to include the Authorization header.
curl -H "Authorization: Bearer mp_live_xxx" ...
The API key must match the format mp_live_* or mp_test_*. If you're calling from the web app, ensure you're passing a valid session token.
Your domain doesn't have an email provider configured. Go to Settings → Domains and set up a provider (Resend, Postmark, SendGrid, or Mailgun).
The to field must be an array of objects with a valid email field.
{
"to": [{ "email": "user@example.com", "name": "User" }]
}You need to verify your domain's DNS records before sending email. Check your domain settings and ensure MX, SPF, and DKIM records are correctly configured.
mp_test_* keys during development — they don't send real emails