This post is about GuardPost-ObjectiveC
- an objC wrapper around MailGun’s email validation web service. Checkout the project on GitHub or read on for more info…
Email address validation can be really hard work. We’ve all spent many hours attempting to write a reasonable regular expression to make sure that our users aren’t mis-typing their email address, but regex doesn’t catch everything.
MailGun recently released
a new API called GuardPost, which is used for validating
email addresses - checking not only the parts of the email address, but also that
the domain exists and has a responsive mail exchanger. It also offers suggestions
for common mis-spellings of email addresses - e.g.
gmial.com will result in a
This weekend I have built an objC wrapper around the new mailgun GuardPost API, and I’ll explain how to use it here.
GuardPost is part of the web service offered by mailgun, and allows validation of email addresses. It has a really simple API - details of which can be found in their documentation. The two methods it offers are as follows:
- Validation This takes a string and attempts to determine whether it is a valid email address. Not only does it check the construction of the string against a grammar, but also whether the domain exists and whether it supports a mail exchanger. Suggestions for common mis-spellings are also offered.
- Parsing Given a string containing multiple email addresses (comma or semi-colon delimited) this tool attempts to split them up into valid email addresses and unparseable string sections.
The GuardPost API is free to use, but requires an API key from mailgun. You can sign up for a free account here.
GuardPost-ObjectiveC is a friendly wrapper around the mailgun service - based on AFNetworking. It is packaged up as a CocoaPod so installation is simple:
And then installation (as with every other CocoaPod) is as simple as:
This installs the dependencies as well as GuardPost-ObjectiveC itself.
The class which provides the required functionality is
GPGuardPost, and it
is provided by the
Before attempting to verify an email address you need to specify your mailgun
API key. This is the public API key - with a prefix of
pubkey-. To set it use
setPublicAPIKey: class method. This only has to be done once per application
so it might make sense to do it in the app delegate:
Now you’re all set to go.
Email Address Validation
To verify an email address use the class method
+validateAddress:success:failure:. It takes a string for the address, and 2
blocks - one for success, the other for failure.
The success block has 2 arguments:
validityis a BOOL which specifies whether the email address sent is valid
suggestionis an NSString which has a suggestion for an email address, or is
nil. Note that valid email addresses can have a non-
nilsuggestion, and similarly invalid addresses don’t necessarily have a suggestion.
The error block has an
NSError argument, which will contain details of the
problem - e.g. a
401 message in the event of authorization failure.
Email List Parsing
+parseListOfAddresses:success:failure method mirrors the API call provided
by mailgun. Provided a string which contains a list of addresses the method again
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
GuardPost-ObjectiveC repo there is a Samples directory, which contains
an example application. This is a really simple app which verifies an email address
as valid and updates the UI as appropriate.
We create the UI in a storyboard and provide the following outlets and methods in the header file:
The implementation which goes alongside this as follows. It’s refreshingly simple:
You can see the
failure blocks clearly. The majority of this code
is getting the right UI elements to appear at the right time with the correct
content. The call to validate the email address is really simple.
To improve the usability we implement the following
which will empty the textfield when the keyboard shows, and also hide any previous
Hopefully you might find this useful. I think it’s a great service from mailgun - validating email addresses is often a fiddly job, and now it’s a lot simpler.
If you have any suggestions/improvements then send a pull request or raise an issue on the GitHub repo.