Skip to content

Email Services SDK

Jump to bottom
Long Lam edited this page Apr 8, 2026 · 2 revisions

Welcome to Juno's Email Service! This guide will walk you through the steps required to integrate Juno’s email microservice into your project.

By following this documentation, your team will be able to set up, configure, and send emails directly through Juno’s SDK.

This guide will focus solely on the Email Service SDK interactions. If you are interested in interacting with the Juno API via REST, please refer to the Juno Documentation. When a new release of Juno is deployed, all documentation will be automatically regenerated to ensure it stays up to date.

Prerequisites

  1. Access to Juno: Ensure you have access to the Juno SDK. You’ll need an API key specific to your project to interact with the email service.
  2. Project Registration: Your project should already be registered in Juno. If it’s not, please refer to the Infra Project Registration Guide to get set up.
  3. API Key: You will need an API key generated for your project. This key allows you to authenticate API requests.
  4. Install and Import Juno SDK:
npm install juno-sdk # for projects using npm
pnpm add juno-sdk # for projects using pnpm
yarn add juno-sdk # for projects using yarn
bun install juno-sdk # for projects using bun
import juno from "juno-sdk";

// Call this somewhere in your program before using any of Juno's services
juno.init({
  apiKey: "<your api key>",
  baseURL: "<base url of running juno instance>"
});

// We can then call any of the service methods, e.g. email, file services

Step 1: Setup Juno Email Services

First, you need to connect your SendGrid API key to Juno. This allows Juno to make email API requests through your SendGrid account.

  • Using Juno SDK:
juno.email.setupEmail({
	sendgridKey: "SG.your-sendgrid-api-key"
});

// If successful, you will receive { success: true }
  • Using Juno Dashboard: Navigate to your project's Settings page (/projects/[projectId]/settings) to configure your SendGrid API key. You can also view existing email configurations on this page and update the SendGrid API key for existing configurations.

View created configuration:

You can view your email configuration on the Juno Dashboard Settings page, or retrieve it programmatically:

const projectId: string = "your-project-id";
juno.email.getEmailConfig(projectId);

If successful, you should get an email config with the following structure:

{
	// Email Configuration ID
	"id": number;
	
	// The configured environment
	"environment": string;
	
	// The SendGrid key associated with this config
	"sendgridKey": string;
	
	// The list of registered domains
	"domains": Array<EmailDomain>;
	
	// The list of registered senders
	"senders": Array<EmailSender>;
}

Example value:

{
	"id": 0,
	"environment": "production",
	"sendgridKey": "SG.xxxxxxxx",
	"domains": [
		{
			"domain": "yourcompany.com",
			"subdomain": "mail",
			"sendgridId": 12345,
			"projects": []
		}
	],
	"senders": [
		{
			"username": "noreply",
			"domain": "yourcompany.com",
			"projects": []
		}
	]
}

Step 2: Register Your Domain

To prevent your emails from being marked as spam, you need to register your domain.

  • Using Juno SDK:
juno.email.registerDomain({
	domain: "yourcompany.com",
	subdomain: "mail" // optional - subdomain to use for sending
});

If successful, the method will return an object with the following structure:

{
	// The SendGrid domain ID
	"id": number; 
	
	// Whether the domain is verified
	"valid": string; 
	
	// DNS records required for domain verification
	"records": {
    "mailCname": {
      "valid": boolean;
      "type": string;
      "host": string;
      "data": string;
    };
    "dkim1": {
      "valid": boolean;
      "type": string;
      "host": string;
      "data": string;
    };
    "dkim2": {
      "valid": boolean;
      "type": string;
      "host": string;
      "data": string;
    };
  };
	
	// HTTP status code from SendGrid
	"statusCode": number;
}

Step 3: Add DNS Records and Verify Your Domain

After registering your domain, you need to add the three records from the response to your domain's DNS settings. This is done through your domain registrar's dashboard. For each record, create a new CNAME entry using the host and data values returned in Step 2.

DNS providers can take up to 48 hours to update. Once the records are in place, verify that they are correctly configured:

  • Using Juno SDK:
juno.email.verifyDomain({
	domain: "yourcompany.com"
});

If successful, the method will return the same RegisterDomainResponse structure as Step 2, with the valid field updated to reflect the verification status.

Step 4: Register Your Sender Address

Next, you need to register the sender email address that will appear in the "From" field of your emails. This step requires a physical mailing address to comply with CAN-SPAM regulations.

  • Using Juno SDK:
juno.email.registerSenderAddress({
	email: "noreply@yourcompany.com",
	name: "Your Company",
	replyTo: "support@yourcompany.com", // optional - defaults to the sender email if not provided
	nickname: "Your Company Notifications",
	address: "123 Peachtree St",
	city: "Atlanta",
	state: "GA",
	zip: "30303",
	country: "US"
});

If successful, the method will return an object with the following structure:

{
	// The registered sender email address
	"email": string;
}

Step 5: Send an Email

At this stage, you should have all the setup you need to begin sending emails!

The send method requires the following inputs:

  • sender The sender's email address and optionally a name. Must be a registered sender address
  • recipients A list of recipient objects, each containing an email address and optionally a name
  • subject The subject line of the email
  • contents A list of content objects, where each object specifies the MIME type (e.g., text/plain, text/html) and the value (e.g., the body of the email)

Make sure your email service is set up, domain is verified, and sender address is registered before calling this method

juno.email.sendEmail({
	sender: {
		email: "noreply@yourcompany.com",
		name: "Your Company"
	},
	recipients: [
		{
			email: "recipient@example.com",
			name: "Recipient Name"
		},
		{
			email: "secondrecipient@example.com",
			name: "Second Recipient Name"
		}
	],
	subject: "Welcome to Our Service",
	contents: [
		{
			type: "text/plain",
			value: "Hello! Thanks for signing up."
		},
		{
			type: "text/html",
			value: "<p>Hello! Thanks for signing up.</p>"
		}
	]
});

If successful, the method will return an object with the following structure:

{
	// Whether the email was successfully sent
	"success": boolean;
}

Step 6: Optional Parameters

The sendEmail method supports several optional parameters for more advanced email functionality:

  • CC/BCC: You can include CC and BCC recipients when sending an email. At least one of recipients, cc, or bcc must be provided.
juno.email.sendEmail({
	sender: {
		email: "noreply@yourcompany.com",
		name: "Your Company"
	},
	recipients: [
		{
			email: "recipient@example.com",
			name: "Recipient Name"
		}
	],
	cc: [
		{
			email: "cc-recipient@example.com",
			name: "CC Recipient Name"
		}
	],
	bcc: [
		{
			email: "bcc-recipient@example.com",
			name: "BCC Recipient Name"
		}
	],
	subject: "Email Subject",
	contents: [
		{
			type: "text/html",
			value: "<p>Hello!</p>"
		}
	]
});
  • Reply-To List: You can specify a list of reply-to addresses. When a recipient replies to the email, their reply will be directed to these addresses instead of the sender address.
juno.email.sendEmail({
	sender: {
		email: "noreply@yourcompany.com",
		name: "Your Company"
	},
	recipients: [
		{
			email: "recipient@example.com",
			name: "Recipient Name"
		}
	],
	replyToList: [
		{
			email: "support@yourcompany.com",
			name: "Support Team"
		}
	],
	subject: "Email Subject",
	contents: [
		{
			type: "text/html",
			value: "<p>Hello!</p>"
		}
	]
});

Step 7: Retrieve Email Statistics

You can retrieve email sending statistics for your project. This is useful for monitoring delivery rates, open rates, and other email metrics.

  • Using Juno SDK:
juno.email.getStatistics({
	startDate: "2024-01-01", // required - start date in YYYY-MM-DD format
	endDate: "2024-01-31",   // optional - end date in YYYY-MM-DD format
	limit: 10,               // optional - number of results to return
	offset: 0,               // optional - pagination offset
	aggregatedBy: "day"      // optional - aggregation period (e.g., "day", "week", "month")
});

If successful, the method will return an object with the following structure:

{
	"responses": [
		{
			"date": string; // The date for this statistics entry
			"clicks": number; // Number of links clicked in your emails
			"uniqueClicks": number; // Unique recipients who clicked links
			"opens": number; // Total times your emails were opened
			"uniqueOpens": number; // Unique recipients who opened your emails
			"blocks": number; // Emails not allowed to be delivered by ISPs
			"bounceDrops": number; // Emails dropped because of a bounce
			"bounces": number; // Emails that bounced instead of being delivered
			"deferred": number; // Emails temporarily unable to be delivered
			"delivered": number; // Emails confirmed delivered
			"invalidEmails": number; // Recipients with invalid email addresses
			"processed": number; // Requests via SMTP Relay or API
			"requests": number; // Emails requested to be delivered
			"spamReportDrops": number; // Emails dropped due to spam reports
			"spamReports": number; // Recipients who marked your email as spam
			"unsubscribeDrops": number; // Emails dropped due to unsubscribes
			"unsubscribes": number; // Recipients who unsubscribed
		}
	]
}
  • Using Juno Dashboard:  Navigate to your project's Email Service page (/projects/[projectId]/services/email) to view email analytics visually.

Step 8: Error Handling

@ApiUnauthorizedResponse

→ Make sure your API key has the permission to perform the action

@ApiBadRequestResponse

→ Make sure your input arguments have correct typings and contain all required fields.

→ Make sure any provided ID or name exists in Juno when retrieving data or associating an object with other objects

→ Make sure not to create objects with duplicate IDs or name

The SDK also performs client-side validation before making API requests. The following will throw a JunoValidationError:

  • Providing an empty or blank string for any required field (email, domain, name, etc.)
  • Providing a SendGrid key that does not start with SG
  • Calling sendEmail without at least one recipient, cc, or bcc
  • Calling sendEmail with an empty contents array

@ApiNotFoundResponse

→ Make sure any provided ID or name exists in Juno when retrieving data or associating an object with other objects

@ApiInternalServerErrorResponse

→ A problem occurred on Juno’s side. If this happens, please contact support.

For a full list of possible error codes and detailed descriptions, please refer to the Juno Documentation or contact the infra team for more information.

Infra Support

If you encounter any issues or need help, you can reach out through the following channels:

  • Slack: Join the #gt-infra-support channel for real-time assistance.

Conclusion

You are now ready to integrate Juno's email service into your project! For more advanced configurations or questions, refer to the Juno Documentation or reach out to the infra team for support.

Clone this wiki locally