Log inSign up
std avatar
Public
Script
Fork
5 Likes
Readme

Email - Docs ↗

Send emails with std/email. You can only send emails to yourself if you're on Val Town Free. If you're on Val Town Pro, you can email anyone.

Want to receive emails instead? Create an email handler val

Basic usage

Create val
import { email } from "https://esm.town/v/std/email";

await email({ subject: "New Ink & Switch Post!",  text: "https://www.inkandswitch.com/embark/" });

subject

The email subject line. It defaults to Message from @your_username on Val Town.

to, cc, and bcc

By default, the to field is set to the owner of the Val Town account that calls it.

If you have Val Town Pro, you can send emails to anyone via the to, cc, and bcc fields.

If you don't have Val Town Pro, you can only send emails to yourself, so leave those fields blank.

from

The from is limited to a few options:

  1. It defaults to notifications@val.town if you don't specify it.

  2. If you do specify it, it must be of the form: your_username.valname@valtown.email.

replyTo

replyTo accepts a string email or an object with strings for email and name (optional).

This can be useful if you are sending emails to others with Val Town Pro.

Create val
import { email } from "https://esm.town/v/std/email";

await email({
  to: "someone_else@example.com",
  from: "your_username.valname@valtown.email",
  replyTo: "your_email@example.com",
  text: "these pretzels are making me thirsty",
});

Attachments

You can attach files to your emails by using the attachments field. Attachments need to be Base64 encoded, which is that the btoa method is doing in this example:

Create val
import { email } from "https://esm.town/v/std/email";

export const stdEmailAttachmentExample = email({
  attachments: [
    {
      content: btoa("hello attachments!"),
      filename: "test.txt",
      type: "text",
      disposition: "attachment",
    },
  ],
});

Here's an example sending a PDF.

📝 Edit docs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
import { API_URL } from "https://esm.town/v/std/API_URL";
import { parseSendGridEmail } from "https://esm.town/v/stevekrouse/parseSendGridEmail?v=8";
import { parseSendGridEmails } from "https://esm.town/v/stevekrouse/parseSendGridEmails?v=10";
/**
* Send emails. You can only send emails to yourself if
* you’re on Val Town Free. If you’re on Val Town Pro,
* you can email anyone. ([Docs ↗](https://docs.val.town/std/email))
*/
export const email = async (data: {
/**
* The email address(es) to send the email to. Only available to Val Town Pro subscribers.
* Can be a single string, IAddress object, or an array of strings/IAddress objects.
* @default the email of the logged user calling this function.
*/
to?: (IAddress | string)[] | IAddress | string;
/**
* The email address to set as the "from" address. It can only be set to username.valname@valtown.email addresses.
* Can be a string or IAddress object.
* @default notifications@val.town
*/
from?: IAddress | string;
/**
* The email address(es) to CC on the email. Only available to Val Town Pro subscribers.
* Can be a single string, IAddress object, or an array of strings/IAddress objects.
*/
cc?: (IAddress | string)[] | IAddress | string;
/**
* The email address(es) to blind carbon copy (BCC) on the email. Only available to Val Town Pro subscribers.
* Can be a single string, IAddress object, or an array of strings/IAddress objects.
*/
bcc?: (IAddress | string)[] | IAddress | string;
/**
* The subject line for the email.
*/
subject?: string;
/**
* The email address(es) to set as the "reply-to" address.
* Can be a single string, IAddress object, or an array of strings/IAddress objects.
*/
replyTo?: (IAddress | string)[] | IAddress | string;
/**
* The HTML content for the email body.
*/
html?: string;
/**
* The plain text content for the email body.
*/
text?: string;
/**
* An array of attachment data to include with the email.
*/
attachments?: AttachmentData[];
}) => {
let result = await fetch(
`${API_URL}/v1/email`,
{
method: "POST",
body: JSON.stringify({
to: parseSendGridEmails(data.to),
from: data.from && parseSendGridEmail(data.from),
cc: parseSendGridEmails(data.cc),
bcc: parseSendGridEmails(data.bcc),
replyToList: parseSendGridEmails(data.replyTo),
subject: data.subject,
html: data.html,
text: data.text,
attachments: data.attachments,
}),
headers: {
authorization: "Bearer " + Deno.env.get("valtown"),
},
},
).then(r => r.json());
if (result?.message !== "Email accepted to be sent") {
let message = result?.message ?? result?.error ?? JSON.stringify(result);
throw new Error("Val Town Email Error: " + message);
}
return result;
};
export interface IAddress {
email: string;
name?: string;
}
export interface AttachmentData {
content: string;
filename: string;
type?: string;
disposition?: string;
contentId?: string;
Val Town is a social website to write and deploy JavaScript.
Build APIs and schedule functions from your browser.
Sign up with GitHub
v12 was merged from the PR "Update JSDocs" by andreterron
Comments
3
rodesp avatar
rodesp…

Is this still what we should be using to send emails?

I noticed the type says RPC (deprecated). That makes me think we should be using something else now but the docs still link here.

std avatar
std…

Good catch! It should be a script type val. Fixed it!

rodesp avatar
rodesp…

Great, thank you!

v12
April 3, 2024