mailjet/mailjet-apiv3-php

Mailjet API 的 PHP 封装

维护者

详细信息

github.com/mailjet/mailjet-apiv3-php

主页

源代码

问题

安装次数: 7,733,184

依赖: 98

建议者: 6

安全: 0

星标: 263

关注者: 28

分支: 86

开放问题: 4

v1.6.3 2023-12-10 11:13 UTC

Requires

Requires (Dev)

MIT b10ac28c0c201bfd834e28a5a2c13f89d283aaa1

phpapiemailv3Mailjet

This package is auto-updated.

Last update: 2024-09-20 04:04:55 UTC

README

alt text

官方 Mailjet PHP 封装

Build Status MIT License Current Version

概述

该仓库包含 Mailjet API 的官方 PHP 封装。

查看官方文档中的所有资源和 PHP 代码示例，链接：官方文档。

目录

兼容性

此库需要 PHP v8.1 或更高版本。

安装

使用以下代码安装封装器

composer require mailjet/mailjet-apiv3-php

如果您不使用 Composer，可以克隆或下载 此仓库，它已经包含所有依赖项和 vendor/autoload.php 文件。如果遇到问题，请在此处发布，而不是在镜像仓库中。

身份验证

Mailjet 电子邮件 API 使用您的 API 和 Secret 密钥进行身份验证。 获取 并保存您的 Mailjet API 凭证。

export MJ_APIKEY_PUBLIC='your API key'
export MJ_APIKEY_PRIVATE='your API secret'

注意：对于短信 API，授权基于 Bearer 令牌。在 readme 的 短信 API 部分中查看相关信息。

初始化您的 Mailjet 客户端

use \Mailjet\Resources;

// getenv will allow us to get the MJ_APIKEY_PUBLIC/PRIVATE variables we created before:

$apikey = getenv('MJ_APIKEY_PUBLIC');
$apisecret = getenv('MJ_APIKEY_PRIVATE');

$mj = new \Mailjet\Client($apikey, $apisecret);

// or, without using environment variables:

$apikey = 'your API key';
$apisecret = 'your API secret';

$mj = new \Mailjet\Client($apikey, $apisecret);

第一次调用

以下是一个发送电子邮件的示例

<?php
require 'vendor/autoload.php';
use \Mailjet\Resources;

// Use your saved credentials, specify that you are using Send API v3.1

$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'),true,['version' => 'v3.1']);

// Define your request body

$body = [
    'Messages' => [
        [
            'From' => [
                'Email' => "$SENDER_EMAIL",
                'Name' => "Me"
            ],
            'To' => [
                [
                    'Email' => "$RECIPIENT_EMAIL",
                    'Name' => "You"
                ]
            ],
            'Subject' => "My first Mailjet Email!",
            'TextPart' => "Greetings from Mailjet!",
            'HTMLPart' => "<h3>Dear passenger 1, welcome to <a href=\"https://www.mailjet.com/\">Mailjet</a>!</h3>
            <br />May the delivery force be with you!"
        ]
    ]
];

// All resources are located in the Resources class

$response = $mj->post(Resources::$Email, ['body' => $body]);

// Read the response

$response->success() && var_dump($response->getData());
?>

客户端/调用配置细节

要实例化库，您可以使用以下构造函数

new \Mailjet\Client($MJ_APIKEY_PUBLIC, $MJ_APIKEY_PRIVATE,$CALL,$OPTIONS);

  • $MJ_APIKEY_PUBLIC : 公共 Mailjet API 密钥
  • $MJ_APIKEY_PRIVATE : 私有 Mailjet API 密钥
  • $CALL : 布尔值，用于启用对 Mailjet API 服务器的 API 调用（应为 true 以运行 API 调用）
  • $OPTIONS : 关联 PHP 数组，描述连接选项（有关完整列表，请参阅下方的选项）

选项

API 版本控制

Mailjet API 分散在三个不同的版本中

  • v3 - 电子邮件 API
  • v3.1 - 电子邮件发送 API v3.1，这是我们的发送 API 的最新版本
  • v4 - 短信 API

由于大多数电子邮件 API 端点位于 v3 下，因此它被设置为默认版本，在发出请求时不需要指定。对于其他版本，您需要使用 version 指定版本。例如，如果使用发送 API v3.1

$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'),true,['version' => 'v3.1']);

有关更多信息，请参阅我们的 API 参考。

基础 URL

Mailjet API 的默认基础域名是 api.mailjet.com。您可以通过在您的调用中设置 url 的值来修改此基础 URL。

$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'),
                          getenv('MJ_APIKEY_PRIVATE'), true,
                          ['url' => "api.us.mailjet.com"]
                        );

如果您账户已迁移到Mailjet的美国架构，您需要设置的URL值是api.us.mailjet.com。

禁用 API 调用

默认情况下，API调用参数始终启用。但是，在测试期间，您可能希望将其禁用，以避免不必要的Mailjet API调用。这可以通过将第三个参数设置为false来完成。

$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'), false);

资源列表

您可以在/src/Mailjet/Resources.php中找到此库所有可用资源的列表。该文件列出了PHP资源的名称以及相应名称在API参考中的名称。

请求示例

POST请求

使用Mailjet客户端的post方法（即$mj->post($resource, $params)）。

$params将是一个PHP关联数组，包含以下键：

  • body：定义要创建的对象的关联PHP数组。属性对应于JSON有效负载的属性。
  • id：您想对其应用POST请求的ID（在资源操作的情况下使用）。

简单的 POST 请求

<?php
/*
Create a new contact:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$body = [
    'Email' => "email@example.com"
];
$response = $mj->post(Resources::$Contact, ['body' => $body]);
$response->success() && var_dump($response->getData());?>

使用操作

<?php
/*
Manage the subscription status of a contact to multiple lists
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$body = [
    'ContactsLists' => [
        [
            'ListID' => "$ListID_1",
            'Action' => "addnoforce"
        ],
        [
            'ListID' => "$ListID_2",
            'Action' => "addforce"
        ]
    ]
];
$response = $mj->post(Resources::$ContactManagecontactslists, ['id' => $id, 'body' => $body]);
$response->success() && var_dump($response->getData());
?>

GET请求

使用Mailjet客户端的get方法（即$mj->get($ressource, $params)）。

$param将是一个PHP关联数组，包含以下键：

  • id：您想要获取的元素的唯一ID（可选）。
  • filters：列出您想要应用到GET的查询参数的关联数组（可选）。

检索所有对象

<?php
/*
Retrieve all contacts:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$response = $mj->get(Resources::$Contact);
$response->success() && var_dump($response->getData());
?>

使用过滤

<?php
/*
Retrieve all contacts that are not in the campaign exclusion list :
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$filters = [
  'IsExcludedFromCampaigns' => 'false'
];
$response = $mj->get(Resources::$Contact, ['filters' => $filters]);
$response->success() && var_dump($response->getData());
?>

使用分页和排序

<?php
/*
Retrieve a specific contact ID :
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$filters = [
    'Limit'=>40,  // default is 10, max is 1000
    'Offset'=>20,
    'Sort'=>'ArrivedAt DESC',
    'Contact'=>$contact->ID,
    'showSubject'=>true
];
$response = $mj->get(Resources::$Message, ['filters'=>$filters]);
$response->success() && var_dump($response->getData());
?>

检索单个对象

<?php
/*
Retrieve a specific contact ID :
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$response = $mj->get(Resources::$Contact, ['id' => $id]);
$response->success() && var_dump($response->getData());
?>

PUT请求

使用Mailjet客户端的put方法（即$mj->put($ressource, $params)）。

$param将是一个PHP关联数组，包含以下键：

  • id：您想要修改的元素的唯一ID。
  • body：表示要更新对象属性的关联数组。

Mailjet API中的PUT请求将作为PATCH请求工作 - 更新将仅影响指定的属性。现有资源的其他属性既不会被修改，也不会被删除。这也意味着您可以从有效负载中省略所有非必填属性。

以下是一个PUT请求的示例。

<?php
/*
Update the contact properties for a contact:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$body = [
    'first_name' => "John",
    'last_name' => "Smith"
];
$response = $mj->put(Resources::$ContactData, ['id' => $id, 'body' => $body]);
$response->success() && var_dump($response->getData());
?>

DELETE请求

使用Mailjet客户端的delete方法（即$mj->delete($ressource, $params)）。

在成功的DELETE请求中，响应将不包含响应体，但只有204 No Content响应代码。

以下是一个DELETE请求的示例。

<?php
/*
Delete an email template:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$response = $mj->delete(Resources::$Template, ['id' => $id]);
$response->success() && var_dump($response->getData());
?>
<?php
/*
Delete a contact from contact list:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(
  getenv('MJ_APIKEY_PUBLIC'),
  getenv('MJ_APIKEY_PRIVATE'),
  true,
  ['version' => 'v4']
);
$response = $mj->delete(Resources::$Contacts, ['ID' => xxxx]);
$response->success() && var_dump($response->getData());
?>

响应

get、post、put和delete方法将返回一个包含以下可用方法的Response对象：

  • success()：返回一个布尔值，指示API调用是否成功。
  • getStatus()：http状态码（例如：200、400 ...）。
  • getData()：如果存在，则为JSON响应有效负载中data属性的值，或者为API调用返回的完整JSON有效负载。这将是一个PHP关联数组。
  • getCount()：响应中返回的元素数量。
  • getReasonPhrase()：http响应消息短语（例如：“OK”、“Bad Request” ...）。

API 资源辅助函数

所有API资源都列在Resources对象中。这将使查找资源和操作别名变得容易。

$response = $mj->delete(Resources::$Template, ['id' => $id]);
$response = $mj->put(Resources::$ContactData, ['id' => $id, 'body' => $body]);
$response = $mj->post(Resources::$ContactManagecontactslists, ['id' => $id, 'body' => $body]);

短信 API

令牌身份验证

SMS API端点的身份验证使用承载令牌完成。承载令牌在您的Mailjet账户的SMS部分生成。

要创建具有令牌身份验证的新Mailjet客户端实例，令牌应作为第一个参数提供，第二个必须为NULL。

$mj = new \Mailjet\Client(getenv('MJ_APITOKEN'),
                          NULL, true,
                          ['url' => "api.mailjet.com", 'version' => 'v4', 'call' => false]
                        );

示例请求

以下是一个SMS API请求的示例。

//Send an SMS
$mj = new \Mailjet\Client(getenv('MJ_APITOKEN'),
                          NULL, true,
                          ['url' => "api.mailjet.com", 'version' => 'v4', 'call' => false]
                        );
$body = [
    'Text' => "Have a nice SMS flight with Mailjet !",
    'To' => "+336000000000",
    'From' => "MJ Pilot",
];
$response = $mj->post(Resources::$SmsSend, ['body' => $body]);
$response->success() && var_dump($response->getData());

在主题中使用支持表情符号的请求发送。

require 'vendor/autoload.php';

use \Mailjet\Resources;

$mj = new \Mailjet\Client(
    'xxx',
    'xxx',
    true,
);

try {
    $subject = \Mailjet\Utility\StringUtility::utfStringNotation("This is subject with emoji  🤑" );

    $body = [
        'Locale' => "en_US",
        'Sender' => "sender@gmail.com",
        'SenderEmail' => "sender@gmail.com",
        'Subject' => $subject,
        'TemplateID' => 12345,
        'ContactsListID' => 12345,
        'Title' => "Emoji Test" . time(),

    ];
    $response = $mj->post(
        Resources::$Campaigndraft,
        [
            'body' => $body,
        ]
    );
    print_r($response->getData());
} catch (Throwable $throwable) {
    print_r($throwable->getMessage());
}

贡献

Mailjet热爱开发者。您可以成为这个项目的一部分！

这个包装器是开源世界的一个很好的入门，查看代码！

请随时提问，并做出贡献。

  • 分叉项目。
  • 创建一个新的分支。
  • 实现您的功能或错误修复。
  • 为其添加文档。
  • 提交代码，推送，然后发起一个Pull Request，就完成了。

如果您对我们的指南有改进建议，请在我们的官方API文档仓库中提交一个issue。