API documentation

Get your publishable key

To add inbox links to your app, you'll need a publishable key. Once you've set up an account, you'll be given a publishable key to get started.

Get a publishable key

Integrations

There are three integration paths for setting up inbox links.

The web component integration is the quickest. Place a snippet of HTML into your app and you're good to go. Fit the inbox link to your app using HTML and CSS.

If you want the data (link, icon, and provider name) use the JavaScript API. It takes a bit of scripting but you can build something totally custom.

Lastly, if you're using React.js, there's the React API with TypeScript support.

Web component

Add the <inbox-link/> to your webpage. Replace the pk_YOUR_KEY with a publishable key from your account.


          <script src="https://js.linktoinbox.com/v1/inbox-link.js"></script>
<inbox-link
  publishable-key="pk_YOUR_KEY"
  recipient-address="customer@address.com"
  from-address="your@app.com"
/>

Add details about the email sent to the recipient to the <inbox-link/>. All email details are optional. Provide as many details as you can for more precise links.

The appearance of the inbox link can also be customized to fit your use case.

Attribute	Description
`publishable-key`	The publishable key required to use the API. Create an account to get yours.
Email details
`recipient-address`	The recipient's email address.
`from-address`	The email address the email is sent from.
`subject`	The subject line of the email.
`message-id`	The message ID (`Message-ID`) of the email as defined in the RFC 822 specification.
`message-sent-at`	The approximate date and time the message was sent in ISO 8601 format.
Appearance options
`icon`	The email provider's icon is shown by default. Set `icon="hidden"` to hide the icon.
`template`	The link text. The default text is `"Open {provider}"`. The `{provider}` bit will be replaced with the email provider's name, e.g. Gmail.
`fallback-text`	The text displayed when no link is available. The default text is `"Check your inbox"`.

The inbox link can be customized even more using CSS:


          inbox-link {
  /* Style the inbox link */
}

inbox-link.link-not-available {
  /* Styles when there is no inbox link */
}

/* Style parts of the inbox link */
inbox-link::part(link) {}
inbox-link::part(icon) {}
inbox-link::part(text) {}
inbox-link::part(external-link-indicator) {}

JavaScript API

Create the API client with makeLinkToInboxClient. Replace the pk_YOUR_KEY with a publishable key from your account.


          <script src="https://js.linktoinbox.com/v1/web-api.js"></script>


          const linkToInbox = makeLinkToInboxClient({
  publishableKey: "pk_YOUR_KEY"
})

const result = await linkToInbox.getInboxLink({
  recipientAddress: "customer@address.com"
  fromAddress: "your@app.com",
})

switch (result.type) {
  case 'link_not_available':
    // Handle the case where this is no inbox link
    // For example, show alternate text like "Check your inbox"
    break
  case 'link_data':
    const {link, icon, providerName} = result.data
    // ...
}

Call getInboxLink with details about the email sent to recipient. All details are optional. Provide as many details as you can for more precise links.

Option	Description
`recipientAddress`	The recipient's email address.
`fromAddress`	The email address the email is sent from.
`subject`	The subject line of the email.
`messageId`	The message ID (`Message-ID`) of the email as defined in the RFC 822 specification.
`messageSentAt`	The approximate date and time the message was sent in ISO 8601 format.

React API

Install the react-inbox-link package. Replace the pk_YOUR_KEY with a publishable key from your account.


          import {InboxLink, useInboxLink} from 'react-inbox-link'
const publishableKey = "pk_YOUR_KEY"

// As a component:
<InboxLink
  publishableKey={publishableKey}
  recipientAddress="customer@address.com"
/>

// As a hook:
const inboxLink = useInboxLink(publishableKey, {
  recipientAddress: "customer@address.com"
})

const {link, icon, providerName} = inboxLink.data

The <InboxLink/> component accepts the web component attributes. The useInboxLink hook accepts the JavaScript API options.

Security

Scripts and network calls are always served over HTTPS. Always load scripts directly from js.linktoinbox.com. The scripts do not use iframe elements.

Content Security Policy

If your app has a Content Security Policy, these directives are necessary to load the scripts and make network requests to our servers:


          connect-src: powered-by.linktoinbox.com;
script-src: js.linktoinbox.com;