Webhook Payload
When MyMX receives an email for your domain, it sends a POST request to your webhook endpoint with the following JSON payload. The Content-Type is always application/json.
| Field | Type | Description |
|---|---|---|
| idreq | string | Unique delivery event ID. |
| eventreq | "email.received" | Event type identifier. Always `"email.received"` for this event type. |
| versionreq | WebhookVersion | API version in date format (YYYY-MM-DD). Use this to detect version mismatches between webhook and SDK. |
| deliveryreq | object | Metadata about this webhook delivery. |
| endpoint_idreq | string | ID of the webhook endpoint receiving this event. Matches the endpoint ID from your MyMX dashboard. |
| attemptreq | number | Delivery attempt number, starting at 1. Increments with each retry if previous attempts failed. |
| attempted_atreq | string | ISO 8601 timestamp (UTC) when this delivery was attempted. |
| emailreq | object | The email that triggered this event. |
| idreq | string | Unique email ID in MyMX. Use this ID when calling MyMX APIs to reference this email. |
| received_atreq | string | ISO 8601 timestamp (UTC) when MyMX received the email. |
| smtpreq | object | SMTP envelope information. This is the "real" sender/recipient info from the SMTP transaction, which may differ from the headers (e.g., BCC recipients). |
| helo | string | null | HELO/EHLO hostname from the sending server. Null if not provided during SMTP transaction. |
| mail_fromreq | string | SMTP envelope sender (MAIL FROM command). This is the bounce address, which may differ from the From header. |
| rcpt_toreq | string[] | SMTP envelope recipients (RCPT TO commands). All addresses that received this email in a single delivery. |
| headersreq | object | Parsed email headers. These are extracted from the email content, not the SMTP envelope. |
| message_id | string | null | Message-ID header value. Null if the email had no Message-ID header. |
| subject | string | null | Subject header value. Null if the email had no Subject header. |
| fromreq | string | From header value. May include display name: `"John Doe" <john@example.com>` |
| toreq | string | To header value. May include multiple addresses or display names. |
| date | string | null | Date header value as it appeared in the email. Null if the email had no Date header. |
| contentreq | object | Raw email content and download information. |
| rawreq | RawContent | Raw email in RFC 5322 format. May be inline (base64) or download-only depending on size. |
| downloadreq | object | Download information for the raw email. Always present, even if raw content is inline. |
| parsedreq | ParsedData | Parsed email content (body text, HTML, attachments). Check `status` to determine if parsing succeeded. |
| ParsedDataComplete | object | Parsed email content when parsing succeeded. |
| ParsedDataFailed | object | Parsed email content when parsing failed. |
| analysisreq | EmailAnalysis | Email analysis and classification results. |
| spamassassin | object | SpamAssassin analysis results. |
| forward | ForwardAnalysis | Forward detection and analysis results. |
| authreq | EmailAuth | Email authentication results (SPF, DKIM, DMARC). |
| spfreq | SpfResult | SPF verification result. |
| dmarcreq | DmarcResult | DMARC verification result. |
| dmarcPolicy | DmarcPolicy | DMARC policy from the sender's DNS record. |
| dmarcFromDomain | string | null | The organizational domain used for DMARC lookups. |
| dmarcSpfAlignedreq | boolean | Whether SPF aligned with the From: domain for DMARC purposes. |
| dmarcDkimAlignedreq | boolean | Whether DKIM aligned with the From: domain for DMARC purposes. |
| dmarcSpfStrict | boolean | null | Whether DMARC SPF alignment mode is strict. |
| dmarcDkimStrict | boolean | null | Whether DMARC DKIM alignment mode is strict. |
| dkimSignaturesreq | DkimSignature[] | All DKIM signatures found in the email with their verification results. |
Notes
Delivery & retries
The delivery.attempt field indicates which delivery attempt this is (1-6). If your endpoint returns a non-2xx response or is unreachable, we automatically retry up to 6 times over approximately 10 hours:
- Immediate (first attempt)
- +60 seconds (inline retry)
- +5 minutes
- +30 minutes
- +2 hours
- +8 hours
The first two attempts happen immediately. Attempts 3-6 are scheduled and may vary by up to 5 minutes.
The id field stays the same across all retry attempts for the same email, so you can use it for idempotency. If you receive a webhook you've already processed, just return 2xx to acknowledge it.
Raw email content
The raw email is included inline (base64-encoded) if it's smaller than 256KB. For larger emails, raw.included will be false and you'll need to fetch it from download.url.
Attachments
Attachment metadata is always included in the payload. To download the actual files, fetch the attachments_download_url which returns a tar.gz archive. Each file in the archive is named according to its tar_path.
Parsing failures
If email parsing fails, parsed.status will be "failed" and parsed.error will contain details. You can still access the raw email content to parse it yourself.
Spam analysis
The analysis.spamassassin.score field contains the SpamAssassin spam score. Higher scores indicate higher likelihood of spam. Typical thresholds are 5+ for spam. You decide how to handle it. We never silently drop mail.