API gửi thư

1. Bắt đầu nhanh

Xin khoá API từ quản trị viên (mục Cài đặt → Khoá API trong hộp thư). Thử kết nối trước khi gửi thật:

curl https://mail.tamiload.com/api/v1/ping \
  -H "Authorization: Bearer KHOA_CUA_BAN"

{
  "ok": true,
  "ten_khoa": "Hệ thống đặt hàng Derma",
  "mien_duoc_gui": ["dermatreatment.com.vn"],
  "tran_ngay": 200,
  "da_dung_hom_nay": 0,
  "con_lai_hom_nay": 200
}

2. Xác thực

Mỗi yêu cầu phải mang khoá API, theo một trong hai cách:

Authorization: Bearer mtm_live_xxxxxxxxxxxx
X-API-Key: mtm_live_xxxxxxxxxxxx

Mỗi khoá bị giới hạn tên miền được phép đặt vào ô người gửi. Khoá cấp cho hệ thống Derma chỉ gửi được từ @dermatreatment.com.vn, không mượn được tên miền khác.

3. Gửi thư

POST https://mail.tamiload.com/api/v1/send

Các trường

Trả về khi thành công

{
  "ok": true,
  "messageId": "<abc123@dermatreatment.com.vn>",
  "id": "mub08fs1-u2glvqf7",
  "con_lai_hom_nay": 199
}

messageId là mã thư theo chuẩn thư điện tử — lưu lại để sau này nối hội thoại hoặc đối soát. id là mã trong hộp thư Minh Trung, dùng để tra lại ở mục Đã gửi.

Trả về khi hỏng

{
  "ok": false,
  "ma": "MIEN_CHUA_BAT",
  "error": "Tên miền \"abc.com\" chưa bật gửi thư. Tên miền dùng được: ..."
}

Luôn có ma để máy đọc và rẽ nhánh, và error là câu tiếng Việt để ghi nhật ký hoặc hiện cho người vận hành. Đừng bắt lỗi theo câu chữ — câu chữ có thể sửa, còn ma thì giữ nguyên.

4. Tệp đính kèm

"attachments": [
  {
    "filename": "don-hang-12345.pdf",
    "type": "application/pdf",
    "content": "<nội dung tệp mã hoá base64>"
  }
]

5. Bảng mã lỗi

6. Giới hạn

Mọi thư gửi qua API đều được lưu vào mục Đã gửi của hộp thư Minh Trung, ghi rõ khoá nào đã gửi, để đối soát khi cần.

7. Ví dụ theo ngôn ngữ

cURL

curl -X POST https://mail.tamiload.com/api/v1/send \
  -H "Authorization: Bearer $MT_MAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "donhang@dermatreatment.com.vn",
    "fromName": "Derma - Đơn hàng",
    "to": "khach@vidu.com",
    "subject": "Đơn hàng #12345 đã được xác nhận",
    "html": "<p>Cảm ơn anh/chị đã đặt hàng.</p>"
  }'

JavaScript / Node.js

const res = await fetch('https://mail.tamiload.com/api/v1/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.MT_MAIL_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'donhang@dermatreatment.com.vn',
    fromName: 'Derma - Đơn hàng',
    to: 'khach@vidu.com',
    subject: 'Đơn hàng #12345 đã được xác nhận',
    html: '<p>Cảm ơn anh/chị đã đặt hàng.</p>',
  }),
});
const kq = await res.json();
if (!kq.ok) throw new Error(`${kq.ma}: ${kq.error}`);
console.log('Đã gửi:', kq.messageId);

PHP

$than = json_encode([
  'from'    => 'donhang@dermatreatment.com.vn',
  'to'      => 'khach@vidu.com',
  'subject' => 'Đơn hàng #12345 đã được xác nhận',
  'html'    => '<p>Cảm ơn anh/chị đã đặt hàng.</p>',
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://mail.tamiload.com/api/v1/send');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer ' . getenv('MT_MAIL_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS     => $than,
]);
$kq = json_decode(curl_exec($ch), true);
if (empty($kq['ok'])) throw new Exception($kq['ma'] . ': ' . $kq['error']);

Python

import os, requests

r = requests.post(
    'https://mail.tamiload.com/api/v1/send',
    headers={'Authorization': f"Bearer {os.environ['MT_MAIL_KEY']}"},
    json={
        'from': 'donhang@dermatreatment.com.vn',
        'to': 'khach@vidu.com',
        'subject': 'Đơn hàng #12345 đã được xác nhận',
        'html': '<p>Cảm ơn anh/chị đã đặt hàng.</p>',
    },
    timeout=30,
)
kq = r.json()
if not kq.get('ok'):
    raise RuntimeError(f"{kq['ma']}: {kq['error']}")

Gửi kèm tệp

const fs = require('node:fs');
const tep = fs.readFileSync('don-hang-12345.pdf').toString('base64');

// … trong phần body:
attachments: [
  { filename: 'don-hang-12345.pdf', type: 'application/pdf', content: tep }
]

Hộp thư Minh Trung · quay lại hộp thư