MyAddress ID · message API

Send messages with MyAddress

A registered application can send messages to its active MyAddress connections without running an email delivery service. Messages appear in each recipient's MyAddress mailbox, and replies return to the sender mailbox you select.

1. Configure the client once

Use the client ID and secret from your existing MyAddress ID integration. Keep them in server-side configuration and call the endpoint only from your server.

import { randomUUID } from 'node:crypto';

const clientId = process.env.MYADDRESS_CLIENT_ID!;
const clientSecret = process.env.MYADDRESS_CLIENT_SECRET!;
const authorization = `Basic ${Buffer.from(
  `${clientId}:${clientSecret}`,
).toString('base64')}`;

type MyAddressMessage = {
  from: string;
  recipients: string[];
  subject?: string;
  text?: string;
  html?: string;
  idempotencyKey?: string;
};

type MyAddressMessageResult = {
  ok: true;
  duplicate: boolean;
  accepted: number;
  invalidRecipients: string[];
};

export async function sendMyAddressMessage({
  idempotencyKey = randomUUID(),
  ...message
}: MyAddressMessage) {
  const response = await fetch('https://id.myaddress.cc/v1/messages', {
    method: 'POST',
    headers: {
      authorization,
      'content-type': 'application/json',
      'idempotency-key': idempotencyKey,
    },
    body: JSON.stringify(message),
  });

  if (!response.ok) {
    throw new Error(
      `MyAddress delivery failed (${response.status}): ${await response.text()}`,
    );
  }

  const result = (await response.json()) as MyAddressMessageResult;
  return { ...result, idempotencyKey };
}

Pass at least one of text or html. The function generates an idempotency key for ordinary one-shot calls and returns it with the delivery result.

2. Handle the result

A 202 response means MyAddress processed the request, but some recipients may have been rejected. accepted is the number of distinct mailboxes that received the message. Inspect invalidRecipients and update or report those connections as appropriate. If duplicate is true, an earlier request with the same idempotency key was already accepted.

3. Retry safely

For queued or otherwise durable delivery, generate and store the idempotency key with the message before the first attempt, then pass it as idempotencyKey. Reuse the same key after a network error, timeout, 429, or 5xx response, using backoff and honoring Retry-After when present. Do not retry another 4xx response until its request or credentials have been corrected.

Addressing

The sender must be an active MyAddress mailbox owned by the account that registered the client. Every recipient must be an active address connected to that client. Identify either one with an OIDC sub, a full myaddress.cc address, or its local part. A request may contain up to 500 recipients. An invalid sender rejects the entire request; invalid recipients do not prevent delivery to the valid ones.