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
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.
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.
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.
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:
Encryption
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 Endpoint | Description |
|---|---|
API Endpoint | |
v3/<domain>/messages | The Messages endpoint lets you issue requests to to send, store, and retrieve emails. |
Description | |
v3/<domain>/events | The Events endpoint retrieves detailed logs on email events like opens, unsubscribes, delivered, failed, rejected, etc. |
v3/domains/<domain>/webhooks | The Webhooks endpoint allows you to create, access, and delete webhooks programmatically that notify you about events. |
v3/<domain>/templates | The Templates endpoint, enables you to store and access pre-defined email templates for sending. |
v4/address/validate | The Email Verifications endpoint allows you to verify email addresses based on:
|
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.
