Request Fields

email

stringrequired

Primary recipient email address.

fromEmail

stringrequired

Sender address. Must use a domain verified on your account (e.g. hello@yourdomain.com).

fromName

stringoptional

Display name shown in the recipient's inbox (e.g. 'Obodom Farms'). Overrides your account business name for this send only. Defaults to your account business name → first name → email local part.

subject

stringrequired

Email subject line. Maximum 998 characters (RFC 2822).

mailBodyHtml

stringoptional

HTML body of the email. Required when no email template is configured on your account. If you have an active template and omit this field, the template is used automatically. If you pass this field alongside an active template, it overrides the template.

mailBodyText

stringoptional

Plain-text fallback. When using a template, this field provides the content injected into the template body. Strongly recommended in all cases; improves deliverability and shown by clients that don't render HTML.

cc

string | string[]optional

CC recipient(s). Single email string or an array. Each address consumes one quota credit.

bcc

string | string[]optional

BCC recipient(s). Same rules as cc. Recipients are hidden from each other.

replyTo

stringoptional

Reply-to address. When a recipient hits reply, their client uses this instead of fromEmail.

attachments

arrayoptional

Array of attachment objects. Maximum 10 per request. Each must have filename and at least one of content (base64 string) or path (server file path). Harmful or potentially malicious file types (e.g. .exe, .dll, .bat, .ps1, .js, .jar) are blocked and will be rejected.

category

"marketing" | "transactional"optional

Email category. Pass "transactional" for OTPs, password resets, receipts, order confirmations, and account alerts. Transactional emails always reach the recipient regardless of unsubscribe status. Pass "marketing" for newsletters, promotions, and bulk campaigns. Marketing emails are blocked for recipients who have unsubscribed, quota is still consumed, and a soft bounce is recorded. If omitted, Altermail auto-detects the category from the subject and body; include this field explicitly to ensure correct behaviour.

Field	Type	Required	Description
`email`	`string`	required	Primary recipient email address.
`fromEmail`	`string`	required	Sender address. Must use a domain verified on your account (e.g. hello@yourdomain.com).
`fromName`	`string`	optional	Display name shown in the recipient's inbox (e.g. 'Obodom Farms'). Overrides your account business name for this send only. Defaults to your account business name → first name → email local part.
`subject`	`string`	required	Email subject line. Maximum 998 characters (RFC 2822).
`mailBodyHtml`	`string`	optional	HTML body of the email. Required when no email template is configured on your account. If you have an active template and omit this field, the template is used automatically. If you pass this field alongside an active template, it overrides the template.
`mailBodyText`	`string`	optional	Plain-text fallback. When using a template, this field provides the content injected into the template body. Strongly recommended in all cases; improves deliverability and shown by clients that don't render HTML.
`cc`	`string \| string[]`	optional	CC recipient(s). Single email string or an array. Each address consumes one quota credit.
`bcc`	`string \| string[]`	optional	BCC recipient(s). Same rules as cc. Recipients are hidden from each other.
`replyTo`	`string`	optional	Reply-to address. When a recipient hits reply, their client uses this instead of fromEmail.
`attachments`	`array`	optional	Array of attachment objects. Maximum 10 per request. Each must have filename and at least one of content (base64 string) or path (server file path). Harmful or potentially malicious file types (e.g. .exe, .dll, .bat, .ps1, .js, .jar) are blocked and will be rejected.
`category`	`"marketing" \| "transactional"`	optional	Email category. Pass "transactional" for OTPs, password resets, receipts, order confirmations, and account alerts. Transactional emails always reach the recipient regardless of unsubscribe status. Pass "marketing" for newsletters, promotions, and bulk campaigns. Marketing emails are blocked for recipients who have unsubscribed, quota is still consumed, and a soft bounce is recorded. If omitted, Altermail auto-detects the category from the subject and body; include this field explicitly to ensure correct behaviour.