godpod/sendgrid

此库允许您使用PHP快速轻松地通过SendGrid发送电子邮件或进行API调用。

维护者

详细信息

github.com/godpod/sendgrid-php

主页

源代码

安装量: 3,802

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 3

分支: 624

2.2.0.1 2015-01-19 11:12 UTC

Requires

Requires (Dev)

Replaces

  • godpod/sendgrid-php: *

MIT be221d7501ad1b0faae210229f2f070c853afc45

emailsendgridsendgrid

This package is not auto-updated.

Last update: 2024-09-28 16:03:56 UTC

README

此库允许您使用PHP通过SendGrid快速轻松地发送电子邮件。

警告：此模块最近从1.1.7升级到2.X。一些方法名称发生了API破坏性更改。有关最新的方法名称，请参阅使用方法。

重要：此库需要PHP 5.3或更高版本。

BuildStatus Latest Stable Version

$sendgrid = new SendGrid('username', 'password');
$email    = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       setFrom('me@bar.com')->
       setSubject('Subject goes here')->
       setText('Hello World!')->
       setHtml('<strong>Hello World!</strong>');

$sendgrid->send($email);

安装

将SendGrid添加到您的composer.json文件。如果您没有使用Composer，您应该使用。这是管理PHP应用程序依赖项的绝佳方式。

{  
  "require": {
    "godpod/sendgrid": "2.2.0.1"
  }
}

然后在您的PHP脚本顶部包含自动加载器

require 'vendor/autoload.php';

替代方案：从zip文件安装

如果您没有使用Composer，只需下载并安装库的最新打包版本作为zip文件。

⬇︎ 下载打包库 ⬇︎

然后从包中包含库

require("path/to/sendgrid-php/sendgrid-php.php");

库的先前版本可以在版本索引中找到。

示例应用程序

有一个sendgrid-php-example应用程序，可以帮助您快速启动开发。

使用方法

要开始使用此库，请使用您的SendGrid凭据初始化SendGrid对象。

$sendgrid = new SendGrid('username', 'password');

创建一个新的SendGrid电子邮件对象并添加您的消息详细信息。

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       addTo('bar@foo.com')->
       setFrom('me@bar.com')->
       setSubject('Subject goes here')->
       setText('Hello World!')->
       setHtml('<strong>Hello World!</strong>');

发送它。

$sendgrid->send($email);

addTo

您可以使用addTo添加一个或多个收件人地址。

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       addTo('another@another.com');
$sendgrid->send($email);

setTos

如果您更喜欢，您可以使用setTos方法将多个收件人地址作为一个数组添加。这将取消设置之前附加的任何addTo。

$email   = new SendGrid\Email();
$emails = array("foo@bar.com", "another@another.com", "other@other.com");
$email->setTos($emails);
$sendgrid->send($email);

setFrom

$email   = new SendGrid\Email();
$email->setFrom('foo@bar.com');
$sendgrid->send($email);

setFromName

$email   = new SendGrid\Email();
$email->setFrom('foo@bar.com');
$email->setFromName('Foo Bar');
$email->setFrom('other@example.com');
$email->setFromName('Other Guy');
$sendgrid->send($email);

setReplyTo

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       setReplyTo('someone.else@example.com')->
       setFromName('John Doe')->
       ...

Cc

addCc

$email   = new SendGrid\Email();
$email->addCc('foo@bar.com');
$sendgrid->send($email);

setCc

$email   = new SendGrid\Email();
$email->setCc('foo@bar.com');
$sendgrid->send($email);

setCcs

$email   = new SendGrid\Email();
$emails = array("foo@bar.com", "another@another.com", "other@other.com");
$email->setCcs($emails);
$sendgrid->send($email);

removeCc

$email->removeCc('foo@bar.com');

Bcc

使用多个addTo作为优于setBcc的替代方案。

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       addTo('someotheraddress@bar.com')->
       addTo('another@another.com')->
       ...

但如果您仍然需要Bcc，可以这样做

addBcc

$email   = new SendGrid\Email();
$email->addBcc('foo@bar.com');
$sendgrid->send($email);

setBcc

$email   = new SendGrid\Email();
$email->setBcc('foo@bar.com');
$sendgrid->send($email);

setBccs

$email   = new SendGrid\Email();
$emails = array("foo@bar.com", "another@another.com", "other@other.com");
$email->setBccs($emails);
$sendgrid->send($email);

removeBcc

$email->removeBcc('foo@bar.com');

setSubject

$email   = new SendGrid\Email();
$email->setSubject('This is a subject');
$sendgrid->send($email);

setText

$email   = new SendGrid\Email();
$email->setText('This is some text');
$sendgrid->send($email);

setHtml

$email   = new SendGrid\Email();
$email->setHtml('<h1>This is an html email</h1>');
$sendgrid->send($email);

setDate

$email   = new SendGrid\Email();
$email->setDate('Wed, 17 Dec 2014 19:21:16 +0000');
$sendgrid->send($email);

setSendAt

$email   = new SendGrid\Email();
$email->setSendAt(1409348513);
$sendgrid->send($email);

setSendEachAt

$email   = new SendGrid\Email();
$email->setSendEachAt(array(1409348513, 1409348514, 1409348515));
$sendgrid->send($email);

addSendEachAt

$email   = new SendGrid\Email();
$email->addSendEachAt(1409348513);
$email->addSendEachAt(1409348514);
$email->addSendEachAt(1409348515);
$sendgrid->send($email);

类别

类别用于对SendGrid提供的电子邮件统计信息进行分组。

要使用类别，只需设置类别名称。注意：每封电子邮件最多可以有10个类别。

addCategory

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       addCategory("Category 1")->
       addCategory("Category 2");

setCategory

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       setCategory("Category 1");

setCategories

$email = new SendGrid\Email();
$categories = array("Category 1", "Category 2", "Category 3");
$email->setCategories($categories);

removeCategory

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       removeCategory("Category 1");

附件

附件目前仅基于文件，未来还计划实现内存中实现。

文件附件限制为每文件7 MB。

addAttachment

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       addAttachment("../path/to/file.txt");

setAttachment

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       setAttachment("../path/to/file.txt");

setAttachments

$email = new SendGrid\Email();
$attachments = array("../path/to/file1.txt", "../path/to/file2.txt");
$email->addTo('foo@bar.com')->
       ...
       setAttachments($attachments);

removeAttachment

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       addAttachment("../path/to/file.txt");
$email->removeAttachment("../path/to/file.txt");

您可以为用作内联HTML内容的文件添加标记。它将使用指定的"cid"标记文件为内联处理。

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')
      ->setHtml('<div>Our logo:<img src="cid:file-cid"></div>')
      ->addAttachment("../path/to/file.txt", "super_file.txt", "file-cid");

重要注意：setBcc不支持附件。这是设计决定的。相反，请使用多个addTo。每个用户都会收到自己的个性化电子邮件，并只看到自己的电子邮件。

标准的setBcc将隐藏电子邮件的接收者。如果您使用多个addTo，每个用户都将收到一个个性化的电子邮件，只显示*仅他们的电子邮件。这更加友好和个性化。此外，使用多个addTo是个好主意，因为setBcc不支持附件。这是设计上的。

所以请记住，当想到“Bcc”时，请使用多个addTo。

替换

替换可以用来定制多收件人电子邮件，并为用户量身定制。

addSubstitution

$email = new SendGrid\Email();
$email->addTo('john@somewhere.com')->
       addTo('harry@somewhere.com')->
       addTo('Bob@somewhere.com')->
       ...
       setHtml('Hey %name%, we've seen that you've been gone for a while')->
       addSubstitution('%name%', array('John', 'Harry', 'Bob'));

替换也可以用来定制多收件人主题。

$email = new SendGrid\Email();
$email->addTos(array('john@somewhere.com', 'harry@somewhere.com', 'bob@somewhere.com'))
    ->setSubject('%subject%')
    ->addSubstitution('%subject%', array('Subject to John', 'Subject to Harry', 'Subject to Bob'))
    ...;

setSubstitutions

$email = new SendGrid\Email();
$email->addTos(array('john@somewhere.com', 'harry@somewhere.com', 'bob@somewhere.com'))
    ->setSubject('%subject%')
    ->setSubstitutions(array('%name%' => array('John', 'Harry', 'Bob') , '%subject%' => array('Subject to John', 'Subject to Harry', 'Subject to Bob')))
    ...;

部分

部分可以用来进一步为最终用户定制消息。部分只有在与替换值一起使用时才有用。

addSection

$email = new SendGrid\Email();
$email->addTo('john@somewhere.com')->
       addTo("harry@somewhere.com")->
       addTo("Bob@somewhere.com")->
       ...
       setHtml("Hey %name%, you work at %place%")->
       addSubstitution("%name%", array("John", "Harry", "Bob"))->
       addSubstitution("%place%", array("%office%", "%office%", "%home%"))->
       addSection("%office%", "an office")->
       addSection("%home%", "your house");

setSections

$email = new SendGrid\Email();
$email->addTo('john@somewhere.com')->
       addTo("harry@somewhere.com")->
       addTo("Bob@somewhere.com")->
       ...
       setHtml("Hey %name%, you work at %place%")->
       addSubstitution("%name%", array("John", "Harry", "Bob"))->
       addSubstitution("%place%", array("%office%", "%office%", "%home%"))->
       setSections(array("%office%" => "an office", "%home%" => "your house"));

唯一参数

唯一参数用于跟踪目的

addUniqueArg / addUniqueArgument

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       addUniqueArg("Customer", "Someone")->
       addUniqueArg("location", "Somewhere")->

setUniqueArgs / setUniqueArguments

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       setUniqueArgs(array('cow' => 'chicken'));

过滤器设置

过滤器设置用于启用和禁用应用程序，并将参数传递给这些应用程序。

addFilter / addFilterSetting

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       addFilter("gravatar", "enable", 1)->
       addFilter("footer", "enable", 1)->
       addFilter("footer", "text/plain", "Here is a plain text footer")->
       addFilter("footer", "text/html", "<p style='color:red;'>Here is an HTML footer</p>");

setFilters / setFilterSettings

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       setFilters(array("gravatar" => array("settings" => array("enable" => 1))))

标题

您可以根据需要添加标准的电子邮件消息标题。

addHeader

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       addHeader('X-Sent-Using', 'SendGrid-API')->
       addHeader('X-Transport', 'web');

setHeaders

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       setHeaders(array('X-Sent-Using' => 'SendGrid-API', 'X-Transport' => 'web'));

removeHeader

$email = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       ...
       addHeader('X-Sent-Using', 'SendGrid-API')->
       addHeader('X-Transport', 'web');
$email->removeHeader('X-Transport');

选项

选项可以在初始化SendGrid对象时传递给库。

$options = array(
  'turn_off_ssl_verification' => false,
  'protocol' => 'https',
  'host' => 'api.sendgrid.com',
  'endpoint' => '/api/mail.send.json',
  'port' => null,
  'url' => null
);
$sendgrid = new SendGrid('username', 'password', $options);

更改URL

您可以通过向options提供各种参数来更改sendgrid-php用于发送电子邮件的URL，所有参数都是可选的。

$sendgrid = new SendGrid('username', 'password', array( 'protocol' => 'http', 'host' => 'sendgrid.org', 'endpoint' => '/send', 'port' => '80' ));

也可以提供完整的URL。

$sendgrid = new SendGrid('username', 'password', array( 'url' => 'http://sendgrid.org:80/send'));

忽略SSL证书验证

您可以选择在使用Web API时忽略SSL证书验证。

$sendgrid   = new SendGrid(SENDGRID_USERNAME, SENDGRID_PASSWORD,  array("turn_off_ssl_verification" => true));

一次性发送成千上万封电子邮件

有时您可能希望在单个请求中发送成千上万封电子邮件。您可以这样做。建议您将每个批次分成1000个增量。所以如果您需要发送给5000封电子邮件，那么您将将其分成每次1000封的循环。

$sendgrid   = new SendGrid(SENDGRID_USERNAME, SENDGRID_PASSWORD);
$email       = new SendGrid\Email();

$recipients = array("alpha@mailinator.com", "beta@mailinator.com", "zeta@mailinator.com");
$names      = array("Alpha", "Beta", "Zeta");

$email->setFrom("from@mailinator.com")->
        setSubject('[sendgrid-php-batch-email]')->
        setTos($recipients)->
        addSubstitution("%name%", $names)->
        setText("Hey %name, we have an email for you")->
        setHtml("<h1>Hey %name%, we have an email for you</h1>");

$result = $sendgrid->send($email);

贡献

  1. 分叉它
  2. 创建您的功能分支（git checkout -b my-new-feature）
  3. 提交您的更改（git commit -am 'Added some feature'）
  4. 将更改推送到分支（git push origin my-new-feature）
  5. 创建新的Pull Request

运行测试

可以使用以下命令使用PHPUnit运行test目录中现有的测试：[PHPUnit](https://github.com/sebastianbergmann/phpunit/)

composer update --dev
cd test
../vendor/bin/phpunit
```

or if you already have PHPUnit installed globally.

```bash
cd test
phpunit
```

## Releasing

To release a new version of this library, update the version in all locations, tag the version, and then push the tag up. Packagist.org takes care of the rest.

#### Testing uploading to Amazon S3

If you want to test uploading the zipped file to Amazon S3 (SendGrid employees only), do the following.

```
export S3_SIGNATURE="secret_signature"
export S3_POLICY="secret_policy"
export S3_BUCKET="sendgrid-open-source"
export S3_ACCESS_KEY="secret_access_key"
./scripts/s3upload.sh
```