Le SDK Mailgun pour Objective-C est désormais disponible

Cet article a été initialement publié par Jay Baird sur le blog DevOps de Rackspace. L’équipe Rackspace utilise Mailgun pour divers projets (comme celui-ci), et vient de publier en open source un SDK pour intégrer Mailgun dans des applications iOS. Jay travaille d’ailleurs juste derrière l’équipe Mailgun dans les bureaux de Rackspace à San Francisco. Nous publions l’intégralité de l’article ici sur notre blog, mais nous vous encourageons vivement à consulter le blog DevOps de Rackspace pour découvrir d’autres excellents articles techniques.

L’un de mes services préférés chez Rackspace est Mailgun, un ensemble d’API qui vous permet d’envoyer un email et de gérer des listes de diffusion via une API REST. De retour d’un récent voyage à San Antonio, j’ai décidé d’ajouter une interface Objective-C pour envoyer un email via Mailgun en utilisant ma propre interface iOS au lieu d’utiliser le MFMailComposeViewController d’Apple. Cette bibliothèque est désormais disponible en open source sur Github et accessible via Cocoapods.

Pour installer le SDK Mailgun, vous pouvez soit utiliser le fantastique Cocoapods soit l’installer directement depuis la source en ajoutant Mailgun.(h|m) et MGMessage.(h|m) à votre projet Xcode. Si vous choisissez de l’installer manuellement, vous devrez également suivre les instructions pour installer la bibliothèque AFNetworking .

Actuellement, les seules fonctions de l’API de Mailgun que le SDK prend en charge sont l’envoi d’emails, l’inscription aux listes de diffusion et la désinscription aux listes de diffusion. J’ai estimé que ce sont les fonctionnalités les plus courantes qu’une équipe de développement utiliserait, mais d’autres fonctionnalités de l’API de Mailgun seront ajoutées à l’avenir. La documentation complète de la bibliothèque se trouve dans le répertoire Docs sur Github ou sur <cocoadocs.org.

Pour envoyer rapidement un message via le SDK Mailgun, nous allons créer notre client en utilisant la méthode de classe clientWithDomain:apiKey: les arguments de cette méthode étant votre domaine Mailgun spécifique et votre clé API. Pour cet exemple, nous utiliserons samples.mailgun.org et key-3ax6xnjp29jd6fds4gc373sgvjxteol0.

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

L’envoi d’un message peut se faire de plusieurs manières. Vous pouvez utiliser la méthode d’instance sendMessageTo:from:subject:body pour envoyer rapidement un simple message ponctuel comme ceci :

[mailgun sendMessageTo:@"Jay Baird " from:@"Excited User " subject:@"Mailgun is awesome!" body:@"A unicode snowman for you! "];

Vous pouvez également construire un message plus complet en utilisant l’objet MGMessage. Ici, je vais créer un objet MGMessage avec une image de chat en pièce jointe, car Internet n’existe que pour propager des photos de chats, et l’envoyer via le SDK :

UIImage *catImage = [UIImage imageNamed:@"cat-pic-01"]; MGMessage *message = [MGMessage messageFrom:@"Excited User " to:@"Jay Baird " subject:@"Mailgun is awesome!" body:@"Mailgun is great, here is a picture of a cat."];

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

Cela ajoute une UIImage à l’objet MGMessage que j’ai créé. Les données de l’ UIImage seront ajoutées en tant que pièce jointe au message.

Une interface identique existe pour OS X qui prend une NSImage et un NSBitmapImageFileType.

Une fois notre message construit, nous pouvons ajouter des destinataires via la méthode addRecipient:, ajouter des destinataires en CC et CCI via addCC: et addBCC: et également ajouter les balises, des variables et toute une série d’autres fonctionnalités prises en charge par l’ API de Mailgun. Consultez l’en-tête de MGMessage.h pour voir tout ce qui est pris en charge.

Pour envoyer ce message spécialement construit, vous pouvez utiliser les méthodes clientes sendMessage: ou la méthode de rappel basée sur des blocs sendMessage:success:failure:. Ici, nous utiliserons cette dernière pour afficher un message lorsque le MGMessage est envoyé avec succès ou afficher une erreur en cas de problème.

[mailgun sendMessage:message success:^(NSString *messageId) {
NSLog(@"Message %@ sent successfully!", messageId);
} failure:^(NSError *error) {
NSLog(@"Error sending message. The error was: %@", [error userInfo]);
}];

Les listes de diffusion de Mailgun constituent un moyen pratique d’envoyer des emails à de multiples destinataires en utilisant une adresse email alias. Mailgun envoie une copie du message adressé à l’alias à chaque personne inscrite sur la liste de diffusion. Ajouter une fonctionnalité d’inscription et de désinscription à votre application peut être un excellent moyen de maintenir l’engagement et le contact avec votre clientèle en lui envoyant des mises à jour et des conseils réguliers. Pour inscrire un utilisateur à une liste de diffusion, nous utiliserons le même client Mailgun que celui créé dans le premier exemple :

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

Pour cet exemple, j’ai créé un AboutViewController doté d’un UITextFieldv où un utilisateur peut saisir son adresse email et appuyer sur un bouton d’inscription. Voici comment je gère l’action du bouton d’inscription :

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

[mailgun subscribeToList:@”news@sampleapp.org” email:mailTextField.text success:^{
NSLog(@”Successfully subscribed user to mailing list!”);
} failure:^(NSError *error) {
NSLog(@”There was an error while subscribing to the mailing list: %@”, [error userInfo]
); }];

Les blocs de succès et d’échec peuvent être utilisés pour fournir plus d’informations à l’utilisateur, suivre les statistiques et afficher ou masquer la progression pendant que le SDK effectue les appels API nécessaires.

Pour se désinscrire, le processus est similaire. Nous prenons l’email d’un utilisateur inscrit, dans ce cas nous utiliserons mon adresse email jay.baird@rackspace.com, et nous le désinscrivons de la liste de diffusion SampleApp :

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

[mailgun unsubscribeToList:@”news@sampleapp.org” email:emailAddress success:^{
NSLog(@”Successfully removed %@ from the mailing list”, emailAddress);
} failure:^(NSError *error) {
NSLog(@”Error removing address from mailing list: %@”, [error userInfo]
); }];

REMARQUE : Si un utilisateur n’est pas inscrit à une liste de diffusion, cette méthode appellera le bloc d’échec avec une erreur 404. Ceci est tout à fait normal et doit être géré de manière appropriée.

J’espère que cette brève introduction au nouveau SDK Mailgun vous enthousiasme autant que moi à l’idée d’ajouter les fonctionnalités Mailgun à votre prochain projet OS X ou iOS. N’hésitez pas à créer un fork du projet et à y contribuer, ou à signaler tout problème rencontré sur notre page Github.

Auteur·trice: 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!