SDK do Mailgun para Objective-C agora disponível

Esta postagem foi originalmente publicada por Jay Baird no blog de DevOps da Rackspace. A equipe da Rackspace tem usado o Mailgun para diversos projetos (como este) e acabou de lançar um SDK de código aberto para integrar o Mailgun a aplicativos de iOS. Na verdade, Jay se senta logo atrás da equipe do Mailgun no escritório da Rackspace em São Francisco. Estamos publicando a postagem completa aqui em nosso blog, mas recomendamos que você confira o blog de DevOps da Rackspace para ver outros bons artigos técnicos.

Um dos meus serviços favoritos aqui na Rackspace é o Mailgun, um conjunto de APIs que permite enviar e-mails e gerenciar listas de e-mails por meio de uma API REST. Voltando de uma viagem recente a San Antonio, decidi que adicionaria uma interface em Objective-C para enviar e-mails pelo Mailgun usando minha própria interface de iOS em vez de usar o MFMailComposeViewController da Apple. Essa biblioteca agora tem código aberto no Github e está disponível via Cocoapods.

Para instalar o SDK do Mailgun, você pode usar o fantástico Cocoapods ou instalar diretamente do código-fonte adicionando o Mailgun.(h|m) e o MGMessage.(h|m) ao seu projeto do Xcode. Se você optar pela instalação manual, também precisará seguir as instruções para instalar a biblioteca AFNetworking .

Atualmente, as únicas funções da API do Mailgun compatíveis com o SDK são o envio de e-mails, além da assinatura e do cancelamento de inscrição em listas de e-mails. Achei que esses seriam os recursos mais comuns para o desenvolvimento de aplicativos, mas mais recursos da API do Mailgun serão adicionados no futuro. A documentação completa da biblioteca pode ser encontrada no diretório Docs no Github ou em <cocoadocs.org.

Para enviar uma mensagem rapidamente pelo SDK do Mailgun, criaremos nosso cliente usando o método de classe clientWithDomain:apiKey: cujos argumentos são seu domínio específico do Mailgun e sua chave de API. Neste exemplo, usaremos samples.mailgun.org e key-3ax6xnjp29jd6fds4gc373sgvjxteol0.

Mailgun *mailgun = [Mailgun clientWithDomain:@"samples.mailgun.org" apiKey:@"key-3ax6xnjp29jd6fds4gc373sgvjxteol0"];

O envio de mensagens pode ocorrer de várias maneiras. Você pode usar o método de instância sendMessageTo:from:subject:body para disparar rapidamente uma mensagem simples e “única” como esta:

[mailgun sendMessageTo:@"Jay Baird " from:@"Usuário animado " subject:@"O Mailgun é incrível!" body:@"Um boneco de neve em unicode para você! "];

Você também pode construir uma mensagem com mais recursos usando o objeto MGMessage. Aqui criarei um objeto MGMessage com um anexo de imagem de um gato, porque a internet existe apenas para proliferar fotos de gatos, e o enviarei pelo SDK:

UIImage *catImage = [UIImage imageNamed:@"cat-pic-01"]; MGMessage *message = [MGMessage messageFrom:@"Usuário animado " to:@"Jay Baird " subject:@"O Mailgun é incrível!" body:@"O Mailgun é ótimo, aqui está a foto de um gato."];

[message addImage:catImage withName:@"cat-pic-01" type:PNGFileType];

Isso anexa uma UIImage à MGMessage que eu criei. Os dados da UIImage serão adicionados como um anexo à mensagem.

Existe uma interface idêntica para OS X que recebe uma NSImage e um NSBitmapImageFileType.

Quando nossa mensagem estiver construída, podemos adicionar destinatários por meio do método addRecipient:, adicionar destinatários CC e CCO via addCC: e addBCC: e também adicionar tags, variáveis e muitos outros recursos compatíveis com o(a) API do Mailgun. Dê uma olhada no cabeçalho do MGMessage.h para ver tudo o que é compatível.

Para enviar essa mensagem construída especialmente, você pode usar os métodos de cliente sendMessage: ou o método de callback baseado em blocos sendMessage:success:failure:. Aqui usaremos este último para mostrar uma mensagem ao usuário quando a MGMessage for enviada com sucesso ou exibir um erro caso ocorra uma falha.

[mailgun sendMessage:message success:^(NSString *messageId) {
NSLog(@"Mensagem %@ enviada com sucesso!", messageId);
} failure:^(NSError *error) {
NSLog(@"Erro ao enviar a mensagem. O erro foi: %@", [error userInfo]);
}];

As listas de e-mails do Mailgun fornecem uma maneira conveniente de enviar para vários destinatários usando um endereço de e-mail de alias. O Mailgun envia uma cópia da mensagem endereçada ao alias para cada pessoa inscrita na lista de e-mails. Adicionar um recurso de assinar/cancelar inscrição em seu aplicativo pode ser uma ótima maneira de manter o engajamento e o contato com a sua clientela, enviando atualizações e dicas periódicas. Para que um usuário assine uma lista de e-mails, usaremos o mesmo cliente do Mailgun que criamos no primeiro exemplo:

Mailgun *mailgun = [Mailgun clientWithDomain:@"samples.mailgun.org" apiKey:@"key-3ax6xnjp29jd6fds4gc373sgvjxteol0"];

Neste exemplo, criei um AboutViewController que tem um UITextFieldv onde um usuário pode inserir seu endereço de e-mail e tocar em um botão para assinar. Veja como lido com a ação do botão para assinar:

UITextField *mailTextField = [[UITextField alloc] initWithFrame:CGRectZero];

[mailgun subscribeToList:@”news@sampleapp.org” email:mailTextField.text success:^{
NSLog(@”O usuário assinou a lista de e-mails com sucesso!”);
} failure:^(NSError *error) {
NSLog(@”Houve um erro ao assinar a lista de e-mails: %@”, [error userInfo]
); }];

Os blocos de sucesso e falha podem ser usados para exibir mais informações ao usuário, acompanhar as análises e mostrar ou ocultar o progresso enquanto o SDK faz as chamadas de API necessárias.

Para cancelar a inscrição, o processo é semelhante. Pegamos o e-mail de um usuário assinante, neste caso usaremos meu endereço de e-mail jay.baird@rackspace.com e cancelaremos a inscrição da lista de e-mails do SampleApp:

NSString *emailAddress = @"jay.baird@rackspace.com";

[mailgun unsubscribeToList:@”news@sampleapp.org” email:emailAddress success:^{
NSLog(@”%@ removido com sucesso da lista de e-mails”, emailAddress);
} failure:^(NSError *error) {
NSLog(@”Erro ao remover o endereço da lista de e-mails: %@”, [error userInfo]
); }];

NOTA: se um usuário não tiver assinado uma lista de e-mails, esse método chamará o bloco de falha com um erro 404. Isso é normal e deve ser tratado adequadamente.

Espero que esta breve introdução ao novo SDK do Mailgun deixe você tão empolgado quanto eu para adicionar recursos do Mailgun ao seu próximo projeto de OS X ou iOS. Sinta-se à vontade para fazer um fork do projeto e contribuir, ou relatar qualquer problema que encontrar em nossa página do Github.

Autor: The Sinch Mailgun team The Sinch Mailgun team shares news, best practices, and strategies to take your products and apps to the next level using email. Subscribe to our newsletter to get all the articles in your inbox!