An objective-C implementation of Mailgun's Guardpost email validation service
The easiest way to install GuardPost-ObjectiveC is using cocoapods. Add the
following to your Podfile:
pod 'GuardPost-ObjectiveC', '~>0.1.1'
And then run:
pod install
Alternatively you can clone this repo and use the classes defined in the Classes
subdirectory. Note that AFNetworking is a dependency of this tool.
GuardPost offers 2 API methods - email validation and email list parsing. Before using either of these you need to set the API key. GuardPost is a service provided buy MailGun and therefore you need an account with them in order to use it. The GuardPost service is free - to sign up for a free account visit here.
Once you've signed up you need to get hold of your public API key (of the form 'pubkey-...'). To set it in your app you need to call the following method once:
[GPGuardPost setPublicAPIKey:@"pubkey-your-key-here"];
This is a static method - once you've set it it will be used for all calls to the GuardPost API throughout the lifetime of the app. Therefore setting it in the AppDelegate or viewDidLoad of the main view controller is a good idea.
To Validate an email use the +validateAddress:success:failure: method. This
takes a string for the address to validate, and 2 blocks - one to be called in
the event of a successful API call, and one for failure. For example:
[GPGuardPost validateAddress:self.emailField.text success:^(BOOL validity, NSString *suggestion) {
NSLog(@"API call successful");
} failure:^(NSError *error) {
NSLog(@"There was an error: %@", [error localizedDescription]);
}];
The success block has 2 arguments:
validityis aBOOLwhich specifies whether the email address sent is validsuggestionis anNSStringwhich has a suggestion for an email address, or is nil. Note that valid email addresses can have a non-nil suggestion, and similarly invalid addresses don't necessarily have a suggestion.
The error block has an NSError argument.
An email address field can be comprised of a string of comma or semi-colon delimited
email addresses. However, parsing the list is not always trivial. Therefore the
+parseListOfAddresses:success:failure method is provided by mailgun. Provded a
string which contains a list of addresses the method again has success and failure
callback blocks. The failure block is of the same form as for email validation.
The success block has 2 NSArray arguments - the first for a list of parsed
email addresses, and the second for unparseable parts of the list string. Note
that these email addresses have only been parsed for grammar, and additional
validation can then be performed with calls to the validateAddress method.
There is a sample app inside the Samples subdirectory called GuardPostExample.
This is a basic email validation app, which takes an email and reports back
whether it has been found to be valid or not.
In order to try this app out you'll need to provide your own API key. There is a
plist called GPSettings-Sample.plist. Duplicate this as GPSettings.plist and
update the MailGunPublicAPIKey key with your public key.
Alternatively, update the source code with your public key.
This project is an interface to the excellent GuardPost API provided by mailgun. The documentation for this API can be found here.
Feel free to raise an issue, or send a pull request. All contributions welcome!
This project was written by Sam Davies. You should have a peruse of his blog at iwantmyreal.name and follow him on twitter @iwantmyrealname or ADN @samd.