Email

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 email instead? Create an email handler val.

Basic usage#

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

await email({
  subject: "Hello from Val Town",
  text: "This is a test email sent from a Val Town val.",
});

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. On a Free account you can only send emails to yourself.

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:

• { email: "your_username.valname@valtown.email }" or
• { email: "your_username.valname@valtown.email", name: "Sender Name" }.

3. We will soon allow you to email from any val email address you own, but in the meantime you can get around these limitations by using the replyTo field, or using another email library like Resend

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.

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

await email({
  to: "someone_else@example.com",
  replyTo: "your_custom_email@valtown.email",
  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 what the btoa method is doing in this example:

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",
    },
  ],
});

Attachments could be used, for example, when:

• Sending a PDF created in code
• Receiving an attachment and then sending it along.
• Receiving an attachment, sending it to OpenAI, and then emailing it.

Headers#

You can set custom headers in emails that you send:

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

console.log(
  await email({
    text: "Hi",
    headers: {
      "X-Custom-Header": "xxx",
    },
  }),
);

This is also documented in our REST API, and supported in the SDK.

Limitations#

Email sending is currently rate-limited to 100/minute.

Upstream#

std/email is powered internally by Sendgrid.