--- title: "Send a batch of emails" method: POST path: "/v1/emails/batch" tags: ["Emails"] --- # Send a batch of emails `POST /v1/emails/batch` ## Request - Base URL: `https://api.honkio.ca` - URL: `https://api.honkio.ca/v1/emails/batch` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` Requires `emails:w`. ## Request body - union: A JSON array of up to 100 independent emails, or one message for up to 500 recipients as an object with a recipients list. Attachments are not available in a batch, and scheduling only in the object form. The request body may be at most 10 MB; send a larger email on its own. - object[]: An array of up to 100 emails, each sent on its own. Every item is checked before any is sent. - `from` string: Sender, optionally with a name. Its domain must be a verified sending domain on your account. Optional when the template sets one. - `to` union, required: A string or an array; at most 50 recipients across to, cc and bcc. - string, email - string[] - `cc` union: A string or an array. - string, email - string[] - `bcc` union: A string or an array. - string, email - string[] - `reply_to` union: A string or an array. - string, email - string[] - `subject` string: Up to 998 characters. Leave out subject, html and text when you send a template. - `html` string: The HTML body: at most 2 MB, before and after variables are substituted. Give html, text or both, unless you send a template. - `text` string: The plain text body: at most 2 MB, before and after variables are substituted. Give html, text or both, unless you send a template. - `template` object: Send a stored template instead of subject, html and text: its id or alias, and values for its variables. - `id` string, required: The template's id or alias. A live key sends its published version; a test key sends its draft. - `variables` object: Values for the template's variables, by key. - `variables` object: Values to substitute into placeholders in subject, html and text. Ignored when template is set; a template's own variables go in template.variables instead. - `headers` object: Extra email headers, sent as given. Headers HonkIO sets itself (To, From, Subject, Content-Type, List-Unsubscribe and the like) and any name starting with ARC- or X-SES- are refused with EMAIL_HEADER_INVALID. - `tags` object[]: Up to 10 name and value pairs, each part 1 to 256 letters, digits, underscores or hyphens. Names starting with honkio_ are reserved. Tags are kept after the subject and body are purged, so keep personal information out of them. - `name` string, required - `value` string, required - `is_commercial` boolean: False by default. True marks a commercial message under CASL: it goes to exactly one recipient, needs consent on file for that address, and carries an unsubscribe footer and header. - `tracking` object: Open and click tracking for this email, overriding the sending domain's setting. - `opens` boolean: Track opens with a pixel. - `clicks` boolean: Track clicks by rewriting links. - `disable_unsubscribe_footer` boolean: Leave out the unsubscribe footer HonkIO adds to a commercial email. The one click unsubscribe header is still sent: put your own unsubscribe link in the body. - object: One message for up to 500 recipients, each with its own variables. - `from` string: Sender, optionally with a name. Its domain must be a verified sending domain on your account. Optional when the template sets one. - `subject` string: Up to 998 characters. Leave out subject, html and text when you send a template. - `html` string: The HTML body: at most 2 MB, before and after variables are substituted. Give html, text or both, unless you send a template. - `text` string: The plain text body: at most 2 MB, before and after variables are substituted. Give html, text or both, unless you send a template. - `template` object: Send a stored template instead of subject, html and text: its id or alias, and values for its variables. - `id` string, required: The template's id or alias. A live key sends its published version; a test key sends its draft. - `variables` object: Values for the template's variables, by key. - `headers` object: Extra email headers, sent as given. Headers HonkIO sets itself (To, From, Subject, Content-Type, List-Unsubscribe and the like) and any name starting with ARC- or X-SES- are refused with EMAIL_HEADER_INVALID. - `tags` object[]: Up to 10 name and value pairs, each part 1 to 256 letters, digits, underscores or hyphens. Names starting with honkio_ are reserved. Tags are kept after the subject and body are purged, so keep personal information out of them. - `name` string, required - `value` string, required - `is_commercial` boolean: False by default. True marks a commercial message under CASL: it goes to exactly one recipient, needs consent on file for that address, and carries an unsubscribe footer and header. - `scheduled_at` string, date-time, nullable: Send later: an ISO 8601 date-time, 1 minute to 30 days ahead. - `tracking` object: Open and click tracking for this email, overriding the sending domain's setting. - `opens` boolean: Track opens with a pixel. - `clicks` boolean: Track clicks by rewriting links. - `disable_unsubscribe_footer` boolean: Leave out the unsubscribe footer HonkIO adds to a commercial email. The one click unsubscribe header is still sent: put your own unsubscribe link in the body. - `recipients` object[], required: Up to 500 recipients, each sent their own email. - `to` string, email, required: The recipient's address. - `variables` object: Values for this recipient's placeholders or template variables. ## Other responses - `401`: Missing, invalid, revoked or expired API key. - `402`: The account has no balance, or a LIVE key was used before the first top-up. - `403`: FORBIDDEN, EMAIL_DOMAIN_NOT_ALLOWED or SENDING_PAUSED (live email is paused; details carry paused_until, reason and channel: "email"). Refused before any item is sent. - `429`: TEST_EMAIL_QUOTA_EXCEEDED: with a test key, the batch would take the account past 200 test emails in 24 hours, counting one per recipient of the object form and one per email of the array form. It is refused whole, before any email is created (details carry limit, used, requested and window_hours). Or RATE_LIMITED at 100 requests per second. - `500`: Unexpected server error. --- [API](https://skmtc.dev/honkio/apis/honkio-api.md) · [All operations](https://skmtc.dev/honkio/apis/honkio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/honkio/apis/honkio-api/revisions/ce4ed3fe9691?raw)