README

Thư viện PHP (namespace Open\Ses) gửi email qua Open SES / AWS SES bằng AWS SDK for PHP, kèm các ví dụ trong examples/.

Cài đặt qua Composer

Package có trên Packagist:

composer require cuongcds/open-ses-php

Dùng trong code (autoload của Composer nạp Open\Ses\* và aws/aws-sdk-php):

require __DIR__ . '/vendor/autoload.php';

use Open\Ses\SesMailer;

$mailer = new SesMailer(
    region: 'us-east-1',
    accessKeyId: '...',
    secretAccessKey: '...',
    senderEmail: 'no-reply@example.com',
    endpoint: 'https://open-ses.domain.com/ses',
);
$messageId = $mailer->send(['to@example.com'], 'Subject', '<p>Hello</p>', 'Hello');

Chạy các ví dụ (khi clone repo)

composer install
cp .env.example .env

Điền các giá trị trong .env:

AWS_REGION: region đã verify domain/email trên SES (ví dụ ap-southeast-1).
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY: IAM user/role có quyền ses:SendEmail, ses:SendRawEmail.
SES_SENDER_EMAIL: địa chỉ đã verify trên SES (hoặc thuộc domain đã verify).
SES_CONFIGURATION_SET: tên configuration set nếu cần theo dõi mở/click (không bắt buộc).
AWS_SES_ENDPOINT: override host gọi API SES (không bắt buộc). Mặc định trong .env.example là endpoint chuẩn của AWS theo region (https://email.ap-southeast-1.amazonaws.com) — đổi region cho khớp AWS_REGION, hoặc thay bằng VPC endpoint/mock server riêng (ví dụ LocalStack: https://localhost:4566). Bỏ trống để SDK tự chọn endpoint theo AWS_REGION.

Chạy ví dụ

Gửi email HTML/text đơn giản (SES SendEmail):

php examples/send-simple.php

Gửi email kèm file đính kèm (SES SendRawEmail, MIME thủ công):

php examples/send-with-attachment.php

Tích hợp CodeIgniter 3.1.13

examples/codeigniter/application/libraries/MY_Email.php mở rộng CI_Email (theo cơ chế MY_ prefix của CI3), nên code ứng dụng vẫn dùng $this->load->library('email') như bình thường. Transport được chọn bằng config driver trong config/email.php: smtp | gmail | ses. Cách dựng MIME, attachment, alt message, validate... vẫn do CI_Email xử lý; riêng ses thay phần gửi bằng SesAdapter (SendRawEmail).

Cài thư viện bằng composer require cuongcds/open-ses-php (xem "Cài đặt qua Composer"), rồi bật $config['composer_autoload'] = TRUE; trong application/config/config.php (chỉ cần cho driver ses).
Copy application/libraries/MY_Email.php và application/config/email.php vào project CI.
Đặt biến môi trường theo driver (hoặc sửa thẳng config/email.php):
- smtp: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_CRYPTO.
- gmail: GMAIL_USER, GMAIL_APP_PASSWORD (cần bật 2FA và tạo App Password; From phải là chính tài khoản hoặc alias đã verify).
- ses: AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SES_ENDPOINT (Open SES), SES_CONFIGURATION_SET.
Chọn driver: đổi MAIL_DRIVER (hoặc $config['driver']), hoặc đổi lúc chạy bằng $this->email->use_driver('ses').

$this->load->library('email');
$this->email->from('sender@example.com', 'Sender')
    ->to('a@example.com')->subject('Hi')->message('<p>Hello</p>')->send();

Thêm dịch vụ SMTP khác: thêm 1 profile vào $config['drivers'] với protocol => 'smtp' + các khoá smtp_*. Xem application/controllers/Mail_demo.php. Sau send() với driver ses, MessageId nằm ở $this->email->message_id.

Cấu trúc

src/MailAdapterInterface.php, src/SesAdapter.php: transport SES (SendRawEmail) dùng cho driver ses của MY_Email, tạo bằng SesAdapter::fromConfig(...) hoặc truyền sẵn SesClient.
src/SesMailer.php: gửi email không kèm attachment qua API SendEmail.
src/SesRawMailer.php: dựng MIME multipart thủ công để gửi kèm attachment qua API SendRawEmail.
examples/send-simple.php, examples/send-with-attachment.php: script minh hoạ cách dùng.

Lưu ý

Nếu SES account đang ở sandbox mode, cả người gửi và người nhận đều phải được verify trước khi gửi được.
Không commit file .env chứa credentials thật.

Khác biệt so với AWS SES thật

Ví dụ này dùng nguyên AWS SDK for PHP (aws/aws-sdk-php) — code gọi API không đổi giữa AWS SES thật và Open SES, chỉ đổi cấu hình trong .env. Một số điểm khác cần lưu ý khi trỏ vào Open SES thay vì AWS:

	AWS SES thật	Open SES
`AWS_SES_ENDPOINT`	Bỏ trống, hoặc endpoint AWS theo region (`email.<region>.amazonaws.com`)	Bắt buộc set, dạng `https://<domain>/ses` (ví dụ `https://open-ses.domain.com/ses` — thay `domain.com` bằng domain thật của Open SES) — route API nằm ở `/ses`, không phải `/`, do giới hạn kiến trúc của server nền
`AWS_REGION`	Phải khớp region đã verify identity trên AWS	Chuỗi tuỳ ý (ví dụ `us-east-1`) — chỉ dùng để tính chữ ký SigV4, server không kiểm tra region thật
API hỗ trợ	SES v1 (Query API) + SES v2 (JSON API)	Chỉ SES v1 Query API — 3 action `SendEmail`, `SendRawEmail`, `SendBulkTemplatedEmail`
Access Key / Secret Key	Cấp qua IAM	Cấp theo từng App trong Open SES console (mỗi App có Access Key/Secret Key + quota/rate-limit riêng)
Xác thực sender domain	Verify qua AWS Console (DNS TXT/CNAME)	Verify DKIM qua Open SES console (`App > Domains`) — có thể tắt bắt buộc verify domain cho từng App (chỉ nên dùng khi dev/test, không nên bật ở production)
TLS certificate	Chứng chỉ CA hợp lệ	`src/SesMailer.php`/`SesRawMailer.php` tự bỏ qua verify TLS khi có `endpoint` custom (dùng cho domain dev/nội bộ với cert self-signed) — khi không set `endpoint` (trỏ thẳng AWS thật), TLS verify vẫn bật bình thường
Sandbox mode	Có (giới hạn gửi tới địa chỉ chưa verify)	Không có khái niệm sandbox — chỉ giới hạn qua domain verification (nếu bật) và quota/rate-limit theo App
`ConfigurationSetName` (tracking mở/click)	Hỗ trợ	Chưa hỗ trợ ở phiên bản hiện tại — tham số bị bỏ qua nếu gửi

cuongcds / open-ses-php

Package info

Security

Statistics