Inherits from AFHTTPClient
Declared in Mailgun.h

Overview

The Mailgun SDK allows your Mac OS X or iOS application to connect with the Mailgun programmable email platform. Send and manage mailing list subscriptions from your desktop or mobile applications and connect with your users directly in your application.

Requirements The AFNetworking library is required for the Mailgun client library.

Easy Image Attaching

Using MGMessage will allow you to attach UIImage or NSImage instances to a message. It will handle converting the image for you and attaching it either inline or to the message header.

This SDK is not 1:1 to the REST API

At this time the full Mailgun REST API is not supported. Currently support is only provided to send messages, subscribe/unsubscribe from mailing lists and to check mailing lists subscriptions.

Note These features may be implemented at a later date.

Sending Example

 Mailgun *mailgun = [Mailgun clientWithDomain:@"samples.mailgun.org" apiKey:@"key-3ax6xnjp29jd6fds4gc373sgvjxteol0"];  
 [mailgun sendMessageTo:@"Jay Baird <jay.baird@rackspace.com>"   
                   from:@"Excited User <someone@sample.org>"   
                subject:@"Mailgun is awesome!"   
                   body:@"A unicode snowman for you! ☃"];  

Installing

  1. Install via Cocoapods

    pod install mailgun

  2. Install via Source

    1. Clone the repository.
    2. Copy Mailgun.h/.m and MGMessage.h/.m to your project.
    3. There’s no step three!

Tasks

Mailgun Client Setup

  •   apiKey

    Returns the value for the HTTP headers set in request objects created by the HTTP client.

    property
  •   domain property

Creating and Initializing the Mailgun Client

Sending a Previously Constructed Mailgun Message

Sending an Ad-Hoc Mailgun Message

Checking Mailing List Subscription

Subscribing/Unsubscribing to Mailing Lists

Properties

apiKey

Returns the value for the HTTP headers set in request objects created by the HTTP client.

@property (nonatomic, strong) NSString *apiKey

Parameters

header

The HTTP header to return the default value for

Return Value

The default value for the HTTP header, or nil if unspecified

Declared In

Mailgun.h

domain

@property (nonatomic, strong) NSString *domain

Class Methods

client

Creates and initializes an Mailgun object with the specified.

+ (instancetype)client

Return Value

The newly-initialized Mailgun client

Discussion

%warning%
Warning: Important: You will need to set a domain and an API key on this object after creation in order to use the client.

Declared In

Mailgun.h

clientWithDomain:apiKey:

Creates and initializes an Mailgun object with the domain and api key specified.

+ (instancetype)clientWithDomain:(NSString *)domain apiKey:(NSString *)apiKey

Parameters

domain

The domain for this client. Must not be nil.

apiKey

The API key for your Mailgun account. Must not be nil.

Return Value

The newly-initialized Mailgun client

Declared In

Mailgun.h

Instance Methods

checkSubscriptionToList:email:success:failure:

Checks if the given email address is a current subscriber to the specified mailing list.

- (void)checkSubscriptionToList:(NSString *)list email:(NSString *)emailAddress success:(void ( ^ ) ( NSDictionary *member ))success failure:(void ( ^ ) ( NSError *error ))failure

Parameters

list

The mailing list to check for the provided email address. Must not be nil.

emailAddress

Email address to check for list membership. Must not be nil.

success

A block called when the email address is found as a subscriber to list, called with a NSDictionary of member information.

failure

A block called when the email address is not found as a subscriber to list. The NSError will be an HTTP 404.

Declared In

Mailgun.h

sendMessage:

Sends a previously constructed MGMessage without success or failure blocks.

- (void)sendMessage:(MGMessage *)message

Parameters

message

The MGMessage instance to send.

Declared In

Mailgun.h

sendMessage:success:failure:

Sends a previously constructed MGMessage with the provided success and failure blocks.

- (void)sendMessage:(MGMessage *)message success:(void ( ^ ) ( NSString *messageId ))success failure:(void ( ^ ) ( NSError *error ))failure

Parameters

success

A block called when the message is sent successfully called with a parameter NSString of the message id.

failure

A block called when the underlying HTTP request fails. It will be called with an NSError set by the underlying AFNetworking client.

Declared In

Mailgun.h

sendMessageTo:from:subject:body:

Sends a simple message without success or failure blocks.

- (void)sendMessageTo:(NSString *)to from:(NSString *)from subject:(NSString *)subject body:(NSString *)body

Parameters

to

The message recipient. Must not be nil.

from

The message sender. Must not be nil.

subject

The message subject. Must not be nil.

body

The body of the message.

Declared In

Mailgun.h

sendMessageTo:from:subject:body:success:failure:

Sends a simple message with success or failure blocks.

- (void)sendMessageTo:(NSString *)to from:(NSString *)from subject:(NSString *)subject body:(NSString *)body success:(void ( ^ ) ( NSString *messageId ))success failure:(void ( ^ ) ( NSError *error ))failure

Parameters

to

The message recipient. Must not be nil.

from

The message sender. Must not be nil.

subject

The message subject. Must not be nil.

body

The body of the message.

success

A block called when the message is sent successfully called with a parameter NSString of the message id.

failure

A block called when the underlying HTTP request fails. It will be called with an NSError set by the underlying AFNetworking client.

Declared In

Mailgun.h

subscribeToList:email:success:failure:

Subscribes the given email address to the specified mailing list.

- (void)subscribeToList:(NSString *)list email:(NSString *)emailAddress success:(void ( ^ ) ( ))success failure:(void ( ^ ) ( NSError *error ))failure

Parameters

list

The mailing list to subscribe the provided email address to. Must not be nil.

emailAddress

Email address to subscribe. Must not be nil.

success

A block called when the email address is successfully subscribed to the mailing list.

failure

A block called when there is an error subscribing the user to the given mailing list.

Declared In

Mailgun.h

unsubscribeToList:email:success:failure:

Unsubscribes the given email address to the specified mailing list.

- (void)unsubscribeToList:(NSString *)list email:(NSString *)emailAddress success:(void ( ^ ) ( ))success failure:(void ( ^ ) ( NSError *error ))failure

Parameters

list

The mailing list to unsubscribe the given email address from. Must not be nil.

emailAddress

Email address to check for list membership. Must not be nil.

success

A block called when the email address is successfully removed from the mailing list.

failure

A block called when the email address is not found as a subscriber to list. The NSError will be an HTTP 404.

Declared In

Mailgun.h