Mailtrap

An unofficial Rust library for interacting with the Mailtrap API. This library allows you to create and send emails programmatically using Mailtrap's sending API.

Installation

Add this to your Cargo.toml:

[dependencies]
mailtrap = "0.3.1"

Usage

Here's a simple example of how to send an email:

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.

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.

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.

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

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.

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 file for details.