Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/yugo412/laravel-maily/llms.txt

Use this file to discover all available pages before exploring further.

All Laravel Maily configuration lives under the maily key in config/services.php. The package reads this configuration at send time — there is no separate published config file to manage. Sensitive values such as your API key are loaded from environment variables via env(), keeping credentials out of your codebase and making it straightforward to use different keys across local, staging, and production environments.

​
services.php

Add the following block to your config/services.php file: 
'maily' => [
    'key' => env('MAILY_KEY'),
    'endpoint' => env('MAILY_ENDPOINT', 'https://maily.id'),
    'timeout' => (int) env('MAILY_TIMEOUT', 15),
    'retry' => (int) env('MAILY_RETRY', 3),
    'retry_delay' => (int) env('MAILY_RETRY_DURATION', 1_000),
],

​
Environment variables

Add the following entries to your .env file. Only MAILY_KEY and MAIL_MAILER are strictly required; the remaining variables have sensible defaults and can be omitted until you need to tune them. 
MAIL_MAILER=maily

MAILY_KEY=ml_live_your_api_key_here

# optional
MAILY_ENDPOINT=https://maily.id
MAILY_TIMEOUT=15
MAILY_RETRY=3
MAILY_RETRY_DURATION=1000
Never commit your .env file or your raw API key to version control. Ensure .env is listed in your .gitignore and use environment-specific secret management (e.g. Laravel Forge environment variables, AWS Secrets Manager, or Doppler) for production deployments.

​
Configuration reference

​
MAILY_KEY
string
required
Your Maily API key. Obtain this from the Maily.id dashboard after creating an account. The key is passed to the API via the X-API-Key request header on every send call.
​
MAILY_ENDPOINT
string
default:"https://maily.id"
Base URL for the Maily REST API. Override this if you are targeting a staging or self-hosted Maily instance. The transport appends /api/v1/emails/send to this value when making requests.
​
MAILY_TIMEOUT
integer
default:"15"
Maximum number of seconds to wait for an HTTP response from the Maily API before the request is considered to have timed out. Increase this value on slow network links; decrease it for stricter latency budgets.
​
MAILY_RETRY
integer
default:"3"
Maximum number of times the request will be attempted when a connection-level failure is detected. A value of 3 means up to three total attempts. Set to 0 to disable retries entirely.
​
MAILY_RETRY_DURATION
integer
default:"1000"
Delay in milliseconds between retry attempts. The default of 1000 introduces a one-second pause between each attempt to give transient network issues time to resolve before trying again.

​
Retry behavior

Retries are handled exclusively for connection-level failures. If the Maily API returns an HTTP error response (4xx or 5xx), no retry is attempted — a MailyTransportException is thrown immediately. Retries only trigger when Laravel’s HTTP client raises a ConnectionException, which represents a failure to establish or maintain the TCP connection itself. This prevents hammering the API with repeated requests when the failure is on the server side rather than the network. The retry logic is implemented in MailyTransport using Laravel’s built-in Http::retry() with throw: false. The times parameter controls the maximum number of total attempts. When throw: false is set, ConnectionException is suppressed during intermediate attempts, but is still re-thrown once all attempts are exhausted: 
->retry(
    times: config('services.maily.retry', 0),
    sleepMilliseconds: config('services.maily.retry_delay', 1_000),
    throw: false,
    when: function (Exception $exception): bool {
        return $exception instanceof ConnectionException;
    },
)
If every retry attempt fails due to a ConnectionException, the transport catches the final exception and throws a MailyTransportException with the message "Could not connect to the Maily API.", which Laravel’s mailer will surface to your application as a standard send failure.

Build docs developers (and LLMs) love

Get started for freeTalk to us