# Send a message

`POST https://api.mailmasker.org/api/v1/mail/send`

Send a plain-text email from your own address, or another one you may send from.

- Who can use it: Any signed-in account
- Area: Mail
- Answers 200 OK when it works
- Page: https://developer.mailmasker.org/mail-send

The message goes out from your login address unless you name another in `from`, which must be one of the addresses you may send from (see List your addresses). It goes to one recipient, as plain text.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `to` | body | yes | The one address to send it to. | `alex@example.com` |
| `subject` | body | yes | The subject line. | `Lunch on Friday?` |
| `body` | body | yes | The message, as plain text. | `Are you free at noon?` |
| `from` | body | no | Send from this address instead of your login address. It may carry a name, as in `Shop <shop@example.com>`. |  |

## Good to know

- Leaving out to, subject or body answers 400.
- A from address you may not send from is refused with 403.
- If the mail server won't take the message, the answer is 502.
- Each message sent is recorded in your activity log, with its sender, recipient and subject.

## Examples

cURL:

```bash
curl -s -X POST 'https://api.mailmasker.org/api/v1/mail/send' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"to":"alex@example.com","subject":"Lunch on Friday?","body":"Are you free at noon?"}'
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->post('https://api.mailmasker.org/api/v1/mail/send',
    { Authorization => "Bearer $ENV{TOKEN}" },
    json => { to => 'alex@example.com', subject => 'Lunch on Friday?', body => 'Are you free at noon?' })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

```bash
homelab-cli mail send --to alex@example.com --subject "Lunch on Friday?" --body "Are you free at noon?"
```

## Response

200 OK:

```json
{ "ok": true }
```