Send Email

Send a single transactional email, or fan out to many recipients with the bulk endpoint. Both accept HTML and plain-text bodies, CC/BCC, custom headers, attachments, and tracking options.

Endpoint

POST /v1/email/send

curl -X POST https://api.afriroute.ai/api/v1/email/send \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Order Confirmation #12345",
    "html": "<h2>Thank you for your order!</h2><p>Order #12345 is confirmed.</p>",
    "text": "Thank you for your order! Order #12345 is confirmed."
  }'

Parameters

Field	Type	Required	Description
from	string	Yes	Verified sender address ([email protected])
to	string / array	Yes	One or more recipient addresses
subject	string	Yes	Subject line (recommended ≤ 78 chars)
html	string	Yes*	HTML body. *Required unless text or template is set
text	string	No	Plain-text alternative (strongly recommended)
cc	array	No	Carbon-copy recipients
bcc	array	No	Blind carbon-copy recipients
reply_to	string	No	Address used when recipients reply
template	string	No	Template name; see Templates
variables	object	No	Key/value pairs injected into the template
attachments	array	No	File attachments; see Attachments
headers	object	No	Custom email headers
tracking	object	No	Open/click tracking flags; see Tracking

Code Samples

send-email.js

const response = await fetch('https://api.afriroute.ai/api/v1/email/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $AFRIROUTE_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Order Confirmation #12345',
    html: '<h2>Thank you for your order!</h2>',
    text: 'Thank you for your order!'
  })
});

const data = await response.json();
console.log(data.message_id); // email_abc123

send_email.py

import requests

response = requests.post(
    'https://api.afriroute.ai/api/v1/email/send',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'from': '[email protected]',
        'to': '[email protected]',
        'subject': 'Order Confirmation #12345',
        'html': '<h2>Thank you for your order!</h2>',
        'text': 'Thank you for your order!'
    }
)
print(response.json()['message_id'])

Response

{
  "status": "queued",
  "message_id": "email_7K8L9M0N",
  "to": "[email protected]",
  "from": "[email protected]",
  "created_at": "2026-05-28T10:30:00Z"
}

CC, BCC & Reply-To

{
  "from": "[email protected]",
  "to": "[email protected]",
  "cc": ["[email protected]"],
  "bcc": ["[email protected]"],
  "reply_to": "[email protected]",
  "subject": "Proposal for Review",
  "html": "<p>Please review the attached proposal.</p>"
}

Bulk Email

Send to many recipients in a single call. Each recipient can carry its own merge variables.

POST /v1/email/bulk

bulk-email.js

await fetch('https://api.afriroute.ai/api/v1/email/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $AFRIROUTE_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '[email protected]',
    subject: 'Monthly Newsletter — May 2026',
    template: 'newsletter',
    recipients: [
      { email: '[email protected]', variables: { name: 'Alice' } },
      { email: '[email protected]',   variables: { name: 'Bob' } }
    ],
    batch_size: 100
  })
});

Best Practices

• Always supply text alongside html — improves accessibility and spam scoring.
• Keep subject lines under 78 characters to avoid truncation in mobile clients.
• Verify from domains before sending; unverified domains return DOMAIN_NOT_VERIFIED.
• Batch large sends (100–500 per batch) and implement retry with back-off.

Error Handling

try {
  await sendEmail(payload);
} catch (error) {
  if (error.code === 'INVALID_EMAIL') {
    console.error('Recipient address is malformed');
  } else if (error.code === 'DOMAIN_NOT_VERIFIED') {
    console.error('Verify your sending domain first');
  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
    console.error('Slow down — too many requests');
  }
}

Code	HTTP	Meaning
INVALID_EMAIL	400	Recipient or sender address is malformed
DOMAIN_NOT_VERIFIED	403	Sending domain not verified
MISSING_BODY	400	No html, text, or template provided
RATE_LIMIT_EXCEEDED	429	Too many requests

Related Resources

• Email Overview
• Templates
• Attachments
• Tracking & Analytics

---

Last Updated: May 2026 · Need help? Contact Support →