Responses

{
  "Status": "Queued",
  "messageId": "e390eee8-4624-4dee-a158-01dc8baa7bd0",
  "toEmail": "recipient@example.com",
  "fromEmail": "hello@yourdomain.com",
  "cc": [],
  "bcc": [],
  "attachmentsCount": 0,
  "dkimSigned": true,
  "quota": {
    "plan": "developer",
    "monthlyUsed": 42,
    "monthlyLimit": 50000,
    "paygCreditsLeft": 0
  }
}

// messageId is a UUID that uniquely identifies this send.
// Use it with GET /v1/user/email/events to track delivery status.

// If the sender domain's SPF record doesn't include Altermail's mail server,
// a warnings array is included:
{
  "Status": "Queued",
  "messageId": "e390eee8-4624-4dee-a158-01dc8baa7bd0",
  "dkimSigned": true,
  "warnings": [
    "yourdomain.com has no SPF record. Add a TXT record: \"v=spf1 include:mail.altermail-console.com.ng ~all\". Without it the relay may silently discard your emails."
  ],
  "quota": { ... }
}

// Missing required field
{ "message": "email is required." }

// Token header missing
{ "message": "token header is required." }

// Token not found in database
{ "message": "Invalid token" }

// Unexpected extra field in body
{ "message": "No extra fields allowed." }

// Invalid email format (to or fromEmail)
{ "message": "Invalid email format." }

// Invalid email format in cc or bcc
{ "message": "Invalid email format in cc/bcc fields." }

// Invalid replyTo address
{ "message": "Invalid replyTo email format." }

// Recipient domain confirmed non-existent by DNS (ENOTFOUND / ENODATA)
{ "message": "Recipient domain 'example.com' does not exist. Email address is invalid." }

// Recipient domain exists but has no mail server (no MX record and no A-record fallback)
{ "message": "Recipient domain 'example.com' has no mail server. Email address is invalid." }

// Recipient was previously hard-bounced and is on the suppression list
{ "message": "The recipient address 'user@example.com' has previously hard-bounced and is suppressed. Remove it from your list." }

// mailBodyHtml missing and no template configured on the account
{ "message": "mailBodyHtml is required when no email template is configured. Set a template in your dashboard or include mailBodyHtml in the request." }

// Active template or colour scheme was deleted after being saved
{ "message": "Your saved template or colour scheme no longer exists. Update your template settings in the dashboard." }

// Too many recipients (To + CC + BCC > 50)
{ "message": "Too many recipients. Maximum 50 per request (To + CC + BCC combined)." }

// Subject too long (> 998 chars)
{ "message": "Subject must be 998 characters or fewer (RFC 2822)." }

// Email body too large (> 500 KB)
{ "message": "mailBodyHtml exceeds the 500 KB limit." }
{ "message": "mailBodyText exceeds the 500 KB limit." }

// attachments field is present but not an array
{ "message": "attachments must be an array." }

// Too many attachments (> 10)
{ "message": "Maximum 10 attachments per email." }

// Malformed attachment or blocked file type
{ "message": "Each attachment must have a filename and content or path. Executable and script file types (e.g. .exe, .dll, .bat, .ps1) are not allowed." }

// Total attachment size exceeds 25 MB
{ "message": "Total attachment size exceeds the 25 MB limit." }

// Domain not verified on your account
{ "message": "Sender domain is not verified. Verify the domain before sending." }

// Plan domain limit reached when adding a new domain
{ "message": "Your free plan allows a maximum of 1 domain. Upgrade your plan to add more." }

// Account suspended due to high hard-bounce rate
{ "message": "Your account has been suspended due to a high hard-bounce rate. Please contact support@altermail-console.com.ng to appeal." }

// Monthly allowance used up with no PAYG overflow credits
{ "message": "Monthly quota exhausted. Buy a PAYG bundle or upgrade your subscription.", "billing": { ... } }

// Paid subscription period ended and renewal is pending/failed
{ "message": "Subscription cycle has ended. Renewal charge is pending or failed.", "billing": { ... } }

// Free plan daily cap hit
{ "message": "Free plan daily limit exceeded. Limit is 100 emails/day.", "billing": { ... } }

// Send endpoint token rate limit (60 sends/min per account)
{ "message": "Too many send requests for this account. Please wait before sending again." }

// Global rate limit (200 requests/15 min per IP)
{ "message": "Too many requests, please slow down." }

{ "message": "Oops something went wrong." }