Mailchimp API 3.0 PHP
3.2.3
Esta é uma biblioteca PHP para interagir com a versão 3.0 da API do MailChimp
Esta biblioteca pressupõe um conhecimento básico do aplicativo MailChimp e de suas funções associadas.
Para execução do Composer:
composer require jhut89/mailchimp3php Alternativamente, você pode adicionar uma linha require aos seus projetos composer.json para o pacote jhut89/mailchimp3php .
Em seguida, execute composer update e adicione o autoloader do compositor ao seu projeto com:
require " vendor/autoload.php " ;Você pode então usar uma instrução use para obter a classe Mailchimp:
use MailchimpAPI Mailchimp ; $ mailchimp = new Mailchimp ( ' 123abc123abc123abc123abc-us0 ' ); Para instanciar você precisará de uma nova instância da classe Mailchimp com a chave API da sua conta MailChimp como único argumento.
Se você estiver usando OAuth para obter um token de acesso, esta biblioteca poderá lidar com o "aperto de mão" para você.
Você deve primeiro enviar o usuário para seus aplicativos authorize_uri . Você pode obter esse URL chamando Mailchimp::getAuthUrl() estaticamente:
$ client_id = ' 12345676543 ' ;
$ redirect_url = ' https://www.some-domain.com/callback_file.php ' ;
Mailchimp:: getAuthUrl ( $ client_id , $ redirect_url );Opcionalmente, se você precisar passar informações de estado junto com sua solicitação para que a resposta de retorno de chamada possa ser roteada corretamente, você poderá incluir um parâmetro de estado:
$ client_id = ' 12345676543 ' ;
$ redirect_url = ' https://www.some-domain.com/callback_file.php ' ;
// state information encoded into a string to be included in the URL, for example data encoded in a JWT token
$ state = ' eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ' ;
Mailchimp:: getAuthUrl ( $ client_id , $ redirect_url , $ state ); A partir daí, o usuário inserirá seu nome de usuário e senha para aprovar sua inscrição e será redirecionado para o redirect_uri que você definiu junto com um code .
Com esse code agora você pode solicitar um token de acesso do mailchimp. Para isso você precisará chamar o método Mailchimp::oauthExchange() estaticamente assim:
$ code = ' abc123abc123abc123abc123 ' ;
$ client_id = ' 12345676543 ' ;
$ client_secret = ' 789xyz789xyz789xyz789xyz ' ;
$ redirect_url = ' https://www.some-domain.com/callback_file.php ' ;
Mailchimp:: oauthExchange ( $ code , $ client_id , $ client_secret , $ redirect_url ); Se o handshake for bem-sucedido, este método retornará uma string contendo sua chave de API como esta: 123abc123abc123abc123abc123abc-us0 . Esta chave de API agora pode ser usada para instanciar sua classe Mailchimp como fizemos acima.
Depois de instanciar a classe Mailchimp , você poderá começar a construir solicitações. A construção de solicitações é feita 'encadeando' métodos à instância $mailchimp . Na maioria dos casos, esta 'cadeia' terminará com o verbo HTTP da sua solicitação.
Um exemplo de como recuperar uma coleção de listas:
$ mailchimp
-> lists ()
-> get (); A recuperação de uma instância pode ser realizada fornecendo um identificador exclusivo para a instância desejada como argumento para o método apropriado. Por exemplo, se eu quisesse recuperar uma instância de lista do exemplo acima, simplesmente passaria um list_id , como o único argumento para o método lists() . Assim:
$ mailchimp
-> lists ( ' 1a2b3c4d ' )
-> get ();Os métodos disponíveis para cada posição na cadeia dependem do que o método anterior retorna. Por exemplo, se eu quisesse recuperar assinantes de uma lista da minha conta, eu:
$ mailchimp
-> lists ( ' 1a2b3c4d ' )
-> members ()
-> get (); Observe que forneci um list_id ao método lists() , pois não haveria como recuperar uma lista de assinantes de uma coleção de listas. A solicitação acima, entretanto, retornará apenas 10 instâncias de assinantes da coleção de membros. Isso ocorre porque a API do MailChimp usa paginação (documentada AQUI) cujo padrão é count=10 e offset=0 . Esta biblioteca permite alterar os parâmetros da string de consulta, passando-os como argumento para o método GET() . Fazemos isso fornecendo uma matriz de pares chave-valor onde as chaves são o parâmetro de consulta que você deseja fornecer/alterar e seu valor é o valor do parâmetro. Por exemplo, se eu quisesse recuperar os segundos 100 assinantes da minha lista, eu poderia:
$ mailchimp
-> lists ( ' 1a2b3c4d ' )
-> members ()
-> get ([
" count " => " 100 " ,
" offset " => " 100 "
]);Isso seria equivalente a fazer uma solicitação get contra:
Https://us0.api.mailchimp.com/3.0/lists/1a2b3c4d/members?count=100&offset=100
Indo um pouco mais longe, podemos recuperar um único membro da lista, fornecendo o members_hash (hash md5 de endereço em minúsculas) ao método members() . Assim:
$ mailchimp
-> lists ( ' 1a2b3c4d ' )
-> members ( ' 8bdbf060209f35b52087992a3cbdf4d7 ' )
-> get (); Alternativamente, em vez de fornecer um hash md5 como identificador para a função members() você pode fornecer o endereço de e-mail de um contato como uma string e esta biblioteca fará o hash para você. Assim:
$ mailchimp
-> lists ( ' 1a2b3c4d ' )
-> members ( ' [email protected] ' )
-> get ();Você pode ler mais sobre solicitações
GETaqui: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Get-Requests
Embora seja ótimo poder recuperar dados da sua conta, também precisamos poder postar novos dados. Isso pode ser feito chamando o método POST() no final de uma cadeia. Por exemplo, inscrever um endereço em uma lista ficaria assim:
$ post_params = [
' email_address ' => ' [email protected] ' ,
' status ' => ' subscribed '
];
$ mailchimp
-> lists ( ' 1a2b3c4d ' )
-> members ()
-> post ( $ post_params ); Nesse caso, eu não forneceria aos members() um identificador, pois desejo postar em sua coleção. Observe também que os dados da postagem são uma matriz de pares de valores-chave que representam quais parâmetros desejo passar para a API MailChimp. Certifique-se de fornecer todos os campos obrigatórios para o endpoint no qual você está postando. Verifique a documentação do MailChimp para saber quais parâmetros são necessários. Parâmetros não obrigatórios podem apenas ser adicionados aos dados da postagem, e o MailChimp irá ignorar aqueles que forem inutilizáveis. Para ilustrar aqui está um exemplo de adição de um assinante a uma lista com alguns parâmetros não obrigatórios:
$ merge_values = [
" FNAME " => " John " ,
" LNAME " => " Doe "
];
$ post_params = [
" email_address " => " [email protected] " ,
" status " => " subscribed " ,
" email_type " => " html " ,
" merge_fields " => $ merge_values
]
$ mailchimp
-> lists ( ' 1a2b3c4d ' )
-> members ()
-> post ( $ post_params );Você pode ler mais sobre as solicitações
POSTaqui: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Post-Requests
Esta biblioteca lida com solicitações PUT e PATCH semelhantes às solicitações POST. O que significa que PUT() e PATCH() aceitam uma matriz de pares de valores-chave que representam os dados que você deseja alterar/fornecer ao MailChimp. Por exemplo, se eu estivesse corrigindo o assinante que assinamos acima, para ter um novo nome, ficaria assim.
$ mailchimp
-> lists ( ' 1a2b3c4d ' )
-> members ( ' a1167f5be2df7113beb69c95ebcdb2fd ' )
-> patch ([
" merge_fields " => [ " FNAME " => " Jane " ]
]);Você pode ler mais sobre as solicitações
PATCH&PUTaqui: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Patch-&-Put-Requests
A exclusão de um registro do MailChimp é realizada com o método DELETE() e é construída de forma semelhante às solicitações GET. Se eu quisesse excluir o assinante acima, eu faria:
$ mailchimp
-> lists ( ' 1a2b3c4d ' )
-> members ( ' a1167f5be2df7113beb69c95ebcdb2fd ' )
-> delete ();Você pode ler mais sobre as solicitações
DELETEaqui: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Delete-Requests
Métodos nomeados para verbos http, como get() , post() , patch() , put() ou delete() iniciam uma solicitação over the wire para a API do MailChimp. Dada uma solicitação bem-sucedida, esses métodos retornam uma instância de MailchimpResponse . Sugiro que você se familiarize com esta classe, pois há vários modificadores e getters para diferentes partes de uma resposta.
Existem vários getters que podemos usar para interagir com partes de nossa instância MailchimpResponse . Alguns dos mais comumente usados são:
$ response -> deserialize (); // returns a deserialized (to php object) resource returned by API
$ response -> getHttpCode (); // returns an integer representation of the HTTP response code
$ response -> getHeaders (); // returns response headers as an array of key => value pairs
$ response -> getBody (); // return the raw text body of the responsePor exemplo, se eu possuo uma chave API, mas quero o e-mail de contato associado à sua conta:
$ mailchimp = new Mailchimp ( ' 123abc123abc123abc123abc-us0 ' );
$ account = $ mailchimp
-> account ()
-> get ()
$ contact_email = $ account
-> deserialize ()
->email
print $ contact_email ; // outputs something like "[email protected]"Você pode ler sobre como trabalhar com respostas em profundidade aqui: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Handling-A-Response
mailchimp()
|
|----account()
|
|----apps()
|
|----automations()
| |
| |----removedSubscribers()
| |----emails()
| |
| |---queue()*
| |---pauseAll()*
| |---startAll()*
|
|----batches()
|
|----batchWebhooks()
|
|----campaignFolders()
|
|----campaigns()
| |
| |----cancel()*
| |----pause()*
| |----replicate()*
| |----resume()*
| |----scedule()*
| |----send()*
| |----test()*
| |----unschedule()*
| |----checklist()
| |----feedback()
| |----content()
|
|----connectedSites()
| |
| |----verifyScriptInstallation()*
|
|----conversations()
| |
| |----messages()
|
|----ecommStores()
| |
| |----customers()
| |----products()
| | |
| | |----variants()
| | |----images()
| |
| |----promoRules()
| | |
| | |----promoCodes()
| |
| |----orders()
| | |
| | |----lines()
| |
| |----carts()
| |
| |----lines()
|
|----facebookAds()
|
|----fileManagerFiles()
|
|----fileManagerFolders()
|
|----googleAds()
|
|----landingPages()
| |
| |----publish()*
| |----unpublish()*
| |----content()
|
|----lists()
| |
| |----batchSubscribe()*
| |----webhooks()
| |----signupForms()
| |----mergeFields()
| |----growthHistory()
| |----clients()
| |----activity()
| |----abuseReports()
| |----segments()
| | |
| | |----batch()*
| | |----members()
| |
| |----members()
| | |
| | |---notes()
| | |---goals()
| | |---activity()
| | |---tags()
| |
| |----interestCategories()
| |
| |----interests()
|
|----ping()
|
|----reports()
| |
| |----unsubscribes()
| |----subReports()
| |----sentTo()
| |----locations()
| |----emailActivity()
| |----googleAnalytics()
| |----openDetails()
| |----eepurl()
| |----domainPerformance()
| |----advice()
| |----abuse()
| |----clickReports()
| |
| |----members()
|
|----searchCampaigns()
|
|----searchMembers()
|
|----templateFolders()
|
|----templates()
| |
| |----defaultContent()
|
|----verifiedDomains()
|
|----verify()
*Por favor, consulte a documentação da API do MailChimp para saber quais verbos são apropriados e onde.
** Métodos marcados com * fazem uma solicitação de rede
** Fique atento às atualizações e sinta-se à vontade para fazer um Fork ou Pull Request. Confira o Wiki para mais informações sobre como contribuir.
