### Go Installation: go get maileroo-go-sdk Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Install the Maileroo Go SDK using the go get command. ```bash go get github.com/maileroo/maileroo-go-sdk ``` -------------------------------- ### Sample Response for Get a Domain Source: https://maileroo.com/docs/api-reference/domains/get Example 200 OK response showing the domain object with DNS records, settings, and statistics. ```json { "data": { "id": 123, "user_id": 12345, "domain_name": "example.com", "dns_records": { "dkim_record": { "host": "smtp._domainkey.example.com", "record": "v=DKIM1; ...", "cname_fallback": "", "created": true }, "spf_record": { "host": "example.com", "record": "v=spf1 include:spf.maileroo.com ~all", "created": true }, "dmarc_record": { "host": "_dmarc.example.com", "record": "v=DMARC1; p=none", "created": false }, "mx_record": { "host": "example.com", "record": "mx.maileroo.com", "priority": 10, "created": false }, "tracking_record": { "host": "track.example.com", "record": "tracking.maileroo.com", "created": false } }, "sandbox": false, "free": false, "interaction_tracking": true, "custom_hostname_tracking": false, "return_path": "bounces", "status": true, "statistics": { "delivered": 100, "bounced": 2, "opened": 60, "clicked": 18 } } } ``` -------------------------------- ### Sample Response for Get Domain Settings Source: https://maileroo.com/docs/api-reference/domain-settings/get Example 200 OK response showing the domain's tracking settings: interaction_tracking, custom_hostname_tracking, and return_path. ```json { "data": { "interaction_tracking": true, "custom_hostname_tracking": false, "return_path": "bounces" } } ``` -------------------------------- ### Install Node.js SDK with npm Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Install the Maileroo Node.js SDK using npm. ```bash npm install maileroo-sdk ``` -------------------------------- ### Install .NET SDK with dotnet add package Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Install the Maileroo .NET SDK using the dotnet CLI. ```bash dotnet add package Maileroo.DotNet.SDK ``` -------------------------------- ### Install PHP SDK with Composer Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Install the Maileroo PHP SDK using Composer. ```bash composer require maileroo/maileroo-php-sdk ``` -------------------------------- ### Sample Response: GET /v1/email-testing Source: https://maileroo.com/docs/api-reference/email-testing/account/get-overview Example JSON response wrapped in a data object. Shows enabled status, SMTP and MX hosts, plan details, limits, and availability. ```json { "data": { "enabled": true, "smtp_host": "smtp.sandbox.maileroo.io", "mx_host": "mx.sandbox.maileroo.io", "plan_id": 12, "limits": {}, "limits_source": "plan", "plan_name": "Growth", "available": true } } ``` -------------------------------- ### Install Python SDK with pip Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Install the Maileroo Python SDK using pip. ```bash pip install maileroo ``` -------------------------------- ### Sample Response for List Sending Keys Source: https://maileroo.com/docs/api-reference/domain-sending-keys/list Example JSON response returned by the GET /v1/domains/:domain_id/sending-keys endpoint. Shows an array of sending key objects with id, name, and sending_key fields. ```json { "data": [ { "id": 77, "name": "Production key", "sending_key": "roo_..." } ] } ``` -------------------------------- ### Get Action - Sample Response Source: https://maileroo.com/docs/api-reference/email-testing/actions/get-action Example JSON response for a successful Get Action request. The response is wrapped in a data object and includes the action ID, message ID, type, status, links, and timestamps. ```json { "data": { "id": "2a8e74f9-aac3-43e8-855a-0b3d61e85744", "message_id": "d5949378-3069-4d8f-a8f3-6e5edf5d6060", "type": "click", "status": "succeeded", "links": [], "created_at": "2025-01-01T12:00:00Z", "finished_at": "2025-01-01T12:00:01Z" } } ``` -------------------------------- ### Sample Response for GET /v1/statistics/summary Source: https://maileroo.com/docs/api-reference/statistics/summary Example 200 OK response body for the statistics summary endpoint. Contains aggregate counts (delivered, bounced, opens, clicks, suppressions) and per-country open/click data. ```json { "data": { "aggregate": { "delivered": 1200, "bounced": 15, "opens": 800, "clicks": 240, "suppressions": 5 }, "country_data": { "US": { "opens": 500, "clicks": 150 }, "GB": { "opens": 120, "clicks": 30 } } } } ``` -------------------------------- ### Sample Response: Get Sender Profile Source: https://maileroo.com/docs/api-reference/otp-verification/sender-profiles/get Example JSON response returned with a 200 OK status. Contains the sender profile details including id, name, enabled channels, rate limit, and timestamps. ```json { "data": { "id": "prf_0123456789abcdef01234567", "name": "Acme login", "enabled_channels": ["sms", "voice"], "rate_limit": { "max": 5, "window_seconds": 60, "scope": "destination" }, "created_at": "2025-01-01T12:00:00Z", "updated_at": "2025-01-01T12:00:00Z" } } ``` -------------------------------- ### Sample Response for Get Domain Source: https://maileroo.com/docs/api-reference/email-testing/domains/get Example JSON response from the Get Domain endpoint. The response is wrapped in a `data` object and includes domain details such as ID, name, status, and MX records. ```json { "data": { "id": "289b7d13-d135-45fc-8ab6-02f7abf11d6a", "account_id": "12345", "name": "test.example.com", "status": "verified", "mx_hostname": "mx.sandbox.maileroo.io", "observed_mx": [ "mx.sandbox.maileroo.io" ], "last_checked_at": "2025-01-01T12:00:00Z", "created_at": "2025-01-01T12:00:00Z" } } ``` -------------------------------- ### Rendered output of example template Source: https://maileroo.com/docs/api-reference/emails/template-engine The output when the example template is processed with the provided template_data. ```text Hello John DOE, Your account is active! - Order #101: $12.5 - Order #102: $21 ``` -------------------------------- ### Sample response Source: https://maileroo.com/docs/api-reference/suppressions/delete Example 200 OK response returned after a successful deletion. ```json { "data": null } ``` -------------------------------- ### Install Laravel Transport with Composer Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Install the Maileroo Laravel Transport package using Composer. ```bash composer require maileroo/maileroo-laravel-transport ``` -------------------------------- ### Authentication Example Source: https://maileroo.com/docs/api-reference/account/introduction Shows how to authenticate requests to the Account API using a Bearer token in the Authorization header. ```APIDOC ## Authentication ### Description Every request must be authenticated with an API key supplied as a Bearer token in the Authorization header. ### Method GET ### Endpoint /v1/account ### Headers - **Authorization** (string) - Required - Bearer token with the API key. ### Request Example ```http GET /v1/account HTTP/1.1 Host: api.maileroo.com Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` ### Response #### Success Response (200) - **data** (object) - The response payload wrapped in a top-level data object. #### Response Example ```json { "data": { "user_id": 12345, "name": "Jane Doe", "email": "jane@example.com" } } ``` ``` -------------------------------- ### Authenticate with cURL Source: https://maileroo.com/docs/api-reference/account/introduction Example of an authenticated request using the cURL command-line tool. ```bash curl https://api.maileroo.com/v1/account \ -H "Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` -------------------------------- ### Get Analysis Response Source: https://maileroo.com/docs/api-reference/email-testing/analysis-and-previews/get-analysis Example response from the Get Analysis endpoint. Shows authentication, reputation, accessibility, unsubscribe, and optional AI analysis fields. The response is wrapped in a `data` object. ```json { "data": { "id": "an_0f5e8e3d-7b6a-4d59-8c21-439bf450a1d2", "account_id": "12345", "message_id": "d5949378-3069-4d8f-a8f3-6e5edf5d6060", "status": "complete", "rspamd": { "status": "ok", "score": -1.2, "action": "no action" }, "authentication": { "spf": { "status": "pass" }, "dkim": { "status": "pass" }, "dmarc": { "status": "pass" }, "arc": { "status": "none" }, "aligned": true }, "unsubscribe": { "valid": true }, "accessibility": { "score": 92 }, "updated_at": "2025-01-01T12:00:00Z" } } ``` -------------------------------- ### Node.js Quick Start - Send Basic Email Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Initialize the Maileroo client and send a basic email using the Node.js SDK. Uses async/await and imports MailerooClient, EmailAddress, and Attachment. ```javascript import {MailerooClient, EmailAddress, Attachment} from "maileroo-sdk"; const client = new MailerooClient("your-api-key"); const referenceId = await client.sendBasicEmail({ from: new EmailAddress("sender@example.com", "Sender Name"), to: [new EmailAddress("recipient@example.com", "Recipient Name")], subject: "Hello from Maileroo!", html: "

Hello World!

This is a test email.

", plain: "Hello World! This is a test email." }); console.log("Email sent with reference ID:", referenceId); ``` -------------------------------- ### Authenticate with HTTP Authorization Header Source: https://maileroo.com/docs/api-reference/account/introduction Example of an authenticated GET request using the Authorization header with a Bearer token. ```http GET /v1/account HTTP/1.1 Host: api.maileroo.com Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` -------------------------------- ### Sample Response for Get Application Source: https://maileroo.com/docs/api-reference/applications/get This JSON object represents a successful 200 OK response containing the full details of an application. ```json { "data": { "id": 10, "name": "My App", "smtp_username": "app10", "smtp_password": "...", "sending_key": "roo_...", "authorized_domains": [ { "domain_id": 123, "domain_name": "example.com" } ], "ip_allowlist": [ { "ip_block": "203.0.113.0/24" } ], "local_part_list": ["hello", "noreply"], "allowed_recipient_domains": ["gmail.com", "example.org"], "outbound_ips": [], "notes": "" } } ``` -------------------------------- ### Get Inbox - Sample Response Source: https://maileroo.com/docs/api-reference/email-testing/inboxes/get Example JSON response wrapped in a `data` object, showing the inbox details such as id, address, kind, and timestamps. ```json { "data": { "id": "35a3cb89-ea59-4ea3-8edc-a5c5f7bf0bda", "account_id": "12345", "domain_id": "sandbox", "local_part": "inbox", "address": "inbox@sandbox.maileroo.net", "kind": "permanent", "smtp_response": "accept", "invisible": false, "expires_at": null, "created_at": "2025-01-01T12:00:00Z" } } ``` -------------------------------- ### Sample Response for List Applications Source: https://maileroo.com/docs/api-reference/applications/list A successful 200 OK response containing the list of applications and pagination metadata. ```json { "data": { "applications": [ { "id": 10, "name": "My App", "smtp_username": "app10", "smtp_password": "...", "sending_key": "roo_...", "authorized_domain_count": 2, "ip_block_count": 1, "outbound_ip_count": 0, "notes": "" } ], "total": 1, "page": 1, "per_page": 25, "total_pages": 1 } } ``` -------------------------------- ### Send email with Upyo Maileroo transport Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Quick start example showing how to create and send a message using the Maileroo transport from @upyo/maileroo. Requires a Maileroo sending API key. ```javascript import { createMessage } from "@upyo/core"; import { MailerooTransport } from "@upyo/maileroo"; const transport = new MailerooTransport({ apiKey: "your-maileroo-sending-key", }); const message = createMessage({ from: "support@example.com", to: "customer@example.com", subject: "Welcome to our service", content: { text: "Thank you for signing up!" }, }); const receipt = await transport.send(message); if (receipt.successful) { console.log("Message sent with ID:", receipt.messageId); } else { console.error("Send failed:", receipt.errorMessages.join(", ")); } ``` -------------------------------- ### .NET Quick Start - Send Basic Email Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Initialize the Maileroo client and send a basic email using the .NET SDK. Uses a dictionary payload and handles exceptions. ```csharp var apiKey = "YOUR_API_KEY"; var client = new MailerooClient(apiKey); var from = new EmailAddress("sender@example.com", "Your Company"); var to = new EmailAddress("example@example.com", "John Doe"); try { var payload = new Dictionary { ["from"] = from, ["to"] = new List { to }, ["subject"] = "Hello from Maileroo .NET 6", ["html"] = "

Hello World

This came from the C# SDK test.

", ["plain"] = "Hello World (plain text fallback)", }; var refId = await client.SendBasicEmailAsync(payload); Console.WriteLine($"Email queued! Reference ID: {refId}"); } catch (Exception ex) { Console.WriteLine("Error: " + ex.Message); } ``` -------------------------------- ### Sample Response: 200 OK Source: https://maileroo.com/docs/api-reference/logs/search Example response showing a successful search result with an item containing message details, tags, and events. The response includes pagination fields. ```json { "data": { "items": [ { "message_id": "0123abcd@maileroo.com", "reference_id": "ref-9", "subject": "Welcome", "sender": "noreply@example.com", "recipients": ["user@example.com"], "tags": [ { "name": "campaign", "value": "welcome" } ], "events": [ { "event_type": "delivered", "timestamp": 1751000000, "message": "250 OK", "data": {} } ], "datetime": "2026-06-28T10:00:00Z" } ], "page": 1, "has_more": false } } ``` -------------------------------- ### Add Domain - Sample Response Source: https://maileroo.com/docs/api-reference/email-testing/domains/add Example JSON response wrapped in a data object. Shows a pending domain with its id, account_id, name, and MX hostname. ```json { "data": { "id": "289b7d13-d135-45fc-8ab6-02f7abf11d6a", "account_id": "12345", "name": "test.example.com", "status": "pending", "mx_hostname": "mx.sandbox.maileroo.io", "observed_mx": [], "last_checked_at": null, "created_at": "2025-01-01T12:00:00Z" } } ``` -------------------------------- ### List Verifications - Sample Response (JSON) Source: https://maileroo.com/docs/api-reference/otp-verification/verifications/list Example response showing the structure of the list data. Items are returned under data.items, with next_cursor null when there is no next page. The response includes three items with different statuses. ```json { "data": { "items": [ { "id": "vrf_1123456789abcdef01234567", "account_id": "12345", "sender_profile_id": "prf_0123456789abcdef01234567", "channel": "sms", "to": "+61412345678", "country": "AU", "code_length": 6, "status": "pending", "attempts": 0, "max_attempts": 3, "created_at": "2025-01-01T12:03:00Z", "expires_at": "2025-01-01T12:18:00Z", "cost": { "channel": null, "maileroo": "0.000000" } }, { "id": "vrf_0123456789abcdef01234567", "account_id": "12345", "sender_profile_id": "prf_0123456789abcdef01234567", "channel": "sms", "to": "+61412345678", "country": "AU", "code_length": 6, "status": "verified", "attempts": 1, "max_attempts": 3, "created_at": "2025-01-01T12:00:00Z", "expires_at": "2025-01-01T12:15:00Z", "verified_at": "2025-01-01T12:02:00Z", "cost": { "channel": "0.055000", "maileroo": "0.030000" } }, { "id": "vrf_2123456789abcdef01234567", "account_id": "12345", "sender_profile_id": "prf_0123456789abcdef01234567", "channel": "sms", "to": "+61412345678", "country": "AU", "code_length": 6, "status": "cancelled", "attempts": 0, "max_attempts": 3, "created_at": "2025-01-01T11:58:00Z", "expires_at": "2025-01-01T12:13:00Z", "cost": { "channel": "0.055000", "maileroo": "0.000000" } } ], "next_cursor": null, "total": 3 } } ``` -------------------------------- ### Sample Response for Get SMTP Sink Credential Source: https://maileroo.com/docs/api-reference/email-testing/smtp-sink-credentials/get Example JSON response returned by the API. The response is wrapped in a data object and includes the credential details such as id, account_id, username, host, port, status, and created_at. ```json { "data": { "id": "19af8047-b6aa-4a0e-85aa-22bd4a734114", "account_id": "12345", "username": "a1b2c3d4e5f6", "host": "smtp.sandbox.maileroo.io", "port": 587, "status": "active", "created_at": "2025-01-01T12:00:00Z" } } ``` -------------------------------- ### Go Quick Start: Send Basic Email with maileroo-go-sdk Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Create a Maileroo client and send a basic email with HTML and plain text content. Requires a valid API key and email addresses. ```go client, err := maileroo.NewClient("your-api-key", 30) if err != nil { log.Fatalf("Failed to create client: %v", err) } htmlContent := "

Test Email

This is a test email from the Maileroo Go SDK.

" plainContent := "Test Email\n\nThis is a test email from the Maileroo Go SDK." referenceId, err := client.SendBasicEmail(context.Background(), maileroo.BasicEmailData{ From: maileroo.NewEmail("YOUR_EMAIL_ADDRESS", "Your Name"), To: []maileroo.EmailAddress{ maileroo.NewEmail("RECIPIENT_EMAIL_ADDRESS", "Recipient Name"), }, Cc: []maileroo.EmailAddress{ maileroo.NewEmail("CC_EMAIL_ADDRESS", "CC Name"), }, Subject: "Test Email from Maileroo Go SDK", HTML: &htmlContent, Plain: &plainContent, }) if err != nil { log.Fatalf("Failed to send email: %v", err) } log.Printf("Email sent with reference ID: %s", referenceId) ``` -------------------------------- ### Sample Response: Get Coverage Source: https://maileroo.com/docs/api-reference/email-testing/analysis-and-previews/get-coverage Example JSON response wrapped in a `data` object. It includes the message ID, a score, client-specific light/dark status, warnings, and size information. The `gmail_clip` field indicates whether Gmail clipping is detected. ```json { "data": { "message_id": "d5949378-3069-4d8f-a8f3-6e5edf5d6060", "score": 1, "clients": [ { "client": "inbox", "light": "ready", "dark": "ready" } ], "warnings": ["gmail_clip"], "gmail_clip": true, "size_bytes": 148213 } } ``` -------------------------------- ### Python Quick Start - Send Basic Email Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Initialize the Maileroo client and send a basic email using the Python SDK. Uses send_basic_email method and EmailAddress for sender and recipient. ```python from maileroo import MailerooClient, EmailAddress # Initialize the client client = MailerooClient("your-api-key") # Send a basic email reference_id = client.send_basic_email({ "from": EmailAddress("sender@example.com", "Sender Name"), "to": [EmailAddress("recipient@example.com", "Recipient Name")], "subject": "Hello from Maileroo!", "html": "

Hello World!

This is a test email.

", "plain": "Hello World! This is a test email." }) print("Email sent with reference ID:", reference_id) ``` -------------------------------- ### Install Upyo Maileroo transport Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Install the @upyo/maileroo package using npm. ```bash npm add @upyo/maileroo ``` -------------------------------- ### PHP Quick Start - Send Basic Email Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Initialize the Maileroo client and send a basic email using the PHP SDK. Requires an API key and uses EmailAddress for sender and recipient. ```php sendBasicEmail([ 'from' => new EmailAddress('sender@example.com', 'Sender Name'), 'to' => [new EmailAddress('recipient@example.com', 'Recipient Name')], 'subject' => 'Hello from Maileroo!', 'html' => '

Hello World!

This is a test email.

', 'plain' => 'Hello World! This is a test email.' ]); echo "Email sent with reference ID: " . $reference_id; ``` -------------------------------- ### Sample Response: List Domains Source: https://maileroo.com/docs/api-reference/domains/list Example JSON response from the List Domains endpoint, showing a domain with statistics and pagination fields. ```json { "data": { "domains": [ { "id": 123, "domain_name": "example.com", "statistics": { "delivered": 100, "bounced": 2, "opened": 60, "clicked": 18 }, "status": true } ], "total": 1, "page": 1, "per_page": 25, "total_pages": 1 } } ``` -------------------------------- ### Create an Application Request Source: https://maileroo.com/docs/api-reference/applications/create A sample POST request to create a new application with specified name, authorized domains, IP allowlist, and other optional configurations. ```http POST https://api.maileroo.com/v1/applications Content-Type: application/json { "name": "My App", "authorized_domains": [123], "ip_allowlist": ["203.0.113.0/24"], "local_part_list": ["hello", "noreply"], "allowed_recipient_domains": ["gmail.com", "example.org"], "outbound_ips": [], "notes": "" } ``` -------------------------------- ### Webhook event envelope JSON example Source: https://maileroo.com/docs/api-reference/otp-verification/webhooks/getting-started Example JSON envelope for a webhook event. The `data` object is the public verification object and does not contain the generated code or cost. The `max_attempts` value shown is an example; the event reports the applicable value. ```json { "id": "evt_0123456789abcdef01234567", "type": "verification.created", "created_at": "2025-01-01T12:00:00Z", "data": { "id": "vrf_0123456789abcdef01234567", "account_id": "12345", "sender_profile_id": "prf_0123456789abcdef01234567", "channel": "sms", "to": "+61412345678", "country": "AU", "code_length": 6, "status": "pending", "attempts": 0, "max_attempts": 3, "expires_at": "2025-01-01T12:15:00Z", "created_at": "2025-01-01T12:00:00Z", "updated_at": "2025-01-01T12:00:00Z" } } ``` -------------------------------- ### Java Quick Start: Send Basic Email with maileroo-java-sdk Source: https://maileroo.com/docs/api-reference/emails/libraries-and-sdks Create a Maileroo client and send a basic email with HTML and plain text content. Requires a valid API key and email addresses. ```java import com.maileroo.*; import java.time.Duration; import java.util.HashMap; import java.util.Map; public class Main { public static void main(String[] args) throws Exception { MailerooClient client = new MailerooClient("your-api-key", Duration.ofSeconds(30)); Map email = new HashMap<>(); email.put("from", new EmailAddress("sender@example.com", "Sender")); email.put("to", new EmailAddress("recipient@example.com", "Recipient")); email.put("subject", "Hello from Maileroo!"); email.put("html", "

Hello World!

This is a test email.

"); email.put("plain", "Hello World! This is a test email."); String refId = client.sendBasicEmail(email); System.out.println("Email sent with reference ID: " + refId); } } ``` -------------------------------- ### Webhook Payload Examples Source: https://maileroo.com/docs/api-reference/emails/webhooks Examples of Maileroo webhook payloads for each event type, showing the JSON structure and fields. ```APIDOC ## Webhook Payloads Maileroo webhook payloads are sent in JSON format. They contain detailed information about each event, including: - **Event Type**: Indicates the type of email event (e.g., delivered, opened). - **Message Details**: Includes IDs, timestamps, email addresses, and other relevant data. ### Accepted ```json { "domain_id": 456, "event_data": { "from": ["sender@examplemail.com"], "to": ["receiver@examplemail.com"] }, "event_id": "mnop1234qrst5678uvwx9101", "event_time": 1710545560, "event_type": "accepted", "inserted_at": "2024-03-15T23:32:40.441Z", "message_id": "<0987654321fedcba@examplemail.com>", "message_reference_id": "mref0987654321fedcba", "tags": null, "user_id": 1002 } ``` ### Delivered ```json { "domain_id": 123, "event_data": { "to": "receiver@examplemail.com" }, "event_id": "abcd1234efgh5678ijkl9101", "event_time": 1710545542, "event_type": "delivered", "inserted_at": "2024-03-15T23:32:22.397Z", "message_id": "<1234567890abcdef@examplemail.com>", "message_reference_id": "mref1234567890abcdef", "tags": null, "user_id": 1001 } ``` ### Opened ```json { "domain_id": 789, "event_data": { "ip": "123.45.67.89", "user_agent": "Mozilla/5.0 (Compatible; ExampleBrowser/1.0; Windows NT)" }, "event_id": "ghij1234klmn5678opqr9101", "event_time": 1710545567, "event_type": "opened", "inserted_at": "2024-03-15T23:32:47.664Z", "message_id": "", "message_reference_id": "mrefabcdef1234567890", "tags": null, "user_id": 1003 } ``` ### Clicked ```json { "domain_id": 774, "event_data": { "ip": "103.120.6.123", "original_url": "https://example.com/confirm/link", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 Edg/122.0.0.0" }, "event_id": "cb91d71458a75cb7160a2cca9c472a42a97bf925385998e0", "event_time": 1710545577, "event_type": "clicked", "inserted_at": "2024-03-15T23:32:57.401Z", "message_id": "<499840827041934075286474.8057.2024315233239@domain.com>", "message_reference_id": "0ed7094bf9509ac3145c4aa97182be44", "tags": null, "user_id": 323 } ``` ### Deferred ```json { "domain_id": 123, "event_data": { "reason": "452-4.2.2 The recipient's inbox is out of storage space. Please direct the recipient to support link.", "to": "example@email.com" }, "event_id": "0dc2204928b817f0122d1e311aee0ee702ac378840ef7df5", "event_time": 1710545557, "event_type": "deferred", "inserted_at": "2024-03-15T23:32:37.427Z", "message_id": "<312897663424678224496834.5399.202431411321@domain.com>", "message_reference_id": "982e548d6b5ff15562272aa42b1f4517", "tags": null, "user_id": 123 } ``` ### Failed ```json { "domain_id": 123, "event_data": { "reason": "452-4.2.2 The recipient's inbox is out of storage space. Please direct the recipient to support link.", "to": "example@email.com" }, "event_id": "0dc2204928b817f0122d1e311aee0ee702ac378840ef7df5", "event_time": 1710545557, "event_type": "failed", "inserted_at": "2024-03-15T23:32:37.427Z", "message_id": "<312897663424678224496834.5399.202431411321@domain.com>", "message_reference_id": "982e548d6b5ff15562272aa42b1f4517", "tags": null, "user_id": 123 } ``` ### Complained ```json { "domain_id": 123, "event_data": { "to": "example@email.com" }, "event_id": "0dc2204928b817f0122d1e311aee0ee702ac378840ef7df5", "event_time": 1710545557, "event_type": "complained", "inserted_at": "2024-03-15T23:32:37.427Z", "message_id": "<312897663424678224496834.5399.202431411321@domain.com>", "message_reference_id": "982e548d6b5ff15562272aa42b1f4517", "tags": null, "user_id": 123 } ``` ### Rejected ```json { "domain_id": 123, "event_data": { "from": ["sender@examplemail.com"], "to": ["receiver@examplemail.com"], "reject_reason": "One or more of the recipients are on the suppression list." }, "event_id": "0dc2204928b817f0122d1e311aee0ee702ac378840ef7df5", "event_time": 1710545557, "event_type": "rejected", "inserted_at": "2024-03-15T23:32:37.427Z", "message_id": "<312897663424678224496834.5399.202431411321@domain.com>", "message_reference_id": "982e548d6b5ff15562272aa42b1f4517", "tags": null, "user_id": 123 } ``` ``` -------------------------------- ### Sample Request: GET /v1/verify/balance Source: https://maileroo.com/docs/api-reference/otp-verification/balance/get Retrieves the prepaid OTP Verification balance and rate card. Requires the scope verify.balance.read and an Authorization header with a Bearer token. ```bash curl "https://api.maileroo.com/v1/verify/balance" \ -H "Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` -------------------------------- ### Reply Artifact Example Source: https://maileroo.com/docs/api-reference/email-testing/actions/download-artifact An example of a reply artifact, which is a complete RFC 822 .eml message generated by Maileroo. ```eml From: support@example.com To: customer@example.net Subject: Re: Verify account Date: Wed, 01 Jan 2025 12:00:00 +0000 Message-ID: <2a8e74f9-aac3-43e8-855a-0b3d61e85744@email-testing.maileroo> In-Reply-To: References: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit This is an automatic reply from the email testing service. The original message was received. This reply does not include the original content. ``` -------------------------------- ### action.failed payload example Source: https://maileroo.com/docs/api-reference/email-testing/webhooks/getting-started Example JSON payload for the action.failed event, showing the event envelope and data fields including action_id, action_type, message_id, and error. ```json { "id": "evt_e50e8400e29b41d4a716446655440009", "type": "action.failed", "account_id": "12345", "created_at": "2025-01-09T12:00:00Z", "data": { "action_id": "72c9d863-8b4a-4f15-9a32-6d1e0f7b4c21", "action_type": "unsubscribe", "message_id": "d5949378-3069-4d8f-a8f3-6e5edf5d6060", "error": "The List-Unsubscribe link must use HTTPS." } } ``` -------------------------------- ### Sample response headers Source: https://maileroo.com/docs/api-reference/email-testing/messages/download-attachment Example response headers showing a 200 OK status, the attachment's media type, and a content disposition with the attachment filename. ```http HTTP/1.1 200 OK Content-Type: application/octet-stream Content-Disposition: attachment; filename="invoice.pdf" ``` -------------------------------- ### Get Inbox - cURL Request Source: https://maileroo.com/docs/api-reference/email-testing/inboxes/get Sends a GET request to retrieve a test inbox by its ID. Requires the `email_testing.inboxes.read` scope and an Authorization header with a Bearer token. ```bash curl "https://api.maileroo.com/v1/email-testing/mailboxes/35a3cb89-ea59-4ea3-8edc-a5c5f7bf0bda" \ -H "Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` -------------------------------- ### Maileroo-Signature header example Source: https://maileroo.com/docs/api-reference/otp-verification/webhooks/getting-started Example of the Maileroo-Signature header included in every webhook request. The signature is the lowercase hexadecimal HMAC-SHA256 of `.` using the webhook's secret as the key. ```http Maileroo-Signature: t=1700000000,v1= ``` -------------------------------- ### Error response example Source: https://maileroo.com/docs/otp-verification/introduction Errors use a non-2xx status and this shape. ```json { "error": { "message": "Your OTP Verification balance is too low. Add funds and try again." } } ``` -------------------------------- ### Get Account Sample Response Source: https://maileroo.com/docs/api-reference/account/get-account A successful 200 OK response containing the account's user ID, plan details, usage statistics for hourly and monthly limits, subscription status, and billing information. ```json { "data": { "user_id": 12345, "name": "Jane Doe", "email": "jane@example.com", "current_plan": { "id": 3, "name": "Pro", "quantity": 100000 }, "usage": [ { "name": "Hourly Outbound Usage", "quantity": 1000, "used": 42, "available": 958 }, { "name": "Monthly Outbound Usage", "quantity": 100000, "used": 5000, "available": 95000 }, { "name": "Monthly Inbound Usage", "quantity": 50000, "used": 1200, "available": 48800 } ], "subscription": { "status": "active", "current_period_start": "2026-06-01T00:00:00Z", "current_period_end": "2026-07-01T00:00:00Z", "cancel_at_period_end": false, "next_invoice_total": 25.0 }, "billing_information": { "name": "Jane Doe", "company_name": "Example Inc", "billing_email": "billing@example.com", "country_code": "US" } } } ``` -------------------------------- ### Successful response example Source: https://maileroo.com/docs/otp-verification/introduction Successful responses contain a top-level data property. ```json { "data": { "id": "vrf_0123456789abcdef01234567" } } ``` -------------------------------- ### Sample Response: 200 OK JSON Source: https://maileroo.com/docs/api-reference/otp-verification/verifications/get Example response for a successful verification retrieval. The max_attempts value is illustrative; the response reports the applicable value. Optional fields such as country and verified_at appear when available. cost amounts are illustrative. ```json { "data": { "id": "vrf_0123456789abcdef01234567", "account_id": "12345", "sender_profile_id": "prf_0123456789abcdef01234567", "channel": "sms", "to": "+61412345678", "country": "AU", "code_length": 6, "status": "verified", "attempts": 1, "max_attempts": 3, "expires_at": "2025-01-01T12:15:00Z", "verified_at": "2025-01-01T12:02:00Z", "created_at": "2025-01-01T12:00:00Z", "updated_at": "2025-01-01T12:02:00Z", "cost": { "channel": "0.055000", "maileroo": "0.030000" } } } ``` -------------------------------- ### Send test email with Go net/smtp Source: https://maileroo.com/docs/api-reference/email-testing/smtp-sink-credentials/getting-started Uses net/smtp to send a test email to the sandbox SMTP sink on port 587 with STARTTLS. Requires MAILEROO_SMTP_USER, MAILEROO_SMTP_PASSWORD, and MAILEROO_TEST_INBOX environment variables. ```go package main import ( "net/smtp" "os" ) func main() { host := "smtp.sandbox.maileroo.io" auth := smtp.PlainAuth("", os.Getenv("MAILEROO_SMTP_USER"), os.Getenv("MAILEROO_SMTP_PASSWORD"), host) to := os.Getenv("MAILEROO_TEST_INBOX") msg := []byte("From: sender@example.com\r\n" + "To: " + to + "\r\n" + "Subject: Email Testing\r\n" + "\r\n" + "Captured by Maileroo.\r\n") // SendMail upgrades the connection with STARTTLS before authenticating. if err := smtp.SendMail(host+":587", auth, "sender@example.com", []string{to}, msg); err != nil { panic(err) } } ``` -------------------------------- ### Sample template_data JSON Source: https://maileroo.com/docs/api-reference/emails/template-engine A sample template_data object that works with the example template. ```json { "first_name": "john", "last_name": "doe", "status": "active", "orders": [ { "id": 101, "amount": 12.50 }, { "id": 102, "amount": 21.00 } ] } ``` -------------------------------- ### Create Webhook - Sample Request Source: https://maileroo.com/docs/api-reference/email-testing/webhooks/create Use this curl command to create a webhook. It requires the `email_testing.webhooks.write` scope and a Bearer token. The request body must include a `url` and an `events` array. ```bash curl -X POST "https://api.maileroo.com/v1/email-testing/webhooks" \ -H "Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/hooks","events":["message.received"]}' ``` -------------------------------- ### Example template with variables, conditionals, and loops Source: https://maileroo.com/docs/api-reference/emails/template-engine A complete Handlebars template demonstrating variables, conditionals, and loops. Uses custom helpers like capitalize, uppercase, eq, and each. ```handlebars Hello {{capitalize first_name}} {{uppercase last_name}}, {{#if (eq status "active")}} Your account is active! {{else}} Please activate your account. {{/if}} {{#each orders}} - Order #{{id}}: ${{amount}} {{/each}} ```