Python REST API implementation for sending email

1. What a REST API is

Most web or mobile applications need to communicate with a server to read, send or transform data. In modern projects, that communication is usually solved with HTTP or HTTPS and a resource-oriented API.

REST stands out because it is a simple, well-understood approach and very suitable for scaling services where several clients consume the same backend: web, mobile, internal automations or third parties.

If this is your first time approaching this kind of architecture, it is worth remembering that today most services we use every day work with some kind of API. Social networks, video platforms, authentication systems and mobile applications depend on this model to grow and communicate.

Regarding terminology, REST means Representational State Transfer. In practice, it helps describe interfaces where clients access resources through HTTP and receive representations of those data in formats such as JSON or XML.

Another important point is that a REST service does not keep state between requests. That means the server does not automatically remember the client from one call to the next: if authentication, context or permissions are needed, the client must provide that information every time.

It may look like a disadvantage because it forces the client to resend credentials or tokens, but in reality it brings a major advantage: scalability. If the server does not need to preserve in-memory state for each user, it becomes much easier to scale horizontally and support more load.

2. SOAP vs REST

SOAP is still valid in certain enterprise environments, but its complexity is usually unnecessary for frontend-oriented web APIs, lightweight automations or simple services.

In this project, a more direct model is preferable: resources, JSON, simple authentication and easy consumption from Angular.

SOAP is designed to cover broader and more formal requirements, including complex security, transactional or messaging scenarios. That can be appropriate in some enterprise environments, but it also adds complexity that many web applications do not need.

Another important difference is the orientation of the model. SOAP is usually closer to invoking remote methods, while REST focuses on resources accessible through URIs. Instead of thinking about “calling a remote function”, we think about “operating on a resource” using GET, POST, PUT or DELETE.

For example, in a more classic service we might imagine a method like GetAll() or GetById(). In REST, by contrast, the focus is on routes like /plates or /plates/123, and the HTTP verb indicates whether we are consulting, creating, modifying or deleting information.

3. Python implementation

This guide uses Python because it allows microservices to be built quickly, the code is easy to read and there is a huge base of libraries and examples available.

The chosen language does not need to be the fastest at a low level, because here the API is not a component that requires squeezing raw performance to the maximum. What matters is moving fast, keeping the code legible and relying on mature tooling.

In that context, Python fits especially well: it is a very widespread language, with clear syntax, multiple programming paradigms and a huge availability of libraries and real examples.

Initial installation

This first block covers the minimum environment setup. Cloning the repository and loading dependencies is the previous step needed to run the API, review the code and perform local tests.

Project structure

Before going into the specific endpoints, it is worth seeing how the project is divided. This structure helps separate configuration, authentication, utilities and API resources.

3.1 Published resources

Every REST API is based on exposing resources through well-defined routes. In this example, endpoints are published to obtain a token, validate it and send protected emails.

Resource list

This fragment centralizes the available routes. It is important because it shows at a glance which resources the API exposes and which class resolves each endpoint.

When the application starts to grow, having the routes and their correspondence with each resource clearly identified avoids confusion and makes it easier for other developers to understand the API without walking through the entire project.

Simple email sending

Here the functional logic of the project already appears: a resource that receives the destination email, delegates the work to a sending class and returns a simple JSON response confirming the result.

The important point is not only sending the email, but also clearly separating the responsibility of the endpoint from the class that really executes the technical operation.

This decoupling is useful because the HTTP resource stays focused on receiving parameters and building the response, while the helper class can evolve separately if the mail provider, the library or the sending strategy changes.

In this example a Gmail account was used to simplify the flow and directly show how an API can encapsulate a useful operation for other clients.

3.2 Security and authentication

To restrict access to the sending endpoint, a token is used. The client first obtains valid credentials and then attaches that token to protected requests.

At this point a natural doubt appears: if the API exposes a resource that sends emails, how do we prevent any third party from invoking it freely? The answer is to protect access with a token associated with a previous authentication process.

In the original project, this is solved by making the sending resource inherit from a secure class responsible for validating whether the request carries an authorized token.

Login endpoint

This endpoint receives client credentials and returns a token if they are correct. It is the entry point to the rest of the protected resources of the API.

User validation

This block shows the logic that decides whether the user can authenticate. Although the example is simple, it helps explain where credential checking would live in a real project.

In the original application, this logic lives inside the login folder, where it is decided which user can enter and which information is incorporated into the access token.

Request to obtain the token

Once the server side has been covered, this example shows what the call would look like from the client or from a testing tool. The goal is to make it clear which URL, headers and payload the authentication needs.

This kind of example is especially useful when you start testing the API with Postman or when another client, such as Angular, needs to reproduce exactly the same HTTP contract.

Request to send the email

This second example represents the real use of the protected resource: the token is attached in the header and the endpoint that sends the email is invoked.

In other words, the complete flow is split into two steps: authenticate and obtain the token, then reuse that token to access the resource that performs the real business operation.

4. Testing with Postman

Postman is useful to validate the API before integrating it into Angular. It allows you to inspect headers, authentication, payloads and responses without depending on the frontend yet.

Postman is not only useful for launching manual requests. It also helps document API behavior, share tests with other team members and quickly verify whether an error comes from the backend or the client.

The normal testing flow would be: prepare the headers, send username and password to recover the token, and reuse that token in the Authorization header of the protected resource.

In practice, Postman becomes a very convenient tool for both developers and operations or monitoring profiles. It allows you to verify whether the API responds correctly before writing a single line of frontend code.

Around that testing idea, the platform also adds utilities to document collections, organize teams, share requests and work with a more API First oriented approach.

Today, Postman provides applications for Windows, Linux and macOS, in addition to collaborative cloud options. If you need to install it, you can download it from postman.com/downloads.

Its basic use is free, although there are also more advanced plans for teams that need more capacity, additional collaborative features or integration with corporate systems.

Execution example

The first step is to connect to the API and correctly prepare the HTTP request. That implies adjusting headers and format so the backend interprets the request as a valid REST call.

The second step is to send username and password to recover the token. That response confirms that the authentication process works correctly and leaves the credential ready for the rest of the calls.

Once the token has been obtained, it is incorporated into the authorization header and it is already possible to invoke the email-sending resource. That is the final confirmation that authentication and the protected endpoint are coordinated.