Skip to main content

API Reference

The Generic Relayer API enables developers to integrate email-driven blockchain actions into their applications.

This API serves as the bridge between traditional email communication and blockchain transactions, allowing users to authorize and execute smart contract functions through email verification.

You can find the source code for the Generic Relayer API here.

Submit Command

Request Parameters

contractAddress (string)

Address of your deployed smart contract containing the command.


dkimContractAddress (string)

Address of the DKIMVerification contract for email authentication.


accountCode (string)

A random uint256 value used to derive the user's address from their email address using CREATE2.


codeExistsInEmail (boolean)

Include accountCode in the email body (true or false).


functionAbi (object)

ABI of the function to execute.


commandTemplate (string)

Command string as defined in your contract (e.g., "Emit string {string}").


commandParams (array)

Parameters to fill into the command template.


templateId (string)

Unique identifier for the command template.


remainingArgs (array)

Additional arguments not included in the command template.


emailAddress (string)

Your email address where the command will be sent.


subject (string)

Subject line of the email.


body (string)

Body content of the email.


chain (string)

Blockchain network (e.g., "sepolia").

Response Fields

message (string)

A confirmation message indicating the email has been sent.


request_id (string)

A unique identifier for the request.


status (string)

The status of the request. Possible value: "success".

Endpoint

POST https://relayer.zk.email/api/submit

Request

Edit Request

Response

(Example)
{
"message": "email sent",
"request_id": "fecfac34-3333-4cd3-bdaa-1b349aea0699",
"status": "success"
}

Request Status

Request Parameters

id (string)

UUID of the request to check status for.

Response Fields

message (string)

A message indicating the request status.


request (object)

An object containing details about the request, including:

  • id (string): UUID of the request.
  • status (string): Current status of the request. Possible values include "Finished" and others.
  • updatedAt (string): ISO 8601 formatted timestamp of when the status was last updated.
  • emailTxAuth (object): Original request details including:
    • emailAddress: Recipient email address
    • subject: Email subject
    • body: Email body content
    • chain: Blockchain network
    • contractAddress: Smart contract address
    • dkimContractAddress: DKIM contract address
    • accountCode: Account code
    • codeExistsInEmail: Boolean indicating if code exists in email
    • functionAbi: ABI of the executed function
    • commandTemplate: Original command template
    • commandParams: Parameters used in the command
    • templateId: Template ID
    • remainingArgs: Additional arguments

Endpoint

GET https://relayer.zk.email/api/status/:id

Request

Edit Request

Response

(Example)
{
"message": "request status",
"request": {"emailTxAuth":{"accountCode":"0x22a2d51a892f866cf3c6cc4e138ba87a8a5059a1d80dea5b8ee8232034a105b7","body":"Sending a hello world!","chain":"sepolia","codeExistsInEmail":true,"commandParams":["testing"],"commandTemplate":"Emit string {string}","contractAddress":"0xefb56bb5771cde84f487391b6c0f9ff1694d2631","dkimContractAddress":"0xc3f15f5cc76a86f97ef8bc2d5070b6725d8992ce","emailAddress":"saul.garces09@gmail.com","functionAbi":{"inputs":[{"components":[{"type":"uint256"},{"type":"bytes[]"},{"type":"uint256"},{"components":[{"type":"string"},{"type":"bytes32"},{"type":"uint256"},{"type":"string"},{"type":"bytes32"},{"type":"bytes32"},{"type":"bool"},{"type":"bytes"}],"type":"tuple"}],"internalType":"struct EmailAuthMsg","name":"emailAuthMsg","type":"tuple"},{"internalType":"address","name":"owner","type":"address"},{"internalType":"uint256","name":"templateIdx","type":"uint256"}],"name":"emitEmailCommand","outputs":[],"stateMutability":"nonpayable"},"remainingArgs":[{"Address":"0x9401296121fc9b78f84fc856b1f8dc88f4415b2e"},{"Uint":"0x0"}],"subject":"Hello World","templateId":"0x25d6c3eada7b2926c822bbfebfc3173123afb205cf093a8cae6622a56712f8a"},"id":"fecfac34-3333-4cd3-bdaa-1b349aea0699","status":"Finished","updatedAt":"2024-10-25T09:49:10.922319"}
}

Health Check

Response Fields

message (string)

A greeting message from the API.


status (string)

The status of the health check. Possible value: "success".

Endpoint

GET https://relayer.zk.email/api/healthz

Request


Response

(Example)
{
"message": "Hello from ZK Email!",
"status": "success"
}