Mailgun Class Reference
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
Install via Cocoapods
pod install mailgun
Install via Source
- Clone the repository.
- Copy Mailgun.h/.m and MGMessage.h/.m to your project.
- 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
-
+ client
Creates and initializes an
Mailgun
object with the specified. -
+ clientWithDomain:apiKey:
Creates and initializes an
Mailgun
object with the domain and api key specified.
Sending a Previously Constructed Mailgun Message
-
– sendMessage:
Sends a previously constructed MGMessage without success or failure blocks.
-
– sendMessage:success:failure:
Sends a previously constructed MGMessage with the provided success and failure blocks.
Sending an Ad-Hoc Mailgun Message
-
– sendMessageTo:from:subject:body:
Sends a simple message without success or failure blocks.
-
– sendMessageTo:from:subject:body:success:failure:
Sends a simple message with success or failure blocks.
Checking Mailing List Subscription
-
– checkSubscriptionToList:email:success:failure:
Checks if the given email address is a current subscriber to the specified mailing list.
Subscribing/Unsubscribing to Mailing Lists
-
– unsubscribeToList:email:success:failure:
Unsubscribes the given email address to the specified mailing list.
-
– subscribeToList:email:success:failure:
Subscribes the given email address to the specified mailing list.
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
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
- 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 aNSDictionary
of member information.
- failure
A block called when the email address is not found as a subscriber to
list
. TheNSError
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 underlyingAFNetworking
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 underlyingAFNetworking
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
. TheNSError
will be an HTTP 404.
Declared In
Mailgun.h