# Mailtrap
An unofficial Rust library for interacting with the [Mailtrap](https://mailtrap.io) API. This library allows you to create and send emails programmatically using Mailtrap's sending API.
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
mailtrap = "0.3.1"
```
## Usage
Here's a simple example of how to send an email:
```rust,no_run
use mailtrap::Email;
#[tokio::main]
async fn main() {
let email = Email::new()
.from("sender@example.com")
.to("recipient@example.com")
.subject("Hello from Rust")
.text("This is a test email sent from Rust using the Mailtrap API.")
.category("test");
// send returns a Result<bool, Error>
// You need to provide the API endpoint and your API token.
// The API endpoint is usually "https://send.api.mailtrap.io/" for production.
let res = email.send(
None,
Some("YOUR_API_TOKEN"),
None
).await;
match res {
Ok(success) => {
if success {
println!("Email sent successfully!");
} else {
println!("Failed to send email.");
}
}
Err(e) => eprintln!("Error: {}", e),
}
}
```
## Advanced Usage
You can also send emails with HTML content, attachments, and custom headers.
```rust,no_run
use mailtrap::{Email, Attachment, Header, ContentType, Disposition};
#[tokio::main]
async fn main() {
// Create an attachment
let attachment = Attachment::new()
.content("Attachment content".as_bytes().to_vec())
.filename("test.txt")
.content_type(ContentType::Plain)
.disposition(Disposition::Attachment);
let email = Email::new()
.from("\"Sender Name\" <sender@example.com>")
.to("recipient@example.com")
.cc("cc@example.com")
.bcc("bcc@example.com")
.reply_to("reply@example.com")
.subject("Advanced Email Test")
.text("Plain text content")
.html("<h1>HTML Content</h1><p>This is an email with HTML.</p>")
.attachments(vec![attachment])
.header("X-Custom-Header", "Custom Value")
.category("integration-test");
let res = email.send(
None,
Some("YOUR_API_TOKEN"),
None
).await;
// handle response...
}
```
## Batch Sending and Templates
You can send emails to multiple recipients in a batch, and use templates with variable substitution.
```rust,no_run
use mailtrap::{BatchEmail, BatchEmailRequest};
#[tokio::main]
async fn main() {
// Create a request for a specific recipient
let request1 = BatchEmailRequest::new()
.to("recipient1@example.com")
.template_uuid("YOUR_TEMPLATE_UUID")
.template_variable("user_name", "Alice");
let request2 = BatchEmailRequest::new()
.to("recipient2@example.com")
.template_uuid("YOUR_TEMPLATE_UUID")
.template_variable("user_name", "Bob");
// Create the batch email
let batch_email = BatchEmail::new()
.from("sender@example.com")
.template_uuid("YOUR_TEMPLATE_UUID")
.request(request1)
.request(request2);
let res = batch_email.send(
None,
Some("YOUR_API_TOKEN"),
None
).await;
match res {
Ok(success) => {
if success {
println!("Batch email sent successfully!");
} else {
println!("Failed to send batch email.");
}
}
Err(e) => eprintln!("Error: {}", e),
}
}
```
## Account Access
You can manage and inspect account access permissions using the `Access` client.
```rust,no_run
use mailtrap::Access;
#[tokio::main]
async fn main() {
let access = Access::new();
let account_id = "YOUR_ACCOUNT_ID";
// list returns a Result<Vec<AccessRecord>, Error>
let res = access.list(
None, // Use default API URL
Some("YOUR_API_TOKEN"),
None, // Or use Bearer token if preferred
account_id,
None, // Optional: Filter by domain_ids
None, // Optional: Filter by inbox_ids
None // Optional: Filter by project_ids
).await;
match res {
Ok(records) => {
for record in records {
println!("Access Record: {:?}", record);
}
}
Err(e) => eprintln!("Error: {}", e),
}
}
```
### Remove Access
```rust,no_run
use mailtrap::Access;
#[tokio::main]
async fn main() {
let access = Access::new();
// remove returns a Result<AccessRemoveResponse, Error>
let res = access.remove(
None, // Use default API URL
Some("YOUR_API_TOKEN"),
None, // Or use Bearer token if preferred
"YOUR_ACCOUNT_ID",
"ACCESS_ID_TO_REMOVE"
).await;
match res {
Ok(response) => println!("Removed access with ID: {}", response.id),
Err(e) => eprintln!("Error: {}", e),
}
}
```
## Accounts
You can list all accounts available to the authenticated user using the `Accounts` client.
```rust,no_run
use mailtrap::Accounts;
#[tokio::main]
async fn main() {
let accounts_client = Accounts::new();
// list returns a Result<Vec<Account>, Error>
let res = accounts_client.list(
None, // Use default API URL
Some("YOUR_API_TOKEN"),
None, // Or use Bearer token if preferred
).await;
match res {
Ok(accounts) => {
for account in accounts {
println!("Account: ID={}, Name={}", account.id, account.name);
for level in account.access_levels {
println!(" - Access Level: {}", level);
}
}
}
Err(e) => eprintln!("Error: {}", e),
}
}
```
## Features
- **Simple Builder API**: Create emails with a fluent interface.
- **Multiple Content Types**: Support for both plain text and HTML content.
- **Attachments**: Easy support for file attachments with customizable content type and disposition.
- **Custom Headers**: Add any custom headers to your emails.
- **Batch Sending**: Send emails to multiple recipients in a single API call.
- **Templates**: Support for Mailtrap templates with variables.
- **Categories**: Tag your emails with categories for analytics.
- **Account Management**: List all accounts available to the authenticated user.
- **Access Control**: Manage and inspect account access permissions.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.