Email

Your guide to API endpoints

API endpoints are a different way for applications to communicate. Why does this matter? Because endpoints enable the features and services we interact with every day. If you understand them, you can manipulate them to do things like improve your email program. Curious to learn more?

PUBLISHED ON

PUBLISHED ON

APIs can be difficult to understand, especially if you’re not familiar with building programmatic processes. Can we let you in on a little secret? APIs are just ways for applications to communicate with one another, and if you know how to use them they can simplify your life.

What is an API endpoint?

If you’re new to the world of email APIs, or APIs in general, API endpoints can be confusing to wrap your mind around. All an API endpoint is, is a unique URL that contains the name of a server or service. It identifies a specific location with an application programming interface (API).

To use an API endpoint, you have to make an API call or request but there’s a quick analogy we can cook up to show you how these endpoints work, and how beneficial they can be but fair warning, it might make you hungry.

How APIs work

When describing APIs, it’s fun to imagine a waiter in a restaurant. You communicate your order to the waiter (we’re thinking about a tasty burrito), who delivers your order to the kitchen, and then brings you your food. In this analogy, the menu is the API documentation that describes the food and drinks the restaurant offers – and these menu options are our API endpoints.

The physical restaurant you walk into is like the REST API. A REST API (or RESTful API) is just an API that has to conform to the specific architecture of a web application or service so that you can interact with that application successfully. In other words, you can order delicious burritos at this restaurant, but you can’t order Chinese food because the kitchen isn’t provisioned for Kung Pao Chicken.

API endpoints

To “place an order”, a developer makes an API call (or API request) that tells an application to do something, in turn, the application uses an API to ask a web server to do something. There are different types of API methods that you can send with your request that determine the type of data you are manipulating:

  • GET: Retrieves a resource

  • PATCH: Updates a resource

  • PUT: Replaces a resource

  • POST: Creates a resource

  • DELETE: Removes a resource

How do endpoints work with API?

Now we’re hungry, but we also have a basic idea of what APIs are and how they work. So, let’s talk about the role endpoints play.

Endpoints look just like any URL with a word or identifier added at the end, /endpoint.

Verification API endpoint code

The endpoint is what we want to eat. Our order may be carried back by the waiter, and prepared by the cooks, but we decide the information that is sent. Since they’ve been in the news lately, we’ll borrow Twitter’s API as an example.

We want to order a new tweet from the twitter API and can do this using their /statuses/update endpoint.

The endpoint is where the API connects with Twitter’s backend system. When we make a request to the /statuses/update endpoint, the endpoint does the work of processing the request (letting the kitchen know what we want and how to prepare it – in this case with custom text) and sending back a response. APIs let you interact with sites and Services programmatically.

Twitter's API

It may be hard to see the benefit of API endpoints when you’re only creating a single tweet but consider a scenario where you have a client that you write tweets for, and they need to go out at scheduled intervals. Using Twitter’s API would let you set this up and market for your client efficiently.

What are some API endpoint best practices?

Pretty much all SaaS and CPaaS solutions offer a REST API to their clients so that developers can integrate the product with their own software applications. To access these APIs, you need to be a customer of that company and companies will often use rate limiting to keep their API use fair. OpenAPIs also exist, which are public APIs that any developer can access.

Anytime you exchange or request data over the internet you need to be concerned about monitoring and security. The first layer of API security is an API key. API keys are generated by the application or project making the call, and they can restrict use to a specific environment or IP address region.

Securing your API endpoints

Since endpoints are doing all the heavy lifting it’s important that they stay secure, or else anyone could programmatically access and alter your data. The good news is that you secure endpoints with the same familiar methods you likely already use to secure your other online systems.

These methods include:

  1. Basic authentication/2FA

  2. Encryption

  3. OAuth 2.0

Basic security best practices apply to protecting your APIs and developer environments. If you’re looking for your Mailgun keys and credentials, you can find them here.

Monitoring your API endpoints

Because endpoints are URLs, you can – and should – monitor them to ensure they stay online. When talking about online services and websites, you’ll often hear the word “uptime”. This is the percentage of time your application stays up – in other words, the percentage of time your app is accessible and functioning. Outages and performance errors will lower your overall percentage.

Monitoring your endpoints also gives you metrics on which endpoints are being accessed and what types of API calls developers are making. This can help you track user behavior, and gain insight into which endpoints are highly trafficked so you can maintain your performance.

How you can use API endpoints with Mailgun to improve your email program

As an email service provider (ESP), Mailgun’s API support is all about programmatic solutions to make your email program more efficient and successful at scale. Our email API is a specific type of API that you can use to connect your web app or platform to an ESP to use its features within your own application.

How, you ask? The most versatile use case is sending transactional or triggered emails. You can use our API to set up automatic emails like account confirmation emails, password resets, or abandoned shopping cart reminders.

These are some of our most-used API endpoints and what they do:

API Endp­oint

Desc­rip­tion

API Endp­oint

v3/<domain>/messages

The Mes­­sages endp­­oint­ lets­ you issu­­e requ­­ests to to send­­, stor­­e, and retr­­ieve emai­­ls.

Desc­rip­tion

v3/<domain>/events

The Eve­­nts endp­­oint retr­ieves deta­­iled logs­­ on emai­l even­­ts like­ open­s, unsu­bscribes, deli­vered, fail­ed, reje­cted, etc.­

v3/domains/<domain>/webhooks

The Web­­hooks endp­­oint allo­ws you to crea­­te, acce­­ss, and dele­­te webh­­ooks prog­­rammatically that­ noti­fy you abou­t even­ts.

v3/<domain>/templates

The Tem­­plates endp­­oint, enab­les you to stor­e and acce­ss pre-­­defined emai­l temp­­lates for send­ing.

v4/address/validate

The Ema­­il Veri­­fications endp­­oint allo­ws you to veri­fy emai­l addr­esses base­d on:

  • Mail­box dete­ction
  • Synt­ax chec­ks (RFC­ defi­ned gram­mar)
  • DNS vali­dation
  • Spel­l chec­ks
  • Emai­l Serv­ice Prov­ider (ESP­) spec­ific loca­l-part gram­mar (if avai­lable)

Wrapping up

API endpoints are satisfying for big sending appetites. These process communication points make it easier to set up programmatic scripts to streamline your email program from setting up automated or transactional messaging, to retrieving metrics and data.

If you send emails frequently at scale and you’re not using an Email API tool, then your email program isn’t reaching its full potential. Managing different types of emails and transactional triggers, receiving important event notifications, and pulling metrics are all important ingredients for your growth, all made easier by APIs.

Want more content like this? That’s good, because we love to write it. Join us as we get geeky about all things email by subscribing to our newsletter.

Keep me posted! Get our news and tips every week.

Send me the newsletter. I expressly agree to receive the newsletter and know that I can easily unsubscribe at any time.

Related readings

Everything you need to know about sending email with APIs

In the world of email marketing and email technology, email APIs are a very important tool. They’re also a big part of what we do here at Mailgun. If you’re not familiar with them, APIs can be intimidating. We’ve got everything you need to know to get started.

Read more

What is a RESTful API, how it works, advantages, and examples

RESTful APIs are APIs that adhere to the six constraints of the REST architecture. In this post, we'll learn how they work, their uses, and their advantages.

Read more

Default API version now V3

The product update that announced the changes from v2 to v3 in Mailgun's API. Read more –

Read more

Popular posts

Mailgun iconSee what you can accomplish with the world's best email delivery platform. It's easy to get started.Let's get sending
CTA icon Mailgun Icon