README

通用的 Zoho ZeptoMail 服务 PHP API 客户端

此非官方的 ZeptoMail/Transmail PHP 库允许您通过 Zoho ZeptoMail API 简单地发送事务性邮件消息。

ZeptoMail 系统旨在处理与网站和应用程序交互相关的事务性邮件（收据、密码重置、双因素认证通知等），而不是像新闻通讯和公告这样的大量发送邮件。请参阅 ZeptoMail 网站了解使用案例和指南的详细信息。

开发者注意

当此服务被称为 Transmail 时，创建了此库。除了 Zoho 文档上的名称和新的 API 端点外，API 与之前相同，截至 2021 年 8 月，即使与旧的 Transmail 端点一起使用，它仍然有效。在未来的某个时刻，我计划更新此库以反映新的品牌。在此之前，它将继续使用并作为 "transmail" 命名空间使用。

安装

对于大多数用途，我们建议通过 Composer 安装 desttools/transmail 包。如果您已经安装了 Composer，可以使用以下命令添加最新版本的包

composer require desttools/transmail

或者，如果您正在将此库添加到应用程序中，在您的 composer.json 文件中

"require": {
	"desttools/transmail": "dev-master"
},

或者，您可以直接克隆此存储库，并将其源代码包含到您的项目中。

设置

在您连接到 API 之前，您需要从 ZeptoMail 账户获取两个设置：一个 授权密钥 和一个 弹跳地址

如果您正在使用环境文件，您将想要使用以下设置创建设置

transmailkey = "MyAPIkeyfromZeptoMail"
transbounceaddr = "bounce@bounce.mydomain.com"

如果您在应用程序中未使用环境变量，您可以省略此步骤，并直接将这些设置传递给邮件发送器（请参阅下面的完整示例）。

要加载页面或应用程序中的库，您需要包含以下文件

// doing your own loading:
include_once ("./transmail/TransmailClient.php");

// or if using composer autoloading: 
include_once ('./vendor/autoload.php');

注意：您发送消息的能力还要求发送者的域名在您的 ZeptoMail 仪表板中进行预先验证。如果没有，您将看到身份验证错误。

基本邮件示例

//create a new message object
$msg = new \stdClass();

//required settings
$msg->subject = "My message subject"; //SUBJECT
$msg->textbody = "My text-only message"; //TEXT MSG, NULL IF sending HTML
$msg->htmlbody = "<p>My HTML-formatted message</p>"; //HTML MSG, NULL if sending TEXT
$msg->to = array('joe@customer.com','Joe Customer'); //TO
$msg->from = array('support@site.com','XYZ Company'); //FROM

//instantiate library and pass info
$tmail = new \Transmail\TransmailClient($msg);

//send the message
$response = $tmail->send();

if ($response)
{
// success
} 
else 
{
// failure
}

注意：您可以将所有电子邮件地址作为字符串或数组传递，如下所示

$msg->to = 'joe@customer.com'; 
//or
$msg->to = array('joe@customer.com','Joe Customer');

如果使用数组，格式化程序将在第一个或第二个元素位置中查找电子邮件地址。如果找到地址，它将使用剩余的元素作为文本名称。如果传递了额外的元素，则将忽略它们。

完整示例

以下是所有可能的选项，包括手动设置授权密钥和弹跳地址

	//create a new message object
	$msg = new \stdClass();
	
	//required settings
	$msg->subject = "My message subject"; //SUBJECT
	$msg->textbody = "My text-only message"; //TEXT MSG, NULL IF sending HTML
	$msg->htmlbody = "<p>My HTML-formatted message</p>"; //HTML MSG, NULL if sending TEXT
	$msg->to = array('joe@customer.com','Joe Customer'); //TO
	$msg->from = array('support@site.com','XYZ Company'); //FROM
	
	//optional settings
	$msg->reply_to = array('address@site.com','XYZ Company'); //REPLY TO
	$msg->cc = array('address2@site.com','Someone'); //CC
	$msg->bcc = array('address3@site.com','Somebody Else'); //BCC
	$msg->track_clicks = TRUE; //TRACK CLICKS, TRUE by default
	$msg->track_opens = TRUE; //TRACK OPENS, TRUE by default
	$msg->client_reference = NULL; //CLIENT ID (string)
	$msg->mime_headers = NULL; //ADDITIONAL MIME HEADERS (array)
	$msg->attachments = NULL; //ATTACHMENTS (array)
	$msg->inline_images = NULL; //INLINE IMAGES (array)
	
	//instantiate library and pass all possible settings
	$tmail = new \Transmail\TransmailClient($msg, "myapikey", "mybounce@address.com", TRUE);
	
	//send the message
	$response = $tmail->send();
			
	if ($response)
	{
		// success
	} 
	else 
	{
		// failure
	}

错误处理

当您实际加载库时，可以传递第四个参数来打开详细的错误报告。默认情况下，这是关闭的，函数返回 TRUE（消息发送）和 FALSE（消息未发送）。

可能发生失败的两个主要点是：cURL 请求可能失败，或 API 请求可能失败。在这两种情况下，除非您打开了详细的错误报告，否则函数将返回通用的 FALSE。

打开详细错误报告

在发生cURL错误时，将返回一个包含特定PHP错误码的字符串。

在API成功或失败的情况下，将返回一个包含整个API响应的JSON对象。有关错误码和其他详细信息，请参阅ZeptoMail文档。

ZeptoMail API错误码

安全提示：这些详细的错误信息可能会泄露您网站或ZeptoMail账户的敏感信息，因此在生产环境中应捕获错误或将其关闭。.

附加头信息

向邮件服务器传递附加头信息是可能的。只需创建所需的任何名称-值对作为数组，并将其传递给函数即可。

$headers = array();

$headers[] = array( "CustId"   => "1234",
		    "CustName" => "Bob Smith" );

发送附件

发送附件意味着将文件加载到PHP的内存中，将其转换为Base64编码的流，然后将该流传递给函数。由于ZeptoMail需要三个参数，通常建议首先将附件设置为数组，然后将该数组传递给函数。

$attachments = array();

$file = "filename.jpg";
$path = "/path/to/" . $file;
$filedata = file_get_contents($path);

if ($filedata) 
{

$base64 = base64_encode($filedata);

$attachments[] = array( "content"   => $base64,
			"mime_type" => mime_content_type($path),
			"name"      => $file );

}

不支持的附件列表

Zoho ZeptoMail API文档

注意：此库仅通过ZeptoMail API系统发送消息。如果您尝试通过SMTP发送，请参阅您网站或电子邮件服务器邮件程序的SMTP中继文档。

desttools / transmail

维护者

详情