# gabriaum/email-service-api architecture

> Architecture diagram of the GitHub repository gabriaum/email-service-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gabriaum/email-service-api
- Repository: https://github.com/gabriaum/email-service-api

## Overview

This is a Spring HTTP email-sending service. A client posts recipient, subject, and body to the mail endpoint; the controller delegates to the application service, which tries configured providers in order, fails over on availability errors, and returns provider/attempt metadata. Functional rejections stop failover and are translated to API errors. The README also documents SendGrid and Mailgun integrations and fallback configuration. Provider-to-service wiring and SendGrid’s outbound request details are not shown in excerpts, so those links are marked unverified.

Main entry points: [`src/main/java/com/gabriaum/uber/application/service/MailSenderService.java`](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/application/service/MailSenderService.java) (Failover service), [`src/main/java/com/gabriaum/uber/infra/web/MailSenderController.java`](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/web/MailSenderController.java) (Mail endpoint), [`src/main/java/com/gabriaum/uber/infra/provider/SendGridProvider.java`](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/provider/SendGridProvider.java) (SendGrid provider), [`src/main/java/com/gabriaum/uber/infra/provider/MailGunProvider.java`](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/provider/MailGunProvider.java) (Mailgun provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_mail_controller["Mail endpoint"]
  node_health["Health endpoint"]
  node_exception_handler["API error mapping"]
end

subgraph group_application["Mail orchestration"]
  node_mail_service["Failover service"]
  node_in_port["Send service port"]
  node_out_port["Provider port<br/>[IMailSend.java]"]
end

subgraph group_providers["Provider integrations"]
  node_sendgrid["SendGrid provider"]
  node_mailgun["Mailgun provider"]
end

subgraph group_domain["Mail contracts and errors"]
  node_email_dto["Email request<br/>[EmailDTO.java]"]
  node_response_dto["Send response"]
  node_exceptions["Mail exceptions"]
end

node_client(("API client"))
node_sendgrid_service{{"SendGrid"}}
node_mailgun_service{{"Mailgun API"}}

node_client -->|"posts email"| node_mail_controller
node_mail_controller -->|"accepts"| node_email_dto
node_mail_controller -->|"delegates to"| node_in_port
node_mail_service -->|"implements"| node_in_port
node_mail_service -->|"dispatches through"| node_out_port
node_mail_service -.->|"tries in order"| node_sendgrid
node_mail_service -.->|"fails over"| node_mailgun
node_sendgrid -->|"implements"| node_out_port
node_mailgun -->|"implements"| node_out_port
node_sendgrid -.->|"sends via"| node_sendgrid_service
node_mailgun -->|"posts to"| node_mailgun_service
node_mail_service -->|"reads"| node_email_dto
node_mail_service -->|"returns"| node_response_dto
node_mail_controller -->|"returns"| node_response_dto
node_mail_service -->|"throws"| node_exceptions
node_exception_handler -->|"maps errors"| node_exceptions
node_mail_controller -->|"returns response"| node_client

click node_mail_controller "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/web/MailSenderController.java"
click node_health "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/web/HealthController.java"
click node_exception_handler "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/web/MailApiExceptionHandler.java"
click node_mail_service "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/application/service/MailSenderService.java"
click node_in_port "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/application/port/in/IMailSenderService.java"
click node_out_port "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/application/port/out/IMailSend.java"
click node_sendgrid "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/provider/SendGridProvider.java"
click node_mailgun "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/provider/MailGunProvider.java"
click node_email_dto "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/domain/model/EmailDTO.java"
click node_response_dto "https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/web/dto/MailSendResponseDTO.java"
click node_exceptions "https://github.com/gabriaum/email-service-api/tree/master/src/main/java/com/gabriaum/uber/domain/exception"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mail_controller,node_health,node_exception_handler,node_client toneBlue
class node_mail_service,node_in_port,node_out_port toneAmber
class node_sendgrid,node_mailgun,node_mailgun_service toneMint
class node_email_dto,node_response_dto,node_exceptions toneRose
class node_sendgrid_service toneIndigo
```

## Components

### HTTP API

- [Mail endpoint](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/web/MailSenderController.java): `src/main/java/com/gabriaum/uber/infra/web/MailSenderController.java`
- [Health endpoint](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/web/HealthController.java): `src/main/java/com/gabriaum/uber/infra/web/HealthController.java`
- [API error mapping](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/web/MailApiExceptionHandler.java): `src/main/java/com/gabriaum/uber/infra/web/MailApiExceptionHandler.java`

### Mail orchestration

- [Failover service](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/application/service/MailSenderService.java): `src/main/java/com/gabriaum/uber/application/service/MailSenderService.java`
- [Send service port](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/application/port/in/IMailSenderService.java): `src/main/java/com/gabriaum/uber/application/port/in/IMailSenderService.java`
- [Provider port](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/application/port/out/IMailSend.java): `src/main/java/com/gabriaum/uber/application/port/out/IMailSend.java`

### Provider integrations

- [SendGrid provider](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/provider/SendGridProvider.java): `src/main/java/com/gabriaum/uber/infra/provider/SendGridProvider.java`
- [Mailgun provider](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/provider/MailGunProvider.java): `src/main/java/com/gabriaum/uber/infra/provider/MailGunProvider.java`

### Mail contracts and errors

- [Email request](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/domain/model/EmailDTO.java): `src/main/java/com/gabriaum/uber/domain/model/EmailDTO.java`
- [Send response](https://github.com/gabriaum/email-service-api/blob/master/src/main/java/com/gabriaum/uber/infra/web/dto/MailSendResponseDTO.java): `src/main/java/com/gabriaum/uber/infra/web/dto/MailSendResponseDTO.java`
- [Mail exceptions](https://github.com/gabriaum/email-service-api/tree/master/src/main/java/com/gabriaum/uber/domain/exception): `src/main/java/com/gabriaum/uber/domain/exception`

### Other components

- **API client**
- **SendGrid**
- **Mailgun API**

## Connections

- API client → Mail endpoint: posts email (evidence: `README.md`)
- Mail endpoint → Email request: accepts (evidence: `src/main/java/com/gabriaum/uber/infra/web/MailSenderController.java`)
- Mail endpoint → Send service port: delegates to (evidence: `src/main/java/com/gabriaum/uber/infra/web/MailSenderController.java`)
- Failover service → Send service port: implements (evidence: `src/main/java/com/gabriaum/uber/application/service/MailSenderService.java`)
- Failover service → Provider port: dispatches through (evidence: `src/main/java/com/gabriaum/uber/application/service/MailSenderService.java`)
- Failover service → SendGrid provider: tries in order (evidence: `README.md`)
- Failover service → Mailgun provider: fails over (evidence: `README.md`)
- SendGrid provider → Provider port: implements (evidence: `src/main/java/com/gabriaum/uber/infra/provider/SendGridProvider.java`)
- Mailgun provider → Provider port: implements (evidence: `src/main/java/com/gabriaum/uber/infra/provider/MailGunProvider.java`)
- SendGrid provider → SendGrid: sends via (evidence: `README.md`)
- Mailgun provider → Mailgun API: posts to (evidence: `src/main/java/com/gabriaum/uber/infra/provider/MailGunProvider.java`)
- Failover service → Email request: reads (evidence: `src/main/java/com/gabriaum/uber/application/service/MailSenderService.java`)
- Failover service → Send response: returns (evidence: `src/main/java/com/gabriaum/uber/application/service/MailSenderService.java`)
- Mail endpoint → Send response: returns (evidence: `src/main/java/com/gabriaum/uber/infra/web/MailSenderController.java`)
- Failover service → Mail exceptions: throws (evidence: `src/main/java/com/gabriaum/uber/application/service/MailSenderService.java`)
- API error mapping → Mail exceptions: maps errors (evidence: `src/main/java/com/gabriaum/uber/infra/web/MailApiExceptionHandler.java`)
- Mail endpoint → API client: returns response (evidence: `src/main/java/com/gabriaum/uber/infra/web/MailSenderController.java`)