Tài liệu API

Bạn cần thêm tham số api_token=YOUR_API_TOKEN vào url kết nối tới hệ thống Zozo EMA
Ví dụ: https://appv4.zozo.vn/api/v1/lists?api_token=YOUR_API_TOKEN

Authentication

Phương thức API Chức năng

POST /api/v1/login-token Tạo token đăng nhập một lần

Phương thức	API	Chức năng
POST	/api/v1/login-token	Tạo token đăng nhập một lần
	Resp trả về Chuỗi token	Example: `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/login-token \ -d api_token=YOUR_API_TOKEN` Người dùng có thể đăng nhập bằng cách truy cập URL sau: `https://appv4.zozo.vn/login/token/\|token_string\|`

Resp trả về

Chuỗi token

Example:

curl -X POST -H "accept:application/json" -G \
https://appv4.zozo.vn/api/v1/login-token \
-d api_token=YOUR_API_TOKEN

Người dùng có thể đăng nhập bằng cách truy cập URL sau:
https://appv4.zozo.vn/login/token/*|token_string|*

DANH SÁCH

Phương thức	API	Chức năng
POST	/api/v1/lists	Tạo danh sách mới
	Tham số `$name` Tên danh sách `$from_email` Địa chỉ email người gửi mặc định `$from_name` Tên người gửi mặc định `$default_subject không bắt buộc` Tiêu đề email mặc định `divider` Thông tin liên hệ `$contact[company]` Tên công ty `$contact[state]` Bang / Tỉnh / Vùng `$contact[address_1]` Địa chỉ 1 `$contact[address_2]` Địa chỉ 2 `$contact[city]` Thành phố `$contact[zip]` Mã bưu chính `$contact[phone]` Điện thoại `$contact[country_id]` Id quốc gia `$contact[email]` Email `$contact[url] không bắt buộc` Trang chủ `$subscribe_confirmation` Gửi email xác nhận đăng ký (Double Opt-In) `$send_welcome_email` Gửi email chào mừng cuối cùng `$unsubscribe_notification` Gửi thông báo hủy đăng ký tới người đăng ký Resp trả về Kết quả tạo dạng JSON	Example: curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/lists \ -d api_token=YOUR_API_TOKEN \ -d name=List+1 \ -d from_email=admin@abccorp.org \ -d from_name=ABC+Corp. \ -d default_subject=Welcome+to+ABC+Corp. \ -d contact[company]=ABC+Corp. \ -d contact[state]=Armagh \ -d contact[address_1]=14+Tottenham+Court+Road+London+England \ -d contact[address_2]=44-46+Morningside+Road+Edinburgh+Scotland+EH10+4BF \ -d contact[city]=Noname \ -d contact[zip]=80000 \ -d contact[phone]=123+456+889 \ -d contact[country_id]=1 \ -d contact[email]=info@abccorp.org \ -d contact[url]=http://www.abccorp.org \ -d subscribe_confirmation=1 \ -d send_welcome_email=1 \ -d unsubscribe_notification=1
GET	/api/v1/lists	Lấy thông tin tất cả danh sách
	Resp trả về Tất cả danh sách của bạn dạng JSON	Example: `curl -X GET -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/lists \ -d api_token=YOUR_API_TOKEN`
GET	/api/v1/lists/{uid}	Lấy thông tin một danh sách cụ thể
	Resp trả về Thông tin danh sách dạng JSON	Example: `curl -X GET -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/lists/{uid} \ -d api_token=YOUR_API_TOKEN`
POST	/api/v1/lists/{uid}/add-field	Thêm trường tùy chỉnh vào danh sách
	Tham số `$type` Một trong các kiểu: text, number, datetime. `$label` Nhãn của trường `$tag` Tên thẻ; có thể gồm chữ và số, dấu gạch ngang và gạch dưới. `$default_value không bắt buộc` Giá trị mặc định của trường Resp trả về Kết quả tạo dạng JSON	Example: `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/lists/{uid}/add-field \ -d api_token=YOUR_API_TOKEN \ -d type=text \ -d label=Custom \ -d tag=CUSTOM_FIELD_1 \ -d default_value=test`
XÓA	/api/v1/lists/{uid}	Xóa một danh sách
	Tham số `$uid` Uid của danh sách Resp trả về Thông báo kết quả dạng JSON	Example: `curl -X DELETE -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/lists/{uid} \ -d api_token=YOUR_API_TOKEN`

CHIẾN DỊCH

Phương thức	API	Chức năng
GET	/api/v1/campaigns	Lấy thông tin tất cả chiến dịch
	Resp trả về Tất cả chiến dịch của bạn dạng JSON	Example: `curl -X GET -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/campaigns \ -d api_token=YOUR_API_TOKEN`
GET	/api/v1/campaigns/{uid}	Lấy thông tin một chiến dịch cụ thể
	Resp trả về Thông tin chiến dịch dạng JSON	Example: `curl -X GET -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/campaigns/{uid} \ -d api_token=YOUR_API_TOKEN`
POST	/api/v1/campaigns/{uid}/pause	Tạm dừng một chiến dịch
	Resp trả về Kết quả thao tác dạng JSON	Example: `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/campaigns/{uid}/pause \ -d api_token=YOUR_API_TOKEN`
POST	/api/v1/campaigns	Tạo chiến dịch
	Tham số `$name` Tên chiến dịch `$subject` Tiêu đề email `$html` Nội dung email (HTML) `$from_email` Email người gửi `$reply_to` Email nhận phản hồi (reply-to) `$type không bắt buộc - default: regular` Loại chiến dịch, ví dụ: regular `$from_name không bắt buộc` Tên người gửi `$delivery_at không bắt buộc` Thời gian gửi theo lịch (Y-m-d H:i:s) `$default_mail_list_id không bắt buộc` Id danh sách gửi Resp trả về Kết quả tạo dạng JSON	Example: `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/campaigns \ -d api_token=YOUR_API_TOKEN \ -d name=Untitled \ -d subject=Welcome+to+ABC+Corp. \ -d html=Hello+World. \ -d from_email=email@gmail.com \ -d from_name=name \ -d reply_to=email@gmail.com \ -d delivery_at=2020-08-03+16:50:20 \ -d type=regular \ -d default_mail_list_id=1`

LIÊN HỆ

Phương thức	API	Chức năng
GET	/api/v1/subscribers	Liệt kê người đăng ký của một danh sách
	Tham số `$list_uid` Uid của danh sách `$open không bắt buộc - default: all` yes = đã mở một số chiến dịch; no = chưa mở chiến dịch nào `$click không bắt buộc - default: all` yes = đã nhấp một số chiến dịch; no = chưa nhấp chiến dịch nào `$per_page không bắt buộc - default: 25` Số bản ghi mỗi trang `$page` Số trang Resp trả về Tất cả người đăng ký của danh sách dạng JSON	Example: `curl -X GET -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/subscribers \ -d api_token=YOUR_API_TOKEN \ -d list_uid={list_uid} \ -d per_page=20 \ -d page=1`
POST	/api/v1/subscribers	Tạo người đăng ký trong một danh sách
	Tham số `$list_uid` Uid của danh sách `$EMAIL` Email của người đăng ký `$tag không bắt buộc` Thẻ (tag) của người đăng ký, phân tách bằng dấu phẩy (,). `$[OTHER_FIELDS...] không bắt buộc` Các trường khác của người đăng ký, ví dụ FIRST_NAME, LAST_NAME, ... (tùy theo cấu hình trường của danh sách). Resp trả về Kết quả tạo dạng JSON	Example: `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/subscribers \ -d api_token=YOUR_API_TOKEN \ -d list_uid={list_uid} \ -d EMAIL=test@gmail.com \ -d tag=foo,bar,tag+with+space, \ -d FIRST_NAME=Marine \ -d LAST_NAME=Joze`
GET	/api/v1/subscribers/{uid}	Lấy thông tin một người đăng ký cụ thể
	Tham số `$uid` Uid hoặc email của người đăng ký Resp trả về Thông tin người đăng ký dạng JSON	Example: `curl -X GET -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/subscribers/{uid} \ -d api_token=YOUR_API_TOKEN`
PATCH	/api/v1/subscribers/{uid}	Cập nhật người đăng ký trong danh sách
	Tham số `$uid` Uid của người đăng ký `$EMAIL` Email của người đăng ký `$tag không bắt buộc` Thẻ (tag) của người đăng ký, phân tách bằng dấu phẩy (,). `$[OTHER_FIELDS...] không bắt buộc` Các trường khác của người đăng ký, ví dụ FIRST_NAME, LAST_NAME, ... (tùy theo cấu hình trường của danh sách). Resp trả về Kết quả cập nhật dạng JSON	Example: `curl -X PATCH -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/subscribers/{uid} \ -d api_token=YOUR_API_TOKEN \ -d EMAIL=test@gmail.com \ -d tag=foo,bar,tag+with+space, \ -d FIRST_NAME=Marine \ -d LAST_NAME=Joze`
POST	/api/v1/subscribers/{uid}/add-tag	Thêm thẻ (tag) cho người đăng ký
	Tham số `$tag không bắt buộc` Thẻ (tag) của người đăng ký, phân tách bằng dấu phẩy (,). Resp trả về Kết quả tạo dạng JSON	Example: `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/subscribers/{uid}/add-tag \ -d api_token=YOUR_API_TOKEN \ -d tag=foo,bar,tag+with+space`
GET	/api/v1/subscribers/email/{email}	Tìm người đăng ký theo email
	Tham số `$email` Email của người đăng ký Resp trả về Tất cả người đăng ký khớp email	Example: `curl -X GET -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/subscribers/email/{email} \ -d api_token=YOUR_API_TOKEN`
PATCH	/api/v1/subscribers/{uid}/subscribe	Đăng ký (subscribe) một người đăng ký
	Tham số `$list_uid` Uid của danh sách `$uid` Uid của người đăng ký Resp trả về Thông báo kết quả dạng JSON	Example: `curl -X PATCH -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/subscribers/{uid}/subscribe \ -d api_token=YOUR_API_TOKEN`
PATCH	/api/v1/subscribers/{uid}/unsubscribe	Hủy đăng ký (unsubscribe) một người đăng ký
	Tham số `$list_uid` Uid của danh sách `$uid` Uid của người đăng ký Resp trả về Thông báo kết quả dạng JSON	Example: `curl -X PATCH -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/subscribers/{uid}/unsubscribe \ -d api_token=YOUR_API_TOKEN`
XÓA	/api/v1/subscribers/{uid}	Xóa một người đăng ký
	Tham số `$list_uid` Uid của danh sách `$uid` Uid của người đăng ký Resp trả về Thông báo kết quả dạng JSON	Example: `curl -X DELETE -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/subscribers/{uid}?list_uid={list_uid} \ -d api_token=YOUR_API_TOKEN`

EMAIL

Phương thức API Chức năng

POST /api/v1/email/send Gửi một email đơn

Phương thức	API	Chức năng
POST	/api/v1/email/send	Gửi một email đơn
	Tham số `$subject` Tiêu đề email `$from_email` Email người gửi `$from_name` Tên người gửi `$to` Email người nhận. Nhiều địa chỉ phân tách bằng dấu phẩy; địa chỉ thứ hai trở thành CC. `$reply_to không bắt buộc` Email nhận phản hồi. Mặc định bằng from_email nếu bỏ trống. `$html không bắt buộc` Nội dung email (HTML) `$plain không bắt buộc` Nội dung email (văn bản thuần) `$cc không bắt buộc` Địa chỉ email CC `$attachments không bắt buộc` Mảng JSON tệp đính kèm: [{"name":"file.pdf","content":"{base64}"}] `$params không bắt buộc` Đối tượng JSON chứa giá trị thay thế (merge) chèn vào nội dung email `$enable_tracking không bắt buộc - default: false` Bật theo dõi mở/nhấp (true/false) Resp trả về Kết quả tạo dạng JSON	Example: curl -X POST -H "accept:application/json" \ https://appv4.zozo.vn/api/v1/email/send \ -d api_token=YOUR_API_TOKEN \ -d subject='Hello World. Email sent from Zozo EMA API' \ -d from_email='contact@yourdomain.com' \ -d from_name='John Doe' \ -d to='recipient@gmail.com' \ -d reply_to='noreply@yourdomain.com' \ -d cc='recipient-cc@gmail.com' \ -d html='Hello World.' \ -d plain='Hello World.' \ -d attachments='[{"name":"filename.pdf","content":"{base64content}"}]' \ -d params='{"customerName":"Nguyen Van A","customerEmail":"recipient@gmail.com"}'

Tham số

$subject: Tiêu đề email
$from_email: Email người gửi
$from_name: Tên người gửi
$to: Email người nhận. Nhiều địa chỉ phân tách bằng dấu phẩy; địa chỉ thứ hai trở thành CC.
$reply_to không bắt buộc: Email nhận phản hồi. Mặc định bằng from_email nếu bỏ trống.
$html không bắt buộc: Nội dung email (HTML)
$plain không bắt buộc: Nội dung email (văn bản thuần)
$cc không bắt buộc: Địa chỉ email CC
$attachments không bắt buộc: Mảng JSON tệp đính kèm: [{"name":"file.pdf","content":"{base64}"}]
$params không bắt buộc: Đối tượng JSON chứa giá trị thay thế (merge) chèn vào nội dung email
$enable_tracking không bắt buộc - default: false: Bật theo dõi mở/nhấp (true/false)

Resp trả về

Kết quả tạo dạng JSON

Example:

curl -X POST -H "accept:application/json" \
https://appv4.zozo.vn/api/v1/email/send \
-d api_token=YOUR_API_TOKEN \
-d subject='Hello World. Email sent from Zozo EMA API' \
-d from_email='contact@yourdomain.com' \
-d from_name='John Doe' \
-d to='recipient@gmail.com' \
-d reply_to='noreply@yourdomain.com' \
-d cc='recipient-cc@gmail.com' \
-d html='Hello World.' \
-d plain='Hello World.' \
-d attachments='[{"name":"filename.pdf","content":"{base64content}"}]' \
-d params='{"customerName":"Nguyen Van A","customerEmail":"recipient@gmail.com"}'

Thông báo

Phương thức API Chức năng

POST /api/v1/notification Gửi báo cáo phân phối hoặc lạm dụng tới Zozo EMA (thành công / trả lại / phản hồi / lạm dụng)

Phương thức	API	Chức năng
POST	/api/v1/notification	Gửi báo cáo phân phối hoặc lạm dụng tới Zozo EMA (thành công / trả lại / phản hồi / lạm dụng)
	Tham số `$message_id` Id của thông điệp `$type` Một trong: sent \| bounced \| reported \| failed `$bounce_type` Bắt buộc nếu type là bounced `$report_type` Bắt buộc nếu type là reported `$description` Nội dung thông báo Resp trả về Kết quả thao tác dạng JSON	Example: `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/notification \ -d api_token=YOUR_API_TOKEN \ -d type=sent` `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/notification \ -d api_token=YOUR_API_TOKEN \ -d type=bounced \ -d bounce_type=hard \ -d description=Email+address+does+not+exist` `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/notification \ -d api_token=YOUR_API_TOKEN \ -d type=abuse \ -d report_type=hard \ -d description=Email+address+does+not+exist` `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/notification \ -d api_token=YOUR_API_TOKEN \ -d type=spam \ -d report_type=hard \ -d description=Email+address+does+not+exist` `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/notification \ -d api_token=YOUR_API_TOKEN \ -d type=failed \ -d description=Email+address+does+not+exist`

Tham số

$message_id: Id của thông điệp
$type: Một trong: sent | bounced | reported | failed
$bounce_type: Bắt buộc nếu type là bounced
$report_type: Bắt buộc nếu type là reported
$description: Nội dung thông báo

Resp trả về

Kết quả thao tác dạng JSON

Example:

curl -X POST -H "accept:application/json" -G \
https://appv4.zozo.vn/api/v1/notification \
-d api_token=YOUR_API_TOKEN  \
-d type=sent

curl -X POST -H "accept:application/json" -G \
https://appv4.zozo.vn/api/v1/notification \
-d api_token=YOUR_API_TOKEN  \
-d type=bounced \
-d bounce_type=hard \
-d description=Email+address+does+not+exist

curl -X POST -H "accept:application/json" -G \
https://appv4.zozo.vn/api/v1/notification \
-d api_token=YOUR_API_TOKEN  \
-d type=abuse \
-d report_type=hard \
-d description=Email+address+does+not+exist

curl -X POST -H "accept:application/json" -G \
https://appv4.zozo.vn/api/v1/notification \
-d api_token=YOUR_API_TOKEN  \
-d type=spam \
-d report_type=hard \
-d description=Email+address+does+not+exist

curl -X POST -H "accept:application/json" -G \
https://appv4.zozo.vn/api/v1/notification \
-d api_token=YOUR_API_TOKEN  \
-d type=failed \
-d description=Email+address+does+not+exist

TỆP TIN

Phương thức API Chức năng

POST /api/v1/file/upload Tải tệp lên kho lưu trữ của khách hàng

Phương thức	API	Chức năng
POST	/api/v1/file/upload	Tải tệp lên kho lưu trữ của khách hàng
	Tham số `$files` Mảng JSON các tệp cần tải, mỗi phần tử: {"url":"...","subdirectory":"..."}. subdirectory không bắt buộc (mặc định là thư mục gốc của người dùng). Resp trả về Thông báo kết quả tải lên	Example: `curl -X POST -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/file/upload \ -d api_token=YOUR_API_TOKEN \ -d files='[{"url":"http://demo.ema.zozo.vn/images/logo_big.png","subdirectory":"path/to/file"},{"url":"http://demo.ema.zozo.vn/images/logo_big.svg","subdirectory":"path/to/file2"}]'`

Tham số

$files: Mảng JSON các tệp cần tải, mỗi phần tử: {"url":"...","subdirectory":"..."}. subdirectory không bắt buộc (mặc định là thư mục gốc của người dùng).

Resp trả về

Thông báo kết quả tải lên

Example:

curl -X POST -H "accept:application/json" -G \
https://appv4.zozo.vn/api/v1/file/upload \
-d api_token=YOUR_API_TOKEN  \
-d files='[{"url":"http://demo.ema.zozo.vn/images/logo_big.png","subdirectory":"path/to/file"},{"url":"http://demo.ema.zozo.vn/images/logo_big.svg","subdirectory":"path/to/file2"}]'

Delivery logs

Phương thức API Chức năng

GET /api/v1/deliver-logs Liệt kê nhật ký phân phối và các nhật ký liên quan

Phương thức	API	Chức năng
GET	/api/v1/deliver-logs	Liệt kê nhật ký phân phối và các nhật ký liên quan
	Tham số `$per_page không bắt buộc` Số bản ghi mỗi trang `$off_set không bắt buộc` Vị trí bắt đầu (số bản ghi bỏ qua) `$log_type không bắt buộc` Loại nhật ký: tracking_log, open_log, click_log, feedback_log hoặc unsubscribe_log Resp trả về Kết quả nhật ký dạng JSON	Example: `curl -X GET -H "accept:application/json" -G \ https://appv4.zozo.vn/api/v1/deliver-logs \ -d api_token=YOUR_API_TOKEN`

Tham số

$per_page không bắt buộc: Số bản ghi mỗi trang
$off_set không bắt buộc: Vị trí bắt đầu (số bản ghi bỏ qua)
$log_type không bắt buộc: Loại nhật ký: tracking_log, open_log, click_log, feedback_log hoặc unsubscribe_log

Resp trả về

Kết quả nhật ký dạng JSON

Example:

curl -X GET -H "accept:application/json" -G \
                    https://appv4.zozo.vn/api/v1/deliver-logs \
                    -d api_token=YOUR_API_TOKEN