Mail Send API

API ya kutuma barua pepe za muamala kwa urahisi. Inasaidia utumaji wa moja moja na utumaji wa kundi kupitia foleni.

Ruhusa inayohitajika: mail

POST /api/v1/mail/send

Inatuma barua pepe moja mara moja. Inatumwa kupitia mtoa huduma wa SMTP chaguomsingi wa mtumiaji.

Request Body

{
  "to": "user@example.com",
  "subject": "Order Confirmation",
  "html": "<h1>Your order has been confirmed</h1>",
  "text": "Your order has been confirmed",
  "from_email": "support@yourdomain.com",
  "from_name": "Your App",
  "reply_to": "reply@yourdomain.com",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "tags": ["order", "confirmation"],
  "metadata": {"order_id": "12345"}
}

Parameters

Field	Type	Required	Description
`to`	string	Ndiyo	Barua pepe ya mpokeaji
`subject`	string	Ndiyo	Mada ya barua pepe
`html`	string	Yes*	Maudhui ya HTML (*html au text inahitajika)
`text`	string	Yes*	Maudhui ya maandishi
`from_email`	string	Hapana	Barua pepe ya mtumaji (chaguomsingi: mipangilio ya mtoa SMTP)
`from_name`	string	Hapana	Jina la mtumaji
`reply_to`	string	Hapana	Anwani ya kujibu
`cc`	array	Hapana	Orodha ya barua pepe za nakala
`bcc`	array	Hapana	Orodha ya barua pepe za nakala ya siri
`tags`	array	Hapana	Lebo za barua pepe (kwa uainishaji)
`metadata`	object	Hapana	Metadata maalum ya mtumiaji

Response

{
  "success": true,
  "data": {
    "message_id": "<abc123.1706600000@mailpass.im>",
    "status": "sent",
    "to": "user@example.com",
    "from": "support@yourdomain.com"
  }
}

POST /api/v1/mail/send-batch

Inaongeza barua pepe nyingi kwenye foleni. Upeo wa 100, zinasindikwa na Cron.

Request Body

{
  "messages": [
    {"to": "a@example.com", "subject": "Hello A", "html": "<p>Hi A</p>"},
    {"to": "b@example.com", "subject": "Hello B", "html": "<p>Hi B</p>"}
  ],
  "from_email": "support@yourdomain.com",
  "from_name": "Your App"
}

Response

{
  "success": true,
  "data": {
    "total": 2,
    "queued": 2,
    "failed": 0,
    "messages": [
      {"to": "a@example.com", "status": "queued", "queue_id": 101},
      {"to": "b@example.com", "status": "queued", "queue_id": 102}
    ]
  }
}

GET /api/v1/mail/status/{message_id}

Inauliza hali na matukio ya ufuatiliaji wa barua pepe iliyotumwa.

Response

{
  "success": true,
  "data": {
    "message": {
      "message_id": "<abc123@mailpass.im>",
      "from_email": "support@yourdomain.com",
      "to_email": "user@example.com",
      "subject": "Order Confirmation",
      "status": "sent",
      "error_message": null,
      "sent_at": "2026-01-30T12:00:00",
      "created_at": "2026-01-30T12:00:00"
    },
    "events": [
      {
        "event_type": "open",
        "ip_address": "192.168.1.1",
        "user_agent": "Mozilla/5.0...",
        "created_at": "2026-01-30T12:05:00"
      }
    ]
  }
}

Error Codes

Code	HTTP	Description
`VALIDATION_ERROR`	400	Sehemu zinazohitajika zimekosekana au barua pepe si halali
`NO_SMTP_PROVIDER`	422	Mtoa huduma wa SMTP chaguomsingi haujasanidiwa
`SEND_LIMIT_EXCEEDED`	429	Kikomo cha kutuma kwa siku/saa cha mtoa SMTP kimezidishwa
`SEND_FAILED`	500	Kushindwa kutuma barua pepe

Mifano ya matumizi

cURL

# Single send
curl -X POST https://dev.mailpass.im/api/v1/mail/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>Hello World</p>"
  }'

# Batch send
curl -X POST https://dev.mailpass.im/api/v1/mail/send-batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"to": "a@example.com", "subject": "Hi A", "html": "<p>Hello A</p>"},
      {"to": "b@example.com", "subject": "Hi B", "html": "<p>Hello B</p>"}
    ],
    "from_email": "support@yourdomain.com"
  }'

# Check status
curl https://dev.mailpass.im/api/v1/mail/status/MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (fetch)

// Single send
const response = await fetch('https://dev.mailpass.im/api/v1/mail/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: 'user@example.com',
    subject: 'Hello',
    html: '<p>Hello World</p>'
  })
});
const data = await response.json();
console.log(data.data.message_id);

PHP SDK

$client = new MailPass\Client('mp_live_YOUR_KEY');

// Single send
$result = $client->mail->send([
    'to' => 'user@example.com',
    'subject' => 'Hello',
    'html' => '<p>Hello World</p>',
]);
echo $result['data']['message_id'];

Usanidi wa mtoa SMTP unahitajika

Ili kutumia Mail Send API, lazima kwanza uongeze mtoa huduma wa SMTP na uuweke kama chaguomsingi katika Dashibodi > Mipangilio ya SMTP. SMTP ya MailPass yenyewe, Amazon SES, SendGrid, Mailgun na mengineyo yanasaidiwa.

Mail Send API

Request Body

Parameters

Response

Request Body

Response

Response

Error Codes

Mifano ya matumizi

cURL

JavaScript (fetch)

PHP SDK

Usanidi wa mtoa SMTP unahitajika

Tunatumia kuki